自定义输入法编辑器 (IME) 要求Custom Input Method Editor (IME) requirements

这些指导原则和要求可帮助您开发自定义的输入法编辑器 (IME) ,以帮助用户输入不能在标准键盘上轻松表示的语言的文本。These guidelines and requirements can help you to develop a custom Input Method Editor (IME) to help a user input text in a language that can't be represented easily on a standard QWERTY keyboard.

有关 Ime 的概述,请参阅 输入法编辑器 (IME) For an overview of IMEs, see Input Method Editor (IME).

默认 IMEDefault IME

用户可以选择其任何活动 Ime (设置-> 时间 & 语言 > 语言 > 首选语言-> 语言包选项) 为其首选语言的默认 IME。A user can select any of their active IMEs (Settings -> Time & Language -> Language -> Preferred languages -> Language pack - Options) to be the default IME for their preferred language.

首选语言设置

选择首选语言的 "语言选项" 设置屏幕上的默认键盘。Select the default keyboard on the Language options settings screen for the preferred language.

首选语言键盘

重要

我们不建议直接写入注册表来设置自定义 IME 的默认键盘。We do not recommend writing directly to the registry to set the default keyboard for your custom IME.

兼容性要求Compatibility requirements

下面是自定义 IME 的基本兼容性要求。The following are the basic compatibility requirements for a custom IME.

IME 必须与 Windows apps 兼容IME must be compatible with Windows apps

使用 文本服务框架 (TSF) 来实现 ime。Use the Text Services Framework (TSF) to implement IMEs. 以前,你可以选择使用 输入法管理器 (IMM32) 用于输入服务。Previously, you had the option of using the Input Method Manager (IMM32) for input services. 现在,系统会阻止使用输入法管理器实现的 Ime (IMM32) 。Now the system blocks IMEs that are implemented by using Input Method Manager (IMM32).

当应用程序启动时,TSF 将为用户当前选择的 IME 加载 IME DLL。When an app starts, TSF loads the IME DLL for the IME that's currently selected by the user. 加载 IME 后,它将受到与应用相同的应用容器限制。When an IME is loaded, it's subject to the same app container restrictions as the app. 例如,如果应用程序未在其清单中请求 Internet 访问权限,则 IME 无法访问 Internet。For example, an IME can't access the Internet if an app hasn't requested Internet access in its manifest. 此行为可确保 Ime 不会违反安全协定。This behavior ensures that IMEs can't violate security contracts.

TSF 是应用程序和 IME 之间的中介。TSF is the intermediary between the app and your IME. TSF 向 IME 传达输入事件,并在用户选择字符后接收输入字符。TSF communicates input events to the IME and receives input characters back from the IME after the user has selected a character.

此行为与以前版本的 Windows 相同,但加载到 Windows 应用会影响 IME 的可能功能。This behavior is the same as previous versions of Windows, but being loaded into a Windows app affects the potential capabilities of an IME.

如果输入法需要在 Windows 应用和桌面应用之间提供不同的功能或 UI,请确保 TSF 加载的 DLL 检查要加载到的应用类型。If your IME needs to provide different functionality or UI between Windows apps and desktop apps, ensure that the DLL that’s loaded by TSF checks which type of app it's being loaded into. 调用 IME 中的 ITfThreadMgrEx:: GetActiveFlags 方法,并检查 TF_TMF_IMMERSIVEMODE 标志,使 IME 根据结果触发不同的应用程序逻辑。Call the ITfThreadMgrEx::GetActiveFlags method in your IME and check the TF_TMF_IMMERSIVEMODE flag, so your IME triggers different application logic depending on the result.

Windows 应用不支持表文本服务 (TTS) Ime。Windows apps do not support Table Text Service (TTS) IMEs.

备注

某些用于生成 TTS Ime 的工具会生成由 Windows 标记为恶意软件的 Ime。Some tools for generating TTS IMEs produce IMEs that are marked as malware by Windows.

IME 必须与系统托盘兼容IME must be compatible with the system tray

没有用于托管 IME 图标的语言栏。There is no language bar to host IME icons. 相反,系统任务栏上会显示一个指示当前输入选项的输入标记。Instead, an Input Indicator shows on the system tray that indicates the current input option. 输入指示器只显示 IME 标记图标,以指示当前正在运行的 IME。The Input Indicator shows only the IME branding icon to indicate the currently running IME. 此外,用户可以在 IME 标记图标的左侧显示一个 IME 模式图标,用户可以使用该图标来执行最常用的 IME 模式切换,例如打开或关闭 IME。Also, there's one IME mode icon that shows on the left of the IME branding icon for users to perform the most commonly used IME mode switch, like turning the IME on or off.

输入指示器仅显示兼容 Ime 的 IME 标记图标和模式图标。The Input Indicator shows the IME branding icon and mode icon only for compatible IMEs. 不兼容的 Ime 不会在系统托盘中显示品牌图标和模式图标。IMEs that aren't compatible don't have the branding icon and mode icon displayed in the system tray. 相反,输入指示器显示语言缩写,而不是 IME 标记图标。Instead, the Input Indicator shows the language abbreviation instead of the IME branding icon.

将 IME 图标存储在 DLL 或 EXE 文件中,而不是单独的 .ico 文件中。Store the IME icons in a DLL or EXE file, instead of a standalone .ico file. IME 图标的设计必须遵循以下 UI 设计指南部分中所述的指导原则。The design of IME icons must follow the guidelines described in the following UI design guidelines section.

IME 标记图标IME branding icon

输入指示器在系统上注册输入法时,通过使用 IME 定义的资源 ID,从 IME DLL 中获取 IME 标记图标。The Input Indicator gets the IME branding icon from the IME DLL by using the resource ID defined by the IME when it was registered on the system.

IME 模式图标IME mode icon

某些输入法可能需要依赖于系统托盘上显示的输入指示器来显示 IME 模式图标。Some IMEs may need to rely on the Input Indicator showing on the system tray to display the IME mode icon. 在这种情况下,IME 使用 GUID_LBI_INPUTMODE 将 IME 模式图标传递到输入指示器。In this case, the IME passes the IME mode icon to the Input Indicator by using GUID_LBI_INPUTMODE.

将 IME 模式图标传递到系统任务栏上的输入指示器时,IME 模式图标的默认大小为16x16 像素。When passing the IME mode icons to the Input Indicator on the system tray, the default size of the IME mode icon is 16x16 pixels. UI 缩放遵循 DPI。The UI scaling follows DPI.

将 IME 模式图标传递到安全桌面) 中的 UAC (用户帐户控制时,IME 模式图标的默认大小为20x20 像素。When passing the IME mode icon to the Input Indicator on UAC (User Account Control in Secure Desktop), the default size of the IME mode icon is 20x20 pixels. UAC 上的 IME 模式图标的 UI 缩放在 PPI 之后。The UI scaling for IME mode icon on UAC follows PPI.

IME 必须在应用容器中运行IME must work in app container

某些 IME 函数在应用容器中受到影响。Some IME functions are affected in an app container.

  • 字典文件 -通常,ime 具有只读字典文件,用于将用户输入映射到特定字符。Dictionary Files - Frequently, IMEs have read-only dictionary files to map user input to specific characters. 若要从应用容器内部访问这些文件,IME 必须将它们放在程序文件或 Windows 目录下。To access these files from inside an app container, your IME must place them under the Program Files or Windows directories. 默认情况下,可以从应用容器读取这些目录,因此 Ime 可以访问存储在这些位置的字典文件。By default, these directories can be read from an app container, so IMEs can access dictionary files that are stored in these locations. 如果 IME 必须将字典文件存储在其他位置,则必须显式操作 访问控制列表 (ACL) 字典文件,以允许从应用容器访问。If your IME must store the dictionary file somewhere else, it must explicitly manipulate the Access Control Lists (ACL) of the dictionary files to allow access from app containers.
  • Internet 更新 -如果你的 IME 需要使用来自 Internet 的数据更新其字典,则无法在应用程序容器中可靠地执行此操作,因为不会始终允许 Internet 访问。Internet Updating - If your IME needs to update its dictionaries using data from the Internet, it can't reliably do so inside an app container, because Internet access isn't always permitted. 相反,IME 应运行单独的桌面进程,该进程负责使用 Internet 上的数据更新字典文件。Instead, your IME should run a separate desktop process that's responsible for updating the dictionary files with data from the Internet.
  • 动态学习 -如果在具有 Internet 访问权限的应用容器中运行了 ime,则 ime 可以与之通信的终结点没有限制。On-the-fly learning - If an IME is running in an app container that has Internet access, there's no restriction on the endpoints that the IME can communicate with. 在这种情况下,IME 可以使用云服务器来提供实时学习服务。In this case, an IME can use a cloud server to provide on-the-fly learning services. 某些 Ime 会在用户键入内容时,动态下载和上传用户输入。Some IMEs download and upload user input on the fly, while the user is typing. 由于不能在应用容器中保证 Internet 访问,因此不一定会允许这样做。Since Internet access is not guaranteed in an app container, this may not always be allowed.
  • 进程之间共享信息-ime 可能需要在不同应用容器中的应用之间共享有关用户输入首选项的数据。Sharing information between processes - IMEs may need to share data about the user’s input preferences between apps that are in different app containers. 使用 web 服务在应用之间共享数据。Use a web service to share data between apps.

重要

如果尝试绕过应用容器安全规则,则 IME 可能被视为恶意软件并被阻止。If you try to circumvent app container security rules, your IME may be treated as malware and blocked.

IME 和触摸键盘IME and touch keyboard

IME 必须确保其候选面板的 UI 以及其他 UI 元素不会绘制在触摸键盘的下方。Your IME must ensure that its candidate pane's UI, and other UI elements, aren't drawn underneath the touch keyboard. 触摸键盘与所有应用显示在 z 顺序较高的频带中,IME UI 与活动的应用显示在同一 z 顺序带区中。The touch keyboard is displayed in a higher z-order band than all apps, and the IME UI is displayed in the same z-order band as the app it's active in. 因此,触摸键盘可以重叠并隐藏 IME UI。As a result, the touch keyboard can overlap and hide the IME UI. 在大多数情况下,应用应调整其窗口大小,以用于触控键盘。In most cases, the app should resize its window to account for the touch keyboard. 如果应用没有调整大小,IME 仍可使用 InputPane API 来获取触摸键盘的位置。If an app doesn't resize, the IME still can use the InputPane API to get the position of the touch keyboard. IME 查询 Location 属性,或为触摸键盘的显示和隐藏事件注册处理程序。The IME queries the Location property, or it registers a handler for the touch keyboard's Show and Hide events. 每次用户点击编辑字段时都会引发 Show 事件,即使当前显示的是触摸键盘也是如此。The Show event is raised every time the user taps in an edit field, even if the touch keyboard is displayed currently. IME 可以使用此 API 来获取触碰 (或其他) 的 UI 之前的触摸键盘所用的屏幕空间,并重排 Ime UI,以避免在触摸键盘下绘制。Your IME can use this API to get the screen space used by the touch keyboard before the IME draws candidate (or other) UI, and to reflow the IMEs UI to avoid drawing beneath the touch keyboard.

指定首选触摸键盘布局Specifying the preferred touch keyboard layout

IME 可以指定要使用的触摸键盘布局,并且启用了 IME 来处理触摸优化的布局。The IME can specify which touch keyboard layout to use, and the IME is enabled to work with touch-optimized layouts. 此功能仅限于朝鲜语、日语、简体中文和繁体中文输入语言的 Ime。This functionality is limited to IMEs for the Korean, Japanese, Chinese Simplified, and Chinese Traditional input languages.

触摸键盘支持7个布局,其中三个为经典布局,其中的四个为触控优化布局。There are seven layouts supported by the touch keyboard, three of which are classic layouts and four of which are touch-optimized layouts. 经典布局的外观和行为与物理键盘相同。The classic layouts look and behave like a physical keyboard.

这三种经典布局均用于在不同形式中输入繁体中文:All of the three classic layouts are for inputting traditional Chinese in different forms:

  • 基于拼音的输入Phonetic-based input
  • 仓颉输入Changjie input
  • 大易输入Dayi input

除了经典布局,每个韩语、日语、简体中文和繁体中文输入语言都有一个触摸优化的布局。In addition to the classic layouts, there is one touch-optimized layout for each of the Korean, Japanese, Simplified Chinese, and Traditional Chinese input languages.

若要使用此功能,IME 必须实现 ITfFnGetPreferredTouchKeyboardLayout 接口,该接口由 IME 使用文本服务框架 ITfFunctionProvider API 导出。To use this functionality, your IME must implement the ITfFnGetPreferredTouchKeyboardLayout interface, which is exported by the IME by using the Text Services Framework ITfFunctionProvider API.

如果 IME 不支持 ITfFnGetPreferredTouchKeyboardLayout 接口,则使用 IME 会使触控键盘显示的语言使用默认的经典布局。If your IME doesn't support the ITfFnGetPreferredTouchKeyboardLayout interface, using the IME results in the default classic layout for the language that is displayed by the touch keyboard.

如果输入法需要将其中一种经典布局设置为首选布局,则除了支持 ITfFnGetPreferredTouchKeyboardLayout 和 ITfFunctionProvider 接口外,IME 不需要额外的工作。If your IME needs to set one of the classic layouts as the preferred layout, no additional work is required on the IME side beyond supporting the ITfFnGetPreferredTouchKeyboardLayout and ITfFunctionProvider interfaces. 但 IME 中需要额外的工作才能使用触摸优化布局,下一部分将对此进行介绍。But additional work is required in the IME to work with the touch-optimized layouts, and this is described in the next section.

触摸优化布局Touch-optimized layout

用于朝鲜语、日语、简体中文和繁体中文输入语言的触摸优化键盘在转换模式下显示了不同的输入法和 IME。The touch-optimized keyboards for the Korean, Japanese, Simplified Chinese, and Traditional Chinese input languages display a different layout for IME On and IME Off conversion modes. 触摸键盘上有一个用于将 IME 转换模式设置为 "开" 或 "关" 的键,但键盘的 IME 模式也可能随着编辑控件中的焦点更改而更改。There's a key on the touch keyboard to set the IME conversion mode to On or Off, but the IME mode of the keyboard also may change as focus changes among edit controls.

日语、简体中文和繁体中文输入语言的触摸优化键盘包含 IME 用来浏览候选页的键或键。The touch-optimized keyboards for the Japanese, Simplified Chinese, and Traditional Chinese input languages contain a key, or keys, which the IME uses to navigate through candidate pages. 对于日语和简体中文,候选页键显示在触摸优化布局上。For Japanese and Simplified Chinese, the candidate page key displays on the touch-optimized layout. 对于繁体中文,前一个和下一个候选页有单独的键。For Traditional Chinese, there are separate keys for the previous and next candidate pages.

按下这些键时,触摸键盘将调用 SendInput 函数,以将以下 Unicode 专用区域字符发送到突出输入的应用程序,IME 可以截获和操作:When these keys are pressed, the touch keyboard calls the SendInput function to send the following Unicode Private Use Area characters to the focused application, which the IME can intercept and act on:

  • **下一页 (0xF003) ** -在按下了用于日语和简体中文的触摸优化键盘上时,或在繁体中文的触摸优化键盘上按下页面键时发送。Next page (0xF003) - Sent when the candidate page key is pressed on the touch-optimized keyboard for Japanese and Simplified Chinese, or when the next page key is pressed on the touch-optimized keyboard for Traditional Chinese.
  • **上一页 (0xF004) ** -在按下候选页键的同时按下了用于日语和简体中文的触摸优化键盘上的 Shift 键时,或在繁体中文上按下了触摸优化键盘时发送。Previous page (0xF004) - Sent when either the candidate page key is pressed at the same time as the Shift key on the touch-optimized keyboard for Japanese and Simplified Chinese, or when the previous page key is pressed on the touch-optimized keyboard for Traditional Chinese.

这些字符将作为 Unicode 输入发送。These characters are sent as Unicode input. 下一段详细说明了如何在文本服务框架输入法接收的关键事件接收器通知期间提取字符信息。The next paragraph details how to extract the character information during the key event sink notifications that the Text Services Framework IME will receive. 不会在任何标头文件中定义这些字符值,因此需要在代码中定义这些字符值。These character values are not defined in any header file, so you will need to define them in your code.

若要截获键盘输入,IME 必须注册为 key 事件接收器。To intercept keyboard input, your IME must register as a key event sink. 对于通过使用 SendInput 函数生成的 Unicode 输入, ITfKeyEventSink 回调的 WPARAM 参数 (OnKeyDown,OnKeyUp,OnTestKeyDown,OnTestKeyUp) 始终包含虚拟密钥 VK_PACKET,并且不会直接标识该字符。For Unicode input that is generated by using the SendInput function, the WPARAM parameter of the ITfKeyEventSink callbacks (OnKeyDown, OnKeyUp, OnTestKeyDown, OnTestKeyUp) always contains the virtual key VK_PACKET and doesn't identify the character directly.

实现以下调用序列以访问字符:Implement the following call sequence to access the character:

// 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 search integration

通过搜索约定向用户提供搜索功能,并与搜索窗格集成。Provide users with search features through the search contract and integration with the search pane.

搜索窗格和 IME 建议
搜索窗格和 IME 建议Search pane and IME suggestions

搜索窗格是用户在所有应用中执行搜索的中心位置。The search pane is a central location for users to perform searches across all of their apps. 对于 IME 用户,Windows 提供了独特的搜索体验,允许兼容 Ime 与 Windows 集成,以实现更高的效率和可用性。For IME users, Windows provides a unique search experience that lets compatible IMEs integrate with Windows for greater efficiency and usability.

如果用户使用与搜索兼容的 IME 键入内容,则有两个主要优点:Users who type with an IME that's compatible with search get two main benefits:

  • IME 与搜索体验之间的无缝交互。Seamless interaction between the IME and the search experience. IME 在搜索框下内联显示,无需 occluding 搜索建议。IME candidates are shown inline under the search box without occluding search suggestions. 用户可以使用键盘在搜索框、IME 转换候选项和搜索建议之间无缝导航。The user can use the keyboard to navigate seamlessly between the search box, the IME conversion candidates, and the search suggestions.
  • 更快地访问应用程序提供的相关结果和建议。Faster access to relevant results and suggestions provided by applications. 应用有权访问所有当前的转换候选项,以提供更多相关建议。The app has access to all current conversion candidates to provide more relevant suggestions. 为了更好地确定搜索建议的优先级,按相关性顺序向应用程序提供转换。To better prioritize search suggestions, conversions are given to apps in order of relevance. 用户只需键入拼音即可查找并选择他们想要的结果,而无需转换。Users find and select the result they want without converting, just by typing in phonetic.

如果符合以下条件,则 IME 与集成的搜索体验兼容:An IME is compatible with the integrated search experience if it meets the following criteria:

当在 "搜索" 窗格中激活时,将在 UIless 模式下放置兼容的 IME 并且无法显示其 UI。When activated in the search pane, a compatible IME is placed in UIless mode and can't show its UI. 相反,它会将候选转换发送到 Windows,这会在内联候选项列表控件中显示它们,如前面的屏幕截图所示。Instead, it sends conversion candidates to Windows, which displays them in the inline candidate list control, as shown in the previous screenshot.

此外,IME 发送应用于运行当前搜索的候选项。Also, the IME sends candidates that should be used to run the current search. 这些候选项可以与转换候选项相同,也可以针对搜索进行定制。These candidates could be the same as the conversion candidates, or they could be tailored for search.

优秀搜索候选项满足以下条件:Good search candidates meet the following criteria:

  • 无前缀重叠。No prefix overlap. 例如,北京大学 and北京是冗余的,因为其中一个是另一个的前缀。For example, 北京大学 and北京 are redundant because one is a prefix of the other.
  • 无冗余候选项。No redundant candidates. 任何多余的候选项不适合搜索,因为它不能帮助筛选结果。Any redundant candidate isn't useful for search because it doesn't help filter results. 例如,任何与北京大学匹配的结果也会与北京匹配。For example, any result that matches 北京大学 also matches 北京.
  • 无预测候选项,仅转换。No prediction candidate, only conversion. 例如,如果用户键入 "北",则 IME 可以将返回为候选项,但不能返回北京大学。For example, if the user types "be", the IME can return 北 as a candidate, but not 北京大学. 通常,预测候选人过于严格。Usually, prediction candidates are too restrictive.

不符合条件的 Ime 与其他控件的搜索显示方式不兼容,并且无法利用 UI 集成和搜索候选项。IMEs that don't meet the criteria aren't compatible with search display in the same way as other controls, and can't take advantage of UI integration and search candidates. 应用仅在用户完成撰写后接收查询。Apps receive queries only after the user has finished composing.

当支持搜索协定的应用收到查询时,该查询事件包含一个 "queryTextAlternatives" 数组,该数组包含所有已知的替代项,该数组由最相关的 (可能) 到最不) (不太相关。When an app that supports the search contract receives a query, the query event contains a "queryTextAlternatives" array that contains all known alternatives, ranked from the most relevant (likely) to least relevant (unlikely).

如果提供了替代方法,则应用程序应将每个替代项视为查询,并返回所有匹配项的结果。When alternatives are provided, the app should treat each alternative as a query and return all results that match any of the alternatives. 应用程序的行为应如同用户同时发出了多个查询,实际上是向提供结果的服务发出了 "或" 查询。The app should behave as if the user had issued multiple queries at the same time, essentially issuing an "or" query to the service providing the results. 出于性能方面的考虑,应用通常会限制与最相关备选方案的5到20之间的匹配。For performance considerations, apps often limit matching to between 5 and 20 of the most relevant alternatives.

UI 设计准则UI design guidelines

所有 Ime 都必须遵循 设计和代码 Windows 应用中所述的用户体验指导原则。All IMEs must follow the user experience guidelines described in Design and code Windows apps.

不要使用粘滞窗口Don't use sticky windows

IME 窗口应仅在需要时显示,并且它们不应始终可见。Your IME windows should appear only when needed, and they shouldn't be visible all the time. 当用户不需要键入时,IME windows 不应显示。When users don't need to type, IME windows shouldn't show. IME 窗口不应为全屏窗口。The IME window shouldn't be a full screen window. IME windows 不应相互重叠。IME windows shouldn't overlap each other. Windows 应采用 Windows 样式设计,并遵循 UI 缩放。The windows should be designed in a Windows style and follow UI scaling.

IME 图标IME icons

有两种类型的 IME 图标:品牌图标和模式图标。There are two kinds of IME icons, branding icons and mode icons. 所有 IME 图标都必须仅设计为黑白颜色。All IME icons must be designed with black and white colors only. 新的 IME 图标借用系统托盘图标 glyphic 的外观。The new IME icons borrow from the glyphic look of the system tray icons. 此样式已经创建,因此所有语言都可以使用它来补充 familial 外观,同时也区分开来。This style has been created so all languages can use it to complement the familial look while also differentiating from each other.

IME 图标的文件格式是 .ICO。The file format for IME icons is ICO. 您必须提供以下图标大小。You must provide the following icon sizes.

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

确保所有分辨率中都提供了带 alpha 通道的32位图标。Ensure that 32-bit icons with alpha channel are provided in all resolutions.

IME 品牌图标由一个白色框定义,其中,新式字样中呈现的印刷标志符号。IME brand icons are defined by a white box in which a typographic glyph rendered in a modern typeface is placed. 每个语言组都选择每个定义标志符号。Each defining glyph is chosen by each language team. 标志符号为黑色。The glyph is black. 此框包含以黑色为50% 的不透明度的 "1" 像素的外部笔划。The box includes an outer stroke of 1 pixel in black at 50% opacity. "新" 版本由框左上角的圆角定义。"New" versions are defined by a rounded corner in the upper left of the box.

IME 模式图标由新式字样中的白色排字标志符号定义,其中包含以50% 的不透明度表示的黑色1像素的外部笔划。IME mode icons are defined by a white typographic glyph in a modern typeface which includes an outer stroke of 1 pixel in black at 50% opacity.

图标Icon 描述Description
繁体中文 ChangeJie 的 IME 图标示例。 繁体中文 ChangeJie 的 IME 图标示例。Example IME brand icon for Traditional Chinese ChangeJie.
繁体中文 New ChangeJie 的输入法标记图标示例。 繁体中文 ChangeJie 的 IME 图标示例。Example IME brand icon for Traditional Chinese ChangeJie.
中文模式图标 示例输入法模式图标。Example IME mode icon.

拥有的窗口Owned window

若要显示候选 UI,IME 必须将其窗口设置为拥有窗口,以便它可以显示当前正在运行的应用程序。To display candidate UI, an IME must set its window to be owned-window, so it can display over the currently running app. 使用 ITfContextView:: GetWnd 方法检索要拥有的窗口。Use the ITfContextView::GetWnd method to retrieve the window to own to. 如果 GetWnd 返回错误或 NULLHWND,则调用 GetFocus 函数。If GetWnd returns an error or a NULLHWND, call the GetFocus function.

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

IME 候选窗口与浅消除曲面交互IME candidate window interaction with light dismiss surfaces

弹出式窗口的消除模型称为 "轻型消除",因为用户可以轻松关闭此类窗口。The dismissal model for popup windows is called "light dismiss" because it's easy for a user to close such windows. 为了使 Ime 在 Windows 交互模型中正常工作,IME Windows 必须参与浅色消除模型。For IMEs to function well in the Windows interaction model, the IME windows must participate in the light dismiss model.

为了参与浅色消除模型,IME 必须使用 NotifyWinEvent 函数或类似函数引发三个新的 Windows 事件。In order to participate in the light dismiss model, your IME must raise three new Windows events by using the NotifyWinEvent function or a similar function. 这些新事件包括:These new events are:

  • EVENT_OBJECT_IME_SHOW -IME 变为可见时引发此事件。EVENT_OBJECT_IME_SHOW - Raise this event when the IME becomes visible.
  • EVENT_OBJECT_IME_HIDE -隐藏 IME 时引发此事件。EVENT_OBJECT_IME_HIDE - Raise this event when the IME is hidden.
  • EVENT_OBJECT_IME_CHANGE -IME 移动或更改大小时引发此事件。EVENT_OBJECT_IME_CHANGE - Raise this event when the IME moves or changes size.

声明兼容性Declaring compatibility

Ime 通过使用 ITfCategoryMgr:: RegisterCategory为其 IME 注册类别 GUID_TFCAT_TIPCAP_IMMERSIVESUPPORT 来声明它们是兼容的。IMEs declare that they are compatible by registering the category GUID_TFCAT_TIPCAP_IMMERSIVESUPPORT for their IME using ITfCategoryMgr::RegisterCategory.

将默认 IME 模式设置为打开Set the default IME mode to on

我们为 Ime 提供了更好的 UX。We provide a better UX for IMEs.

DPI 缩放支持桌面应用程序DPI scaling support for desktop applications

增强的 DPI 缩放支持支持查询每个桌面进程的已声明 DPI 感知级别,以确定是否需要缩放 UI。Enhanced DPI scaling support enables querying the declared DPI awareness level of each desktop process to determine if it needs to scale the UI. 在多监视器方案中,Windows 会针对每个监视器上的不同 DPI 设置适当地缩放 UI。In a multi-monitor scenario, Windows scales the UI appropriately for different DPI settings on each monitor.

由于 IME 在每个应用程序进程的上下文中运行,因此不应为 IME 声明 DPI 感知级别。Because your IME runs in the context of each application's process, you shouldn't declare a DPI awareness level for your IME. 这可确保 IME 在当前进程的 DPI 感知级别下运行。This ensures that your IME runs at the DPI awareness level of the current process.

若要确保所有 IME UI 元素与正在运行的进程的 UI 元素具有缩放性,则必须相应地响应不同的 DPI 值。To ensure that all IME UI elements have scaling parity with the UI elements of the process in which you are running, you must respond appropriately to different DPI values.

备注

为了确保使用新的桌面应用程序进行奇偶校验,IME 应支持每个监视器– DPI 感知,但不应声明级别本身。To ensure parity with new desktop applications, your IME should support per monitor–DPI awareness, but shouldn't declare a level of awareness itself. 系统在每个方案中确定适当的缩放要求。The system determines the appropriate scaling requirements in each scenario.

有关 DPI 缩放对桌面应用程序的支持的详细信息,请参阅 高 dpiFor details about DPI scaling support requirements for Desktop applications, see High DPI.

IME 安装IME installation

如果使用 Microsoft Visual Studio 生成输入法,请使用第三方安装程序(如 InstallShield Flexera Software)为 IME 创建安装体验。If you build your IME by using Microsoft Visual Studio, create an installation experience for your IME by using a third-party installer, like InstallShield from Flexera Software.

以下步骤演示如何使用 InstallShield 为 IME DLL 创建安装项目。The following steps show how to use InstallShield to create a setup project for your IME DLL.

  • 安装 Visual Studio。Install Visual Studio.
  • 启动 Visual Studio。Start Visual Studio.
  • 在 " 文件 " 菜单上,指向 " 新建 ",然后选择 " 项目"。On the File menu, point to New and select Project. 此时将打开 " 新建项目 " 对话框。The New Project dialog opens.
  • 在左窗格中,导航到 " 模板 > 其他项目类型 >" 安装和部署",单击" 启用 InstallShield 受限版本",然后单击 " 确定 "In the left pane, navigate to Templates > Other Project Types > Setup and Deployment, click Enable InstallShield Limited Edition, and click OK. 按照安装说明进行操作。Follow the installation instructions.
  • 重启 Visual Studio。Restart Visual Studio.
  • ( .sln) 文件中打开 IME 解决方案。Open the IME solution (.sln) file.
  • 在解决方案资源管理器中,右键单击解决方案,指向 " 添加",然后选择 " 新建项目"。In Solution Explorer, right-click the solution, point to Add, and select New Project. 此时将打开 " 添加新项目 " 对话框。The Add New Project dialog opens.
  • 在左侧树视图控件中,导航到 " 模板 > 其他项目类型 >" InstallShield 受限版本"。In the left tree view control, navigate to Templates > Other Project Types > InstallShield Limited Edition.
  • 在中心窗口中,单击 " InstallShield 受限版本项目"。In the center window, click InstallShield Limited Edition Project.
  • 在 " 名称 " 文本框中,键入 "SetupIME",然后单击 "确定"。In the Name text box, type "SetupIME" and click OK.
  • 在 " 项目助手 " 对话框中,单击 " 应用程序信息"。In the Project Assistant dialog, click Application Information.
  • 填写公司名称和其他字段。Fill in your company name and the other fields.
  • 单击 " 应用程序文件"。Click Application Files.
  • 在左窗格中,右键单击 " [INSTALLDIR] " 文件夹,然后选择 " 新建文件夹"。In the left pane, right-click the [INSTALLDIR] folder, and select New Folder. 将文件夹命名为 "插件"。Name the folder "Plugins".
  • 单击 " 添加文件"。Click Add Files. 导航到 IME DLL,并将其添加到 " 插件 " 文件夹中。Navigate to your IME DLL and add it to the Plugins folder. 为 IME 词典重复此步骤。Repeat this step for the IME dictionary.
  • 右键单击 IME DLL,然后选择 " 属性"。Right-click the IME DLL and select Properties. 此时将打开 " 属性 " 对话框。The Properties dialog opens.
  • 在 " 属性 " 对话框中,单击 " COM & .net 设置 " 选项卡。In the Properties dialog, click the COM & .NET Settings tab.
  • 在 " 注册类型" 下,选择 " 自注册 ",然后单击 "确定"Under Registration Type, select Self-registration and click OK.
  • 生成解决方案。Build the solution. IME DLL 生成后,InstallShield 创建一个 setup.exe 文件,使用户能够在 Windows 上安装 IME。The IME DLL is built, and InstallShield creates a setup.exe file that enables users to install your IME on Windows.

若要创建自己的安装体验,请在安装过程中调用 ITfInputProcessorProfileMgr:: RegisterProfile 方法来注册 IME。To create your own installation experience, call the ITfInputProcessorProfileMgr::RegisterProfile method to register the IME during installation. 请勿直接写入注册表项。Don't write registry entries directly.

如果 IME 必须在安装后立即使用,请调用 InstallLayoutOrTip ,以使用 psz 参数的以下格式将 IME 添加到启用用户的输入方法:If the IME must be usable immediately after installation, call InstallLayoutOrTip to add the IME to user-enabled input methods, using the following format for the psz parameter:

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

IME 辅助功能IME accessibility

实现以下约定,使 Ime 符合辅助功能要求,并与讲述人合作。Implement the following convention to make your IMEs conform to the accessibility requirements and to work with Narrator. 若要使候选列表可访问,你的 Ime 必须遵循此约定。To make candidate lists accessible, your IMEs must follow this convention.

  • 对于预测候选项列表,候选项列表必须具有等于 "IME_Candidate_Window" 的 UIA_AutomationIdPropertyId 或 "IME_Prediction_Window"。The candidate list must have a UIA_AutomationIdPropertyId equal to "IME_Candidate_Window" for lists of conversion candidates or "IME_Prediction_Window" for lists of prediction candidates.
  • 当候选项列表出现并消失时,它会分别引发 UIA_MenuOpenedEventIdUIA_MenuClosedEventId类型的事件When the candidate list appears and disappears, it raises events of type UIA_MenuOpenedEventId and UIA_MenuClosedEventId, respectively
  • 当当前选定的候选项发生更改时,候选项列表将引发 UIA_SelectionItem_ElementSelectedEventIdWhen the current selected candidate changes, the candidate list raises a UIA_SelectionItem_ElementSelectedEventId. 所选元素的属性应 UIA_SelectionItemIsSelectedPropertyId 等于 TRUEThe selected element should have a property UIA_SelectionItemIsSelectedPropertyId equal to TRUE.
  • 候选列表中每一项的 UIA_NamePropertyId 必须是候选项的名称。The UIA_NamePropertyId for each item in the candidate list must be the name of the candidate. 还可以通过 UIA_HelpTextPropertyId提供其他信息来消除候选项的歧义。Optionally, you can provide additional information to disambiguate candidates through UIA_HelpTextPropertyId.