紀錄工作經驗、相關知識,解決技術相關問題。

Javascript, 新手 Jamp Holes

IME 輸入法組字是什麼?compositionstart、compositionend 事件與中文輸入的前端處理

IME 輸入法組字是什麼?compositionstart、compositionend 事件與中文輸入的前端處理 特色圖片

IME 輸入法組字是什麼?IME(Input Method Editor,輸入法編輯器)負責把按鍵轉成注音、拼音、倉頡這類中日韓文字,使用者在按下確認之前,輸入框裡那串還沒定案的文字就叫組字(composition)。瀏覽器會在組字的開始、更新與結束時各送出 compositionstart、compositionupdate、compositionend 事件;若程式沒分清楚組字中與組字完成,就會出現選字到一半就被搜尋、按 Enter 選字卻把表單送出這類問題。本文從零說明這些名詞與事件,並整理常見處理寫法。

IME 是什麼:把按鍵轉成中文字的輸入法編輯器

W3C UI Events 規範對 IME 的說明是:輸入法編輯器(IME,也稱 front end processor)是一種在按鍵與表意文字或其他字元之間做轉換的應用程式,常用於中文、日文、韓文等東亞語言。

用注音輸入「你好」時,鍵盤上按的是 ㄋㄧˇㄏㄠˇ 這一串按鍵,並不是「你好」這兩個字。中間需要 IME 先接住按鍵、顯示候選字,使用者選定後,才把最後的文字交給輸入框。這個「接住按鍵、還沒交出文字」的階段,就是下一節的組字。

英文鍵盤打 a 就直接得到 a,不需要這個階段,所以只用英文測試表單時,很容易漏掉這類問題。

組字(composition)是什麼

組字指 IME 正在處理、尚未確定的那段文字。以注音為例,輸入框裡帶底線的 ㄋㄧˇ,或是選字視窗裡還沒按下的候選字,都屬於組字狀態。使用者選好字、或按下確認後,組字結束,文字才算真正寫進輸入框。

規範把這段過程稱為 composition session(組字階段):一個 session 由一個 compositionstart、一個或多個 compositionupdate、一個 compositionend 組成。

compositionstart、compositionupdate、compositionend 三個事件

事件何時觸發會冒泡可取消
compositionstart組字系統開始新的組字 session是是
compositionupdate組字 session 中收到新字元是否
compositionend組字系統完成或取消目前的組字 session是否

三個事件的物件都是 CompositionEvent,用 event.data 取得 IME 產生的字元;data 的內容依事件類型而異。規範另外說明:compositionend 的 data 是組字的最終結果,組字被取消時可能是空字串;compositionend 會在輸入框更新之後才送出,所以這時讀 input.value 已經是定案的文字。

下面的程式碼監聽這三個事件,把事件類型、data 與 isComposing 印出來。

const input = document.querySelector('#q');

const log = (e) => {
  console.log(e.type, JSON.stringify(e.data ?? ''), e.isComposing);
};

['compositionstart', 'compositionupdate', 'compositionend'].forEach((type) => {
  input.addEventListener(type, log);
});

下圖是用 Playwright 透過 Chrome DevTools Protocol 的 Input.imeSetComposition 與 Input.insertText 模擬一次 IME 輸入(先送出 ㄋ、再送出 你、最後確認),並同時監聽 beforeinput、input 的畫面。這是程式模擬 IME 的結果,不是用真實的注音輸入法打字,圖中 compositionstart、compositionupdate 的 isComposing 欄位為 undefined,因為 isComposing 只存在於鍵盤與輸入事件上。

Chrome 156、Windows 11 以 CDP 模擬 IME 輸入時 composition 與 input 事件的輸出畫面

從圖中可以看到:組字期間每次更新都有 compositionupdate,最後以 compositionend 結束,event.data 是 你(圖中最後一次 compositionupdate 是 Input.insertText 觸發的)。圖中 beforeinput、input 出現在 compositionupdate 之後,與規範 3.6.6 節範例(beforeinput、compositionupdate、input)的順序不同,所以處理程式不要依賴這幾種事件之間的先後,只依賴 isComposing 與 compositionend。

規範另外有一條:如果 compositionstart 被取消(例如呼叫 preventDefault()),組字 session 應該結束,但 compositionend 仍然一定會送出。

組字期間的 keydown 與 input:isComposing 與 keyCode 229

只靠鍵盤事件判斷不出 IME 的狀態。規範說明,Composition 事件與 Keyboard 事件不一定一對一;鍵盤事件無法判斷輸入法編輯器目前的狀態,要看 CompositionEvent 的 data。

不過規範仍要求組字期間 keydown、keyup 照常送出,並且 isComposing 必須是 true。input 事件的 InputEvent.isComposing 也一樣,為 true 代表事件發生在 compositionstart 之後、對應的 compositionend 之前。所以最直接的判斷方式是:

input.addEventListener('keydown', (e) => {
  if (e.isComposing) {
    return; // 組字中,不處理
  }
  // 一般按鍵處理
});

規範還寫了另一個舊式判斷:keydown 的 keyCode,在 IME 正在處理按鍵輸入時會回傳 229。MDN 的 keydown 事件頁也說明 229 是 keyCode 針對 IME 處理過的事件所設的特殊值。

為什麼不能只看 isComposing?MDN 的說明是:輸入第一個字開啟 IME 時,compositionstart 可能在 keydown 之後才觸發;輸入最後一個字關閉 IME 時,compositionend 可能在 keydown 之前就觸發。這兩種情況下 isComposing 會是 false,但 keyCode 仍是 229,所以 MDN 建議兩個條件一起檢查。

keyCode 本身已經被 MDN 標示為棄用,官方建議改用 KeyboardEvent.code 或 KeyboardEvent.key。不過 MDN 的 keydown 範例仍同時檢查兩者,寫法就是 e.isComposing || e.keyCode === 229。

另外,MDN 提到 Firefox 65 起,keydown 與 keyup 在 IME 組字期間也會觸發,目的是改善中日韓文使用者的跨瀏覽器相容性。

常見問題一:組字中按 Enter 卻把表單送出

使用者用注音打完 ㄋㄧˇ,按 Enter 想確認選字,結果程式把 Enter 當成「送出」。原因是處理程式只看了 e.key === 'Enter',沒有排除組字中的 Enter。

const input = document.querySelector('#q');

input.addEventListener('keydown', (e) => {
  if (e.key !== 'Enter') return;

  // 組字中的 Enter 是用來確認選字,不是送出
  if (e.isComposing || e.keyCode === 229) return;

  console.log('送出:' + input.value);
});

下面用同一段程式,對比「沒有排除組字」與「有排除組字」兩種寫法。畫面中的 Enter 事件是用 new KeyboardEvent('keydown', { key: 'Enter', keyCode: 229, isComposing: true }) 派送的合成事件,用來驗證判斷邏輯,不是真實 IME 產生的事件。

Chrome 156、Windows 11 以合成 KeyboardEvent 對比有無排除組字的 Enter 處理結果

實際的 IME 在各瀏覽器、各作業系統與各輸入法上,Enter 事件送出的順序與屬性不一定相同。本文只引用規範與 MDN 的說明,沒有逐一驗證這些組合,所以上線前仍建議在目標使用者會用的瀏覽器與輸入法上自己試一次。

常見問題二:選字到一半就觸發搜尋

即時搜尋、字數統計這類功能常掛在 input 事件上。用注音輸入時,每選一個音就會觸發 input,此時送出查詢的內容是 ㄋ、ㄋㄧ 這種半成品。

簡單的處理方式是:組字中的 input 先略過,等 compositionend 再處理一次定案的值。

const input = document.querySelector('#q');
let lastQuery = null;

function search(value) {
  if (value === lastQuery) return; // 同一個值不重複查詢
  lastQuery = value;
  console.log('搜尋:' + value);
}

input.addEventListener('input', (e) => {
  if (e.isComposing) return; // 組字中,先不查
  search(input.value);
});

input.addEventListener('compositionend', () => {
  search(input.value); // 規範:compositionend 在輸入框更新之後送出
});

lastQuery 的比對是為了避免同一個值查兩次:規範說明 compositionend 沒有 DOM 更新,不會再送 beforeinput 與 input,但各瀏覽器實際送出的順序可能不同,加上比對比較保險。

下圖同樣是用 CDP 模擬 IME 輸入後的結果:組字中的三次 input(isComposing 都是 true)都被略過,只在 compositionend 搜尋一次 你。

Chrome 156、Windows 11 以 CDP 模擬 IME 輸入時只在 compositionend 搜尋一次的輸出畫面

即時搜尋常見的 Debounce(防抖)與競態處理,不在本文範圍。想了解 beforeinput、input、change、blur 的完整觸發順序與防抖寫法,詳細可前往〈搞懂 HTML input 事件生命週期:beforeinput、input、change 與 blur 的觸發時機全解析〉。

什麼時候不需要處理組字

下列情況通常不用特別處理 composition:

  • 只在 change 或 blur 時才處理資料:這兩個事件是在輸入完成後才觸發,不會碰到組字中的半成品。
  • 輸入欄位只接受英文與數字:使用者通常不需要開 IME。
  • 全形字與半形字的轉換:這是輸入完成後對字串做的處理,與組字事件無關,可前往〈JS 半形轉全形與 String.prototype.normalize 字元轉換〉。

重點整理

  • IME 負責把按鍵轉成中日韓文字;組字(composition)是 IME 還沒交出定案文字的那段過程。
  • 一次組字由 compositionstart、一個或多個 compositionupdate、compositionend 組成;event.data 取得 IME 產生的字元。
  • 判斷 keydown、input 是否在組字中,用 isComposing;Enter 這類按鍵要再加 keyCode === 229,因為 compositionstart 與 compositionend 可能與 keydown 順序錯開。
  • 即時搜尋等功能:組字中略過,在 compositionend 處理定案值,並避免同一個值重複處理。
  • 各瀏覽器與輸入法的細節可能不同,正式上線前在目標環境自行確認。

參考資料與延伸閱讀

發佈留言