1# @ohos.multimodalInput.inputConsumer-sys (组合按键)(系统接口)
2
3组合按键订阅模块，用于处理组合按键的订阅。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> - 本模块接口为系统接口。
10
11## 导入模块
12
13```js
14import { inputConsumer } from '@kit.InputKit';
15```
16
17## inputConsumer.on
18
19on(type: 'key', keyOptions: KeyOptions, callback: Callback<KeyOptions>): void
20
21订阅组合按键，当满足条件的组合按键输入事件发生时，使用Callback异步方式上报组合按键数据。
22
23**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
24
25**参数：**
26
27| 参数名         | 类型                         | 必填   | 说明                                       |
28| ---------- | -------------------------- | ---- | ---------------------------------------- |
29| type       | string                     | 是    | 事件类型，目前仅支持'key'。                       |
30| keyOptions | [KeyOptions](#keyoptions)  | 是    | 组合键选项。                 |
31| callback   | Callback<KeyOptions> | 是    | 回调函数，当满足条件的组合按键输入事件发生时，异步上报组合按键数据。 |
32
33**示例：**
34
35```js
36let leftAltKey = 2045;
37let tabKey = 2049;
38let keyOptions: inputConsumer.KeyOptions = {
39  preKeys: [ leftAltKey ],
40  finalKey: tabKey,
41  isFinalKeyDown: true,
42  finalKeyDownDuration: 0
43};
44let callback = (keyOptions: inputConsumer.KeyOptions) => {
45  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
46}
47try {
48  inputConsumer.on("key", keyOptions, callback);
49} catch (error) {
50  console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
51}
52```
53
54
55## inputConsumer.off
56
57off(type: 'key', keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void
58
59取消订阅组合按键。
60
61**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
62
63**参数：**
64
65| 参数名         | 类型                         | 必填   | 说明                              |
66| ---------- | -------------------------- | ---- | ------------------------------- |
67| type       | string                     | 是    | 事件类型，当前仅支持 'key'。              |
68| keyOptions | [KeyOptions](#keyoptions)  | 是    | 组合键选项。             |
69| callback   | Callback<KeyOptions> | 否    | 需要取消订阅的回调函数。若不填，则取消当前应用组合键选项已订阅的所有回调函数。 |
70
71**示例：**
72
73```js
74let leftAltKey = 2045;
75let tabKey = 2049;
76// 取消订阅单个回调函数
77let callback = (keyOptions: inputConsumer.KeyOptions) => {
78  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
79}
80let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0};
81try {
82  inputConsumer.on("key", keyOption, callback);
83  inputConsumer.off("key", keyOption, callback);
84  console.log(`Unsubscribe success`);
85} catch (error) {
86  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
87}
88```
89```js
90let leftAltKey = 2045;
91let tabKey = 2049;
92// 取消订阅所有回调函数
93let callback = (keyOptions: inputConsumer.KeyOptions) => {
94  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
95}
96let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0};
97try {
98  inputConsumer.on("key", keyOption, callback);
99  inputConsumer.off("key", keyOption);
100  console.log(`Unsubscribe success`);
101} catch (error) {
102  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
103}
104```
105
106## inputConsumer.setShieldStatus<sup>11+</sup>
107
108setShieldStatus(shieldMode: ShieldMode, isShield: boolean): void
109
110设置屏蔽按键拦截状态。
111
112**需要权限**: ohos.permission.INPUT_CONTROL_DISPATCHING
113
114**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
115
116**参数：**
117
118| 参数名         | 类型                         | 必填   | 说明                                       |
119| ---------- | -------------------------- | ---- | ---------------------------------------- |
120| shieldMode       | ShieldMode                     | 是    | 屏蔽类型，目前仅支持'FACTORY_MODE'。                       |
121| isShield | boolean  | 是    | 屏蔽类型生效状态，true代表屏蔽类型生效，flase代表不生效。              |
122
123**示例：**
124
125```js
126let FACTORY_MODE = 0;
127try {
128  inputConsumer.setShieldStatus(FACTORY_MODE,true);
129  console.log(`set shield status success`);
130} catch (error) {
131  console.log(`set shield status failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
132}
133
134```
135
136## inputConsumer.getShieldStatus<sup>11+</sup>
137
138getShieldStatus(shieldMode: ShieldMode): boolean
139
140获取屏蔽按键拦截是否生效。
141
142**需要权限**: ohos.permission.INPUT_CONTROL_DISPATCHING
143
144**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
145
146**参数：**
147
148| 参数名         | 类型                         | 必填   | 说明                                       |
149| ---------- | -------------------------- | ---- | ---------------------------------------- |
150| shieldMode       | ShieldMode                    | 是    | 屏蔽类型，目前仅支持'FACTORY_MODE'。                       |
151
152**返回值：**
153
154| 参数         |  说明                                       |
155| ---------- |  ---------------------------------------- |
156| boolean                    | 屏蔽类型生效状态，true代表屏蔽类型生效，flase代表不生效。                       |
157
158**示例：**
159
160```js
161try {
162  let FACTORY_MODE = 0;
163  let shieldstatusResult:Boolean =  inputConsumer.getShieldStatus(FACTORY_MODE);
164  console.log(` get shield status result:${JSON.stringify(shieldstatusResult)}`);
165} catch (error) {
166  console.log(`Failed to get shield status, error: ${JSON.stringify(error, [`code`, `message`])}`);
167}
168```
169
170## KeyOptions
171
172组合键选项。
173
174**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
175
176| 名称        | 类型   | 可读   | 可写   | 说明      |
177| --------- | ------ | ---- | ---- | ------- |
178| preKeys    | Array\<number>   | 是    | 否 | 前置按键集合，数量范围[0, 4]，前置按键无顺序要求。<br>如组合按键Ctrl+Alt+A中，Ctrl+Alt称为前置按键。 |
179| finalKey             | number  | 是    |  否 | 最终按键，此项必填，最终按键触发上报回调函数。<br>如组合按键Ctrl+Alt+A中，A称为最终按键按键。 |
180| isFinalKeyDown       | boolean | 是    |  否 | 最终按键状态。<br>ture表示按键按下，false表示按键抬起。 |
181| finalKeyDownDuration | number  | 是    |  否 | 最终按键保持按下持续时间，单位为微秒（μs）。<br>当finalKeyDownDuration为0时，立即触发回调函数。<br>当finalKeyDownDuration大于0时，isFinalKeyDown为true，则最终按键按下超过设置时长后触发回调函数；isFinalKeyDown为false，则最终按键按下到抬起时间小于设置时长时触发回调函数。   |
182| isRepeat<sup>14+</sup>  | boolean  | 是      | 否      | 是否上报重复的按键事件。true表示上报，false表示不上报，若不填默认为true。 |
183
184## shieldMode<sup>11+</sup>
185
186屏蔽类型。
187
188**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
189
190| 名称                        | 类型  | 可读 | 可写 | 说明           |
191| ------------------------------ | ----------- | ---------------- | ---------------- | ---------------- |
192| FACTORY_MODE | number | 是 | 否 | 屏蔽类型，屏蔽所有快捷键。 |