自訂輸入法編輯器 (IME) 要求

這些指南和要求可以協助您開發自訂輸入法編輯器 (IME)，從而協助使用者輸入使用標準 QWERTY 鍵盤難以輕鬆表示的語言文字。

如需 IME 的概觀，請參閱輸入法編輯器 (IME)。

預設 IME

使用者可以選擇任何一種使用中的 IME ([設定 -> 時間 & 語言 -> 語言 -> 慣用語言 -> 語言套件 - 選項]) 做為慣用語言的預設 IME。

在 [語言選項] 設定畫面上選取慣用語言的預設鍵盤。

重要

不建議直接寫入登錄來設定自訂 IME 的預設鍵盤。

相容性要求

以下是自訂 IME 的基本相容性需求。

IME 必須與 Windows 應用程式相容

使用 Text Services Framework (TSF) 來實作 IME。 以前，可以選擇使用輸入法管理器 (IMM32) 來執行輸入服務。 現在系統會封鎖使用輸入法管理器 (IMM32) 實作的 IME。

當應用程式啟動時，TSF 會載入使用者目前選取之 IME 的 IME DLL。 載入IME 時，它受到與應用程式相同的應用程式容器限制。 例如：如果應用程式的清單中未要求存取網際網路，則 IME 無法存取網際網路。 此行為可確保 IME 不會違反安全性合約。

TSF 是應用程式與 IME 之間的媒介。 TSF 會將輸入事件傳達給 IME，並在使用者選取字元之後，從 IME 接收輸入字元。

此行為與舊版 Windows 相同，但載入 Windows 應用程式會影響 IME 的潛在功能。

如果 IME 需要在 Windows 應用程式和傳統型應用程式之間提供不同的功能或 UI，請確定 TSF 所載入的 DLL 會檢查要載入的應用程式類型。 在您的 IME 中呼叫 ITfThreadMgrEx::GetActiveFlags 方法，並檢查 TF_TMF_IMMERSIVEMODE 旗標，以便 IME 會根據結果觸發不同的應用程式邏輯。

Windows 應用程式不支援表格文字服務 (TTS) IME。

注意

一些用於產生 TTS IME 的工具所產生的 IME 會被 Windows 標記為惡意軟體。

IME 必須與系統匣相容

沒有語言列可裝載 IME 圖示。 相反地，系統匣上會顯示一個輸入指標，來指示目前的輸入選項。 輸入指標只會顯示 IME 品牌圖示，以指出目前執行的 IME。 此外，IME 品牌圖示的左側還顯示一個 IME 模式圖示，讓使用者執行最常用的 IME 模式切換，例如：開啟或關閉 IME。

輸入指標只會為相容的 IME 顯示 IME 品牌圖示和模式圖示。 不相容的 IME 不會在系統匣中顯示品牌圖示和模式圖示。 相反地，輸入指標會顯示語言縮寫，而不是 IME 品牌圖示。

將 IME 圖示儲存在 DLL 或 EXE 檔案中，而不是獨立 .ico 檔案中。 IME 圖示的設計必須遵循以下 UI 設計指南一節中描述的指南。

IME 品牌圖示

輸入指標會使用 IME 在系統上註冊時所定義的資源識別碼，從 IME DLL 取得 IME 品牌圖示。

IME 模式圖示

某些 IME 可能需要依賴系統匣上顯示的輸入指標來顯示 IME 模式圖示。 在這種情況下，IME 使用 GUID_LBI_INPUTMODE，將 IME 模式圖示傳遞至輸入指標。

將 IME 模式圖示傳遞到系統匣上的輸入指標時，IME 模式圖示的預設大小為 16x16 像素。 UI 縮放比例會遵循 DPI。

將 IME 模式圖示傳遞到 UAC (安全桌面中的使用者帳戶控制) 上的輸入指標時，IME 模式圖示的預設大小為 20x20 像素。 UAC 上 IME 模式圖示的 UI 縮放遵循 PPI。

IME 必須在應用程式容器中工作

某些 IME 函式在應用程式容器中會受到影響。

• 字典檔案 - 通常，IME 具有唯讀字典檔案，以將使用者輸入對應至特定字元。 若要從應用程式容器內部存取這些檔案，IME 必須將這些檔案置於 Program Files 或 Windows 目錄下。 預設情況下，可以從應用程式容器讀取這些目錄，因此 IME 可以存取儲存在這些位置中的字典檔案。 如果 IME 必須將字典檔案儲存在其他位置，則必須明確操作字典檔案的存取控制清單 (ACL) 以允許從應用容器存取。
• 網際網路更新 - 如果您的 IME 需要使用來自網際網路的資料來更新其字典，則它無法在應用程式容器中可靠地完成此操作，因為不一定會允許存取網際網路。 相反地，IME 應該執行另外的傳統型程式，其負責使用來自網際網路的資料來更新字典檔案。
• 即時學習 - 如果IME 在具有網際網路存取權限的應用程式容器中執行，則可以與 IME 通訊的端點不受限制。 在這種情況下，IME 可以使用雲端伺服器提供即時學習服務。 有些 IME 會在使用者輸入時即時下載和上傳使用者輸入。 由於應用程式容器不保證具有網際網路存取權限，因此可能不會總是允許這樣做。
• 在處理序之間共用資訊 - IME 可能需要在不同應用程式容器中的應用程式之間共用關於使用者輸入偏好的資料。 使用 Web 服務在應用程式之間共用資料。

重要

如果嘗試規避應用程式容器安全性規則，則 IME 可能會被視為惡意軟體並遭到封鎖。

IME 和觸控式鍵盤

IME 必須確保其候選窗格的 UI 和其他 UI 元素不會繪製在觸控式鍵盤底下。 觸控式鍵盤顯示在比所有應用程式更高的 Z 順序帶區中，並且 IME UI 顯示在與可使用此 IME UI 的應用程式相同的 Z 順序帶中。 因此，觸控式鍵盤可以重疊並隱藏 IME UI。 在大部分情況下，應用程式應根據觸控式鍵盤來調整其視窗大小。 如果應用程式不調整大小，IME 仍可以使用 InputPane API 取得觸控式鍵盤的位置。 IME 會查詢 Location 屬性，或註冊處理常式來處理觸控式鍵盤的「顯示與隱藏」事件。 使用者每次點選編輯欄位時，即使目前已顯示觸控式鍵盤，仍會引發「顯示」事件。 IME 繪製候選 UI 或其他 UI 之前，可以使用此 API 取得觸控式鍵盤使用的螢幕空間，並重新排列 IME UI 以避免其繪製在觸控式鍵盤下方。

指定慣用的觸控式鍵盤配置

IME 可以指定要使用的觸控式鍵盤配置，並啟用 IME 以使用觸控最佳化版面配置。 此功能僅限於韓文、日文、簡體中文和繁體中文輸入語言的 IME。

觸控式鍵盤支援七種配置，其中三種是經典版面配置，另外四種是觸控最佳化版面配置。 經典版面配置的外觀和行為類似於實體鍵盤。

所有三種經典版面配置都能用於以不同形式輸入繁體中文：

• 注音輸入
• 倉頡輸入
• 大易輸入

除了經典版面配置之外，每個韓文、日文、簡體中文和繁體中文輸入語言都有一個觸控最佳化版面配置。

若要使用這項功能，IME 必須實作 ITfFnGetPreferredTouchKeyboardLayout 介面，此介面是由 IME 使用 Text Services Framework ITfFunctionProvider API 匯出。

如果 IME 不支援 ITfFnGetPreferredTouchKeyboardLayout 介面，則使用 IME 會產生觸控式鍵盤顯示的語言採用預設經典版面配置。

如果 IME 需要將其中一個經典版面配置設定為慣用的版面配置，則 IME 只需支援 ITfFnGetPreferredTouchKeyboardLayout 和 ITfFunctionProvider 介面即可，無需執行任何其他動作。 但是，如果 IME 要使用觸控最佳化版面配置，則還需執行額外的動作，下一節會說明這部分。

觸控最佳化版面配置

在IME「開啟」和「關閉」兩種轉換模式下，韓文、日文、簡體中文和繁體中文輸入語言的觸控最佳化鍵盤會顯示不同的版面配置。 觸控式鍵盤上有一個按鍵，可用於將 IME 轉換模式設為「開啟」或「關閉」，但鍵盤的 IME 模式也可能隨著編輯控制項之間的焦點變更而變更。

日文、簡體中文和繁體中文輸入語言的觸控最佳化鍵盤包含 IME 用來瀏覽候選頁的一個或多個按鍵。 對於日文和簡體中文，候選頁面鍵顯示在觸控最佳化版面配置上。 對於繁體中文，前一個和下一個候選頁面都各有一個按鍵。

按下這些按鍵時，觸控式鍵盤會呼叫 SendInput 函式，將下列 Unicode 專用區字元傳送到焦點應用程式，IME 會攔截並採取行動：

• 下一頁 (0xF003) - 在日文和簡體中文的觸控最佳化鍵盤上按候選頁鍵，或在繁體中文的觸控最佳化鍵盤上按下一頁鍵時，發送此字元。
• 上一頁 (0xF004) - 在日文和簡體中文的觸控最佳化鍵盤上同時按候選頁鍵和Shift 鍵，或在繁體中文的觸控最佳化鍵盤上按上一頁鍵時，發送此字元。

這些字元會以 Unicode 輸入的形式傳送。 下一段詳細介紹如何在按鍵事件接收器通知期間擷取 Text Services Framework IME 將接收的字元資訊。 這些字元值未在任何標頭檔中定義，因此必須在程式碼中定義它們。

若要攔截鍵盤輸入，IME 必須註冊為按鍵事件接收器。 對於使用 SendInput 函式所產生的 Unicode 輸入，ITfKeyEventSink 回撥 (OnKeyDown、OnKeyUp、OnTestKeyDown、OnTestKeyUp) 的 WPARAM 參數一律包含虛擬按鍵VK_PACKET，而不會直接識別字元。

實作下列呼叫順，序以存取字元：

// Keyboard state
BYTE abKbdState[256];
if (!GetKeyboardState(abKbdState))
{
   return 0;
}

// Map virtual key to character code
WCHAR wch;
if (ToUnicode(VK_PACKET, 0, abKbdState, &wch, 1, 0) == 1)
{
   return wch;
}

IME 搜尋整合

透過整合搜尋合約和搜尋窗格，為使用者提供搜尋功能。

搜尋窗格和 IME 建議

搜尋窗格是使用者在其所有應用程式中執行搜尋的中心位置。 Windows 為 IME 使用者提供獨特的搜尋體驗，將相容的 IME 與 Windows 整合，從而提高搜尋效率和可用性。

當使用者使用與搜尋功能相容的IME 來輸入內容時，有兩個主要優勢：

• IME 與搜尋體驗之間的無縫互動。 IME 候選項會在搜尋方塊下內嵌顯示，而不會遮擋搜尋建議。 使用者可以使用鍵盤在搜尋方塊、IME 轉換候選項和搜尋建議之間順暢地瀏覽。
• 更快地存取應用程式提供的相關結果和建議。 應用程式有權存取所有目前的轉換候選項，以提供更多相關建議。 為了更好地排列搜尋建議的優先順序，請按相關性順序向應用程式提供轉換。 使用者只需輸入注音而無需轉換，即可找到並選擇他們想要的結果。

如果 IME 符合以下條件，即可與整合式搜尋體驗相容：

• 與 Windows 樣式殼層相容。
• 實作 TSF UILess 模式 API。 如需詳細資訊，請參閱 UILess 模式概觀。
• 實作 TSF 搜尋整合 API、ITfFnSearchCandidateProvider 和 ITfIntegratableCandidateListUIElement。

在搜尋窗格中啟動相容的 IME 時，它將處於 UIless 模式且無法顯示 UI。 相反，它會將轉換候選項傳送到 Windows，這會顯示在內嵌候選清單控制項中顯示，如上一個螢幕截圖所示。

此外，IME 也會發送應該用於執行目前搜尋的候選項。 這些候選項可以與轉換候選項相同，也可以根據搜尋自訂。

良好的搜尋候選項符合下列條件：

• 沒有前置詞重疊。 例如，「北京」對於「北京大學」來說是多餘的，因為其中一個是另一個的前置詞。
• 沒有多餘的候選項。 任何多餘的候選項對於搜尋都是無用的，因為它不能協助篩選結果。 例如，任何與「北京大學」相符的結果也會與「北京」相符。
• 無預測候選項，只能轉換。 例如，如果使用者鍵入「ㄅㄟ」，IME 能返回候選項「北」，但不能返回「北京大學」。 通常，預測候選項太具有限制性。

不符合條件的 IME 與其他控制項一樣不相容於搜尋顯示，且無法利用 UI 整合和搜尋候選項。 只有在使用者完成撰寫之後，應用程式才會收到查詢。

當支援搜尋合約的應用程式收到查詢時，查詢事件會含有包括所有已知替代項目的「queryTextAlternatives」陣列，這些替代項目從最相關 (可能) 到最不相關 (不可能) 依序排列。

提供替代項目後，應用程式應會將每個替代項目視為一個查詢，並傳回與每個替代項目相符的所有結果。 應用程式的行為應如同使用者同時發出多個查詢一樣，基本上是向提供結果的服務發出「or」查詢。 出於效能方面的考慮，應用程式通常會將最相關替代項目的相符結果限制在 5 到 20 個之間。

UI 設計方針

所有IME 都必須遵循設計和程式碼 Windows 應用程式中所述的使用者體驗指導方針。

勿使用自黏視窗

IME 視窗應僅在需要時顯示，不應該一直顯示。 當使用者不需要輸入時，IME 視窗不應該顯示。 IME 視窗不應該是全螢幕視窗。 IME 視窗不應該互相重疊。 視窗應採用 Windows 樣式設計，並遵循 UI 縮放比例。

IME 圖示

IME 圖示有兩種類型：品牌圖示和模式圖示。 所有 IME 圖示只能採用黑白兩色設計。 新的 IME 圖示借用系統匣圖示的 Glyphic 外觀。 此樣式已建立，所有語言都可以使用它來完善相似的外觀，同時也能彼此區分。

IME 圖示的檔案格式為 ICO。 必須提供以下圖示大小。

• 16x16 像素
• 20x20 像素
• 24x24 像素
• 32x32 像素
• 40x40 像素
• 48x48 像素

確保所有解析度都提供具有 Alpha 色板的 32 位元圖示。

IME 品牌圖示透過一個白色框及其中放置的一個以現代字樣呈現的印刷樣式來定義。 每個語言團隊都會選擇一種定義字形。 字形是黑色的。 框的外邊框為 1 像素，顏色為黑色且不透明度為 50%。 「新」版本由框左上角的圓角所定義。

IME 模式圖示由一個採用現代字樣的白色印刷字形及大小為 1 像素、不透明度為 50% 的黑色外邊框所定義。

Icon	描述
	繁體中文倉頡的 IME 品牌圖示範例。
	繁體中文倉頡的 IME 品牌圖示範例。
	ME 模式圖示範例。

擁有的視窗

若要顯示候選 UI，IME 必須將其視窗設定為擁有的窗口，以便在目前執行的應用程式上顯示。 使用 ITfContextView::GetWnd 方法來擷取要擁有的視窗。 如果 GetWnd 傳回錯誤或 NULLHWND，請呼叫 GetFocus 函式。

if (FAILED(pView->GetWnd(&parentWndHandle)) || (parentWndHandle == nullptr)) { parentWndHandle = GetFocus(); }

與消失關閉表面的 IME 候選視窗互動

彈出式視窗的關閉模型稱為「消失關閉」，因為使用者可以輕鬆關閉這類視窗。 為了讓 IME 在 Windows 互動模型中正常運作，IME 視窗必須採用消失關閉模型。

為了採用消失關閉模型，IME 必須使用 NotifyWinEvent 函式或類似函式來引發三個新的 Windows 事件。 這些新事件包括：

• EVENT_OBJECT_IME_SHOW - IME 變成可見時引發此事件。
• EVENT_OBJECT_IME_HIDE - IME 隱藏時引發此事件。
• EVENT_OBJECT_IME_CHANGE - IME 移動或更改大小時引發此事件。

宣告相容性

IME 使用 ITfCategoryMgr::RegisterCategory 為其 IME 註冊 GUID_TFCAT_TIPCAP_IMMERSIVESUPPORT 類別，以此宣告其相容性。

將預設 IME 模式設定為開啟

我們為 IME 提供了更好的 UX。

傳統型應用程式的 DPI 縮放支援

透過增強的 DPI 縮放支援，可以查詢每個傳統型程式的已宣告 DPI 感知層級，從而判斷是否需要縮放 UI。 在多重監視器案例中，Windows 會根據每個監視器的不同 DPI 設定適當縮放 UI。

由於 IME 在每個應用程式處理序的內容中執行，因此不應為 IME 宣告 DPI 感知層級。 這可確保 IME 在目前程式的 DPI 感知層級中執行。

為了確保所有 IME UI 元素與正在執行程式的 UI 元素具有相同的縮放比例，必須對不同 DPI 值做出適當回應。

注意

為了確保與新的傳統型應用程式保持一致性，IME 應支援每個監視器的 DPI 感知，但不應宣告本身的感知層級。 系統會在每個案例中判斷適當的縮放要求。

如需傳統型應用程式 DPI 縮放支援要求的詳細資訊，請參閱高 DPI。

安裝 IME

如果使用 Microsoft Visual Studio 建置 IME，請使用第三方安裝程式 (例如：Flexera Software 的 InstallShield) 為 IME 建立安裝體驗。

以下步驟示範如何使用 InstallShield 為 IME DLL 建立安裝專案。

• 安裝 Visual Studio。
• 啟動 Visual Studio。
• 在 [檔案] 功能表中，指向 [新增]，然後選取 [專案]。 [新增專案] 對話方塊隨即開啟。
• 在左窗格中，瀏覽至 [範本] > [其他專案類型] > [安裝和部署]，按一下 [啟用 InstallShield 限量版]，然後按一下 [確定]。 遵循安裝指示進行。
• 重新啟動 Visual Studio。
• 開啟 IME 解決方案 (.sln) 檔案。
• 在 [方案總管] 中，按一滑鼠右鍵，指向 [新增]，然後選擇 [新專案]。 [新增專案] 對話方塊隨即開啟。
• 在左側樹狀結構檢視控制項中，瀏覽至 [範本] > [其他專案類型] > [InstallShield 限量版]。
• 在中間視窗中，按一下 [InstallShield 限量版專案]。
• 在 [名稱] 文字方塊中輸入「SetupIME」，然後按一下 [確定]。
• 在 [專案助理] 對話方塊中，按一下 [應用程式資訊]。
• 填寫公司名稱和其他欄位。
• 按一下 [應用程式檔案]。
• 在左側窗格中，以滑鼠右鍵按一下 [INSTALLDIR] 資料夾，然後選取 [新增資料夾]。 將資料夾命名為「Plugins」。
• 按一下 [加入檔案]。 瀏覽至您的 IME DLL，並將它新增至「Plugins」資料夾。 對 IME 字典重複此步驟。
• 以滑鼠右鍵按一下 IME DLL，然後選取 [屬性]。 [屬性] 對話方塊隨即開啟。
• 在 [屬性] 對話方塊中，按一下 [COM & .NET 設定] 索引標籤。
• 在 [註冊類型] 底下，選取 [自我註冊]，然後按一下 [確定]。
• 建置方案。 IME DLL 已建置，而 InstallShield 會建立 setup.exe 檔案，讓使用者能夠在 Windows 上安裝 IME。

若要建立您\自己的安裝體驗，請在安裝期間呼叫 ITfInputProcessorProfileMgr::RegisterProfile 方法來註冊 IME。 請勿直接寫入登錄項目。

如果 IME 必須在安裝之後立即使用，請呼叫 InstallLayoutOrTip，將 IME 新增至使用者啟用的輸入法，並對 psz 參數使用下列格式：

<LangID 1>:{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

IME 協助工具

實作以下慣例，使 IME 符合協助工具要求，並使用朗讀程式。 若要使候選項清單可供存取，IME 必須遵循此慣例。

• 候選項清單的 UIA_AutomationIdPropertyId 必須為「IME_Candidate_Window」 (轉換候選項清單) 或「IME_Prediction_Window」 (預測候選項清單)。
• 當候選項清單顯示和消失時，它將分別引發 UIA_MenuOpenedEventId 和 UIA_MenuClosedEventId 類型的事件。
• 當目前所選的候選項發生變更時，候選項清單將引發 UIA_SelectionItem_ElementSelectedEventId。 所選取元素的 UIA_SelectionItemIsSelectedPropertyId 屬性應為 TRUE。
• 候選清單中每個項目的 UIA_NamePropertyId 必須是候選項目的名稱。 可以透過 UIA_HelpTextPropertyId 選擇性地提其他資訊，以區分候選項。

相關主題

• 輸入法 (IME)
• ITfFnGetPreferredTouchKeyboardLayout
• ITfCompartmentEventSink
• ITfThreadMgrEx::GetActiveFlags
• ITfContextView::GetWnd
• TF_INPUTPROCESSORPROFILE
• ITfFnSearchCandidateProvider
• ITfIntegratableCandidateListUIElement
• SendInput
• 協助工具