• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 输入法应用沉浸模式
2<!--Kit: IME Kit-->
3<!--Subsystem: MiscServices-->
4<!--Owner: @illybyy-->
5<!--Designer: @andeszhang-->
6<!--Tester: @murphy1984-->
7<!--Adviser: @zhang_yixin13-->
8
9## 场景介绍
10
11为了让应用能够提供一致的沉浸式体验，我们提供了前台应用和输入法应用之间的通信机制。通过该机制，输入法应用根据前台应用设置的沉浸模式来决定最终沉浸模式。
12
13## 框架原理
14![输入法沉浸模式原理图](./figures/输入法沉浸模式原理图.png)
15- 前台应用根据应用场景，设置应用期望的沉浸模式。
16- 输入法框架在拉起输入法应用时会将前台应用期望的沉浸模式传递给输入法应用。
17- 输入法应用根据前台应用的沉浸模式决定最终的沉浸模式，并设置最终沉浸模式给输入法框架。
18
19## 接入指导
201. 前台应用[设置编辑框沉浸模式](../reference/apis-arkui/arkui-ts/ts-basic-components-textarea.md#keyboardappearance15)。示例代码如下。
21   ```ts
22   TextArea({text: "hello world"})
23      .keyboardAppearance(KeyboardAppearance.IMMERSIVE)
24   ```
25
262. 输入法应用[订阅编辑框属性变化事件](../reference/apis-ime-kit/js-apis-inputmethodengine.md#oneditorattributechanged10)，通过回调参数EditorAttribute中的immersiveMode字段感知前台应用期望的沉浸模式。示例代码如下。
27
28   ```ts
29   import { inputMethodEngine } from '@kit.IMEKit';
30
31   inputMethodEngine.getKeyboardDelegate().on("editorAttributeChanged", (attr : inputMethodEngine.EditorAttribute) => {
32      console.info("received editorAttributeChanged, immersiveMode: " + attr.immersiveMode);
33   })
34   ```
35
363. 输入法应用[设置沉浸模式](../reference/apis-ime-kit/js-apis-inputmethodengine.md#setimmersivemode15)。
37   - IMMERSIVE表示沉浸模式由输入法应用决定。
38   - 输入法应用不能设置IMMERSIVE模式给输入法框架。
39   - 如果输入法应用收到前台应用期望的沉浸模式为IMMERSIVE，建议输入法应用根据当前系统所处颜色模式，将最终沉浸模式设置为浅色沉浸模式（LIGHT_IMMERSIVE）或深色沉浸模式（DARK_IMMERSIVE）。
40
41
42   设置沉浸模式，示例代码如下。setImmersiveMode接口需使用[createPanel](../reference/apis-ime-kit/js-apis-inputmethodengine.md#createpanel10)获取到Panel实例后，通过实例调用。
43   ```ts
44   import { inputMethodEngine } from '@kit.IMEKit';
45
46   let panelInfo: inputMethodEngine.PanelInfo = {
47     type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
48     flag: inputMethodEngine.PanelFlag.FLG_FIXED
49   };
50   let inputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();
51   // createPanel需要在InputMethodExtensionAbility的Create声明周期中完成，this.context是InputMethodExtensionAbility中的InputMethodExtensionContext
52   inputMethodAbility.createPanel(this.context, panelInfo).then(async (panel: inputMethodEngine.Panel) => {
53     let inputPanel: inputMethodEngine.Panel = panel;
54     try {
55       inputPanel?.setImmersiveMode(inputMethodEngine.ImmersiveMode.LIGHT_IMMERSIVE);
56     } catch (err) {
57       let error: BusinessError = err as BusinessError;
58       console.error(`Failed to setImmersiveMode, code: ${error.code}, message: ${error.message}`);
59     }
60   }).catch((err: BusinessError) => {
61     console.log(`Failed to createPanel, code: ${err.code}, message: ${err.message}`);
62   });
63   ```
64