• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Input Method Framework ChangeLog
2
3## cl.inputmethod_frameworks.1 API Error Information Return Method Change
4
5The internal APIs of the following modules used service logic return values to indicate error information, which did not comply with the error code specifications of OpenHarmony. Therefore, they are modified in API version 9 and later.
6
7 - Input method framework module: system API, @ohos.inputmethod.d.ts
8
9 - Input method service module: system API, @ohos.inputmethodengine.d.ts
10
11 - Input method ExtentionAbility module: system API, @ohos.inputmethodextensionability.d.ts
12
13 - Input method ExtentionContext module: system API, @ohos.inputmethodextensioncontext.d.ts
14
15 - Input method subtype module: system API, @ohos.inputMethodSubtype.d.ts
16
17Asynchronous API: An error message is returned via **AsyncCallback** or the **error** object of **Promise**.
18
19Synchronous API: An error message is returned via an exception.
20
21**Change Impact**
22
23The application developed based on earlier versions needs to adapt the method for returning API error information. Otherwise, the original service logic will be affected.
24
25**Key API/Component Changes**
26
27Error code processing is added for the following APIs:
28  - getSetting(): InputMethodSetting;
29
30  - getController(): InputMethodController;
31
32  - switchInputMethod(target: InputMethodProperty, callback: AsyncCallback\<boolean>): void;
33
34  - switchInputMethod(target: InputMethodProperty): Promise\<boolean>;
35
36  - switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback\<boolean>): void;
37
38  - switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise\<boolean>;
39
40  - switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback\<boolean>): void;
41
42  - switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise\<boolean>;
43
44  - listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array\<InputMethodSubtype>>): void;
45
46  - listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array\<InputMethodSubtype>>;
47
48  - listCurrentInputMethodSubtype(callback: AsyncCallback<Array\<InputMethodSubtype>>): void;
49
50  - listCurrentInputMethodSubtype(): Promise<Array\<InputMethodSubtype>>;
51
52  - getInputMethods(enable: boolean, callback: AsyncCallback<Array\<InputMethodProperty>>): void;
53
54  - getInputMethods(enable: boolean): Promise<Array\<InputMethodProperty>>;
55
56  - showOptionalInputMethods(callback: AsyncCallback\<boolean>): void;
57
58  - showOptionalInputMethods(): Promise\<boolean>;
59
60  - stopInputSession(callback: AsyncCallback\<boolean>): void;
61
62  - stopInputSession(): Promise\<boolean>;
63
64  - showSoftKeyboard(callback: AsyncCallback\<void>): void;
65
66  - showSoftKeyboard():Promise\<void>;
67
68  - hideSoftKeyboard(callback: AsyncCallback\<void>): void;
69
70  - hideSoftKeyboard():Promise\<void>;
71
72  - hide(callback: AsyncCallback\<void>): void;
73
74  - hide(): Promise\<void>;
75
76  - onCreate(want: Want): void;
77
78  - onDestroy(): void;
79
80
81  - In **InputClient**:
82
83    - sendKeyFunction(action: number, callback: AsyncCallback\<boolean>): void;
84
85    - sendKeyFunction(action: number): Promise\<boolean>;
86
87    - deleteForward(length: number, callback: AsyncCallback\<boolean>): void;
88
89    - deleteForward(length: number): Promise\<boolean>;
90
91    - deleteBackward(length: number, callback: AsyncCallback\<boolean>): void;
92
93    - deleteBackward(length: number): Promise\<boolean>;
94
95    - insertText(text: string, callback: AsyncCallback\<boolean>): void;
96
97    - insertText(text: string): Promise\<boolean>;
98
99    - getForward(length: number, callback: AsyncCallback\<string>): void;
100
101    - getForward(length: number): Promise\<string>;
102
103    - getBackward(length: number, callback: AsyncCallback\<string>): void;
104
105    - getBackward(length: number): Promise\<string>;
106
107    - getEditorAttribute(callback: AsyncCallback\<EditorAttribute>): void;
108
109    - getEditorAttribute(): Promise\EditorAttribute>;
110
111    - moveCursor(direction: number, callback: AsyncCallback\<void>): void;
112
113    - moveCursor(direction: number): Promise\<void>;
114
115- In **InputMethodExtensionAbility**:
116
117    - onCreate(want: Want): void;
118
119    - onDestroy(): void;
120
121**Adaptation Guide**
122
123The following uses **showOptionalInputMethods** as an example for asynchronous APIs:
124
125Callback mode:
126
127```js
128import inputMethod from '@ohos.inputmethod';
129let inputMethodSetting = inputMethod.getSetting();
130try {
131    inputMethodSetting.showOptionalInputMethods((err, data) => {
132        if (err !== undefined) {
133            console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
134            return;
135        }
136        console.info('Succeeded in showing optionalInputMethods.');
137    });
138} catch (err) {
139    console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
140}
141```
142
143Promise mode:
144
145```js
146import inputMethod from '@ohos.inputmethod';
147let inputMethodSetting = inputMethod.getSetting();
148inputMethodSetting.showOptionalInputMethods().then((data) => {
149    console.info('Succeeded in showing optionalInputMethods.');
150}).catch((err) => {
151    console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
152})
153```
154
155## cl.inputmethod_frameworks.2 Deprecation of Some APIs
156
157Deprecated APIs:
158  - getInputMethodSetting(): InputMethodSetting;
159  - getInputMethodController(): InputMethodController;
160  - listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void;
161  - listInputMethod(): Promise<Array<InputMethodProperty>>;
162  - displayOptionalInputMethod(callback: AsyncCallback<void>): void;
163  - displayOptionalInputMethod(): Promise<void>;
164  - stopInput(callback: AsyncCallback<boolean>): void;
165  - stopInput(): Promise<boolean>;
166    interface InputMethodProperty:
167    - readonly packageName: string;
168	- readonly methodId: string;
169  - getInputMethodEngine(): InputMethodEngine;
170  - createKeyboardDelegate(): KeyboardDelegate;
171  - hideKeyboard(callback: AsyncCallback<void>): void;
172  - hideKeyboard(): Promise<void>;
173
174Substitute APIs:
175  - getSetting(): InputMethodSetting;
176  - getController(): InputMethodController;
177  - getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
178  - getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
179  - showOptionalInputMethods(callback: AsyncCallback<boolean>): void;
180  - showOptionalInputMethods(): Promise<boolean>;
181  - stopInputSession(callback: AsyncCallback<boolean>): void;
182  - stopInputSession(): Promise<boolean>;
183    interface InputMethodProperty:
184    - readonly name: string;
185	- readonly id: string;
186  - getInputMethodAbility(): InputMethodAbility;
187  - getKeyboardDelegate(): KeyboardDelegate;
188  - hide(callback: AsyncCallback<void>): void;
189  - hide(): Promise<void>;
190
191**NOTE**
192    Use the **getInputMethodAbility()** API to obtain an **InputMethodAbility** object, and do not use **getInputMethodEngine()** to obtain an **InputMethodEngine** object.
193	  Use methods in **InputMethodAbility**, and do not use methods in **InputMethodEngine**.
194	  Use the **on('inputStart')** method in **InputMethodAbility** to obtain a **KeyboardController** instance and an **InputClient** instance, and do not use the **on('inputStart')** method in **InputMethodEngine** to obtain a **TextInputClient** instance.
195Before:
196
197```js
198inputMethodEngine.getInputMethodEngine().on('inputStart', (kbController, textClient) => {
199    let keyboardController = kbController;
200    let textInputClient = textClient;  // Obtain a TextInputClient instance.
201});
202```
203
204After:
205```js
206inputMethodEngine.getInputMethodAbility().on('inputStart', (kbController, client) => {
207    let keyboardController = kbController;
208    let inputClient = client;  // // Obtain an InputClient instance.
209});
210```
211
212## cl.inputmethod_frameworks.3 Change of Some APIs
213
214Before change:
215  - listInputMethod(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
216  - listInputMethod(enable: boolean): Promise<Array<InputMethodProperty>>;
217  - terminateSelf(callback: AsyncCallback<void>): void;
218  - terminateSelf(): Promise<void>;
219
220After change:
221  - getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
222  - getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
223  - destroy(callback: AsyncCallback<void>): void;
224  - destroy(): Promise<void>;
225
226Deleted APIs in API version 9:
227  - startAbility(want: Want, callback: AsyncCallback<void>): void;
228  - startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;
229  - startAbility(want: Want, options?: StartOptions): Promise<void>;
230
231Added APIs:
232  - on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void;
233  - off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void;
234  - interface InputMethodProperty:
235    - readonly label?: string;
236	- readonly icon?: string;
237	- readonly iconId?: number;
238	- extra: object;
239
240  - interface InputMethodAbility:
241    - on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void;
242    - off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void;
243