1# PatternLock
2
3图案密码锁组件，以九宫格图案的方式输入密码，用于密码验证场景。手指在PatternLock组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。
4
5>  **说明：**
6>
7> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9## 子组件
10
11无
12
13##  接口
14
15PatternLock(controller?: PatternLockController)
16
17**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
18
19**系统能力：** SystemCapability.ArkUI.ArkUI.Full
20
21**参数：**
22
23| 参数名     | 类型                                        | 必填 | 说明 |
24| ---------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
25| controller | [PatternLockController](#patternlockcontroller) | 否   | 设置PatternLock组件控制器，可用于控制组件状态重置。       |
26
27## 属性
28
29除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
30
31### sideLength
32
33sideLength(value: Length)
34
35设置组件的宽度和高度（宽高相同）。设置为0或负数时组件不显示。
36
37**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
38
39**系统能力：** SystemCapability.ArkUI.ArkUI.Full
40
41**参数：**
42
43| 参数名 | 类型                         | 必填 | 说明               |
44| ------ | ---------------------------- | ---- | ------------------ |
45| value  | [Length](ts-types.md#length) | 是   | 组件的宽度和高度。默认值：288vp |
46
47### circleRadius
48
49circleRadius(value: Length)
50
51设置宫格中圆点的半径。设置为0或负数时取默认值。
52
53**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
54
55**系统能力：** SystemCapability.ArkUI.ArkUI.Full
56
57**参数：**
58
59| 参数名 | 类型                         | 必填 | 说明                               |
60| ------ | ---------------------------- | ---- | ---------------------------------- |
61| value  | [Length](ts-types.md#length) | 是   | 宫格中圆点的半径。<br/>默认值：6vp<br/>取值范围：(0, sideLength/11]，设置小于等于0的值时按默认值处理，超过最大值按最大值处理。 |
62
63### backgroundColor
64backgroundColor(value: ResourceColor)
65
66设置背景颜色
67
68**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
69
70**系统能力：** SystemCapability.ArkUI.ArkUI.Full
71
72| 参数名 | 类型                                       | 必填 | 说明                                                       |
73| ------ | ------------------------------------------ | ---- | ---------------------------------------------------------- |
74| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 背景颜色 |
75
76### regularColor
77
78regularColor(value: ResourceColor)
79
80设置宫格圆点在“未选中”状态的填充颜色。
81
82**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
83
84**系统能力：** SystemCapability.ArkUI.ArkUI.Full
85
86**参数：**
87
88| 参数名 | 类型                                       | 必填 | 说明                                                       |
89| ------ | ------------------------------------------ | ---- | ---------------------------------------------------------- |
90| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 宫格圆点在“未选中”状态的填充颜色。<br/>默认值：'#ff182431' |
91
92### selectedColor
93
94selectedColor(value: ResourceColor)
95
96设置宫格圆点在“选中“状态的填充颜色。
97
98**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
99
100**系统能力：** SystemCapability.ArkUI.ArkUI.Full
101
102**参数：**
103
104| 参数名 | 类型                                       | 必填 | 说明                                                     |
105| ------ | ------------------------------------------ | ---- | -------------------------------------------------------- |
106| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 宫格圆点在“选中”状态的填充颜色。<br/>默认值：'#ff182431' |
107
108### activeColor
109
110activeColor(value: ResourceColor)
111
112设置宫格圆点在“激活”状态的填充颜色，“激活”状态为手指经过圆点但还未选中的状态。
113
114**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
115
116**系统能力：** SystemCapability.ArkUI.ArkUI.Full
117
118**参数：**
119
120| 参数名 | 类型                                       | 必填 | 说明                                                     |
121| ------ | ------------------------------------------ | ---- | -------------------------------------------------------- |
122| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 宫格圆点在“激活”状态的填充颜色。<br/>默认值：'#ff182431' |
123
124### pathColor
125
126pathColor(value: ResourceColor)
127
128设置连线的颜色。
129
130**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
131
132**系统能力：** SystemCapability.ArkUI.ArkUI.Full
133
134**参数：**
135
136| 参数名 | 类型                                       | 必填 | 说明                                 |
137| ------ | ------------------------------------------ | ---- | ------------------------------------ |
138| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 连线的颜色。<br/>默认值：'#33182431' |
139
140### pathStrokeWidth
141
142pathStrokeWidth(value: number | string)
143
144设置连线的宽度。设置为0或负数时连线不显示。
145
146**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
147
148**系统能力：** SystemCapability.ArkUI.ArkUI.Full
149
150**参数：**
151
152| 参数名 | 类型                       | 必填 | 说明                          |
153| ------ | -------------------------- | ---- | ----------------------------- |
154| value  | number&nbsp;\|&nbsp;string | 是   | 连线的宽度。<br/>默认值：12vp |
155
156### autoReset
157
158autoReset(value: boolean)
159
160设置在完成密码输入后再次在组件区域按下时是否重置组件状态。
161
162**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
163
164**系统能力：** SystemCapability.ArkUI.ArkUI.Full
165
166**参数：**
167
168| 参数名 | 类型    | 必填 | 说明                                                         |
169| ------ | ------- | ---- | ------------------------------------------------------------ |
170| value  | boolean | 是   | 在完成密码输入后再次在组件区域按下时是否重置组件状态。<br/>为true时，完成密码输入后再次在组件区域按下时会重置组件状态（即清除之前输入的密码）；为false时，不会重置组件状态。<br/>默认值：true |
171
172### activateCircleStyle<sup>12+</sup>
173
174activateCircleStyle(options: Optional\<CircleStyleOptions\>)
175
176设置宫格圆点在“激活”状态的背景圆环样式。
177
178**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
179
180**系统能力：** SystemCapability.ArkUI.ArkUI.Full
181
182**参数：**
183
184| 参数名 | 类型    | 必填 | 说明                                                         |
185| ------ | ------- | ---- | ------------------------------------------------------------ |
186| options  | [CircleStyleOptions](#circlestyleoptions12对象说明) | 是   | 宫格圆点在“激活”状态的背景圆环样式。|
187
188### CircleStyleOptions<sup>12+</sup>对象说明
189
190**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
191
192**系统能力：** SystemCapability.ArkUI.ArkUI.Full
193
194
195| 名称          | 类型 | 必填 | 说明 |
196| ------------- | ------- | ---- | -------- |
197| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 背景圆环颜色。 <br/>默认值：与pathColor值相同 |
198| radius  | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 背景圆环的半径。<br/>默认值：circleRadius的11/6 |
199| enableWaveEffect | boolean | 否 | 波浪效果开关。<br/>默认值：true |
200
201## 事件
202
203除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件：
204
205### onPatternComplete
206
207onPatternComplete(callback: (input: Array\<number\>) => void)
208
209密码输入结束时触发该回调。
210
211**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
212
213**系统能力：** SystemCapability.ArkUI.ArkUI.Full
214
215**参数：**
216
217| 参数名 | 类型            | 必填 | 说明                                                         |
218| ------ | --------------- | ---- | ------------------------------------------------------------ |
219| input  | Array\<number\> | 是   | 与选中宫格圆点顺序一致的数字数组，数字为选中宫格圆点的索引值（第一行圆点从左往右依次为0、1、2，第二行圆点依次为3、4、5，第三行圆点依次为6、7、8）。 |
220
221### onDotConnect<sup>11+</sup>
222
223onDotConnect(callback: [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<number\>)
224
225密码输入选中宫格圆点时触发该回调。
226
227回调参数为选中宫格圆点顺序的数字，数字为选中宫格圆点的索引值（第一行圆点从左往右依次为0、1、2，第二行圆点依次为3、4、5，第三行圆点依次为6、7、8）。
228
229**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
230
231**系统能力：** SystemCapability.ArkUI.ArkUI.Full
232
233## PatternLockController
234
235PatternLock组件的控制器，可以通过它进行组件状态重置。
236
237### 导入对象
238
239```typescript
240let patternLockController: PatternLockController = new PatternLockController()
241```
242
243### constructor
244
245constructor()
246
247PatternLockController的构造函数。
248
249**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
250
251**系统能力：** SystemCapability.ArkUI.ArkUI.Full
252
253### reset
254
255reset()
256
257重置组件状态。
258
259**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
260
261**系统能力：** SystemCapability.ArkUI.ArkUI.Full
262
263### setChallengeResult<sup>11+</sup>
264
265setChallengeResult(result: PatternLockChallengeResult): void
266
267用于设置图案密码正确或错误状态。
268
269**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
270
271**系统能力：** SystemCapability.ArkUI.ArkUI.Full
272
273| 名称   | 类型                                                         | 必填 | 说明           |
274| ------ | ------------------------------------------------------------ | ---- | -------------- |
275| result | [PatternLockChallengeResult](#patternlockchallengeresult11枚举说明) | 是   | 图案密码状态。 |
276
277## PatternLockChallengeResult<sup>11+</sup>枚举说明
278
279**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
280
281**系统能力：** SystemCapability.ArkUI.ArkUI.Full
282
283| 名称    | 说明           |
284| ------- | -------------- |
285| CORRECT | 图案密码正确。 |
286| WRONG   | 图案密码错误。 |
287
288##  示例
289
290该示例展示了PatternLock组件的基本使用方法。通过sideLength设置九宫格的大小、circleRadius等属性设置宫格圆点样式、onPatternComplete属性设置密码输入时的回调。
291
292当用户密码输入完成后，按输入的密码不同，给予不同的回应：输入的密码长度小于5时，提示重新输入；第一次输入完成后，提示第二次输入密码；第二次输入完成后，判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入。
293
294通过'Reset PatternLock'按钮，用户可以重置密码锁。
295
296```ts
297// xxx.ets
298import { LengthUnit } from '@kit.ArkUI'
299
300@Entry
301@Component
302struct PatternLockExample {
303  @State passwords: Number[] = []
304  @State message: string = 'please input password!'
305  private patternLockController: PatternLockController = new PatternLockController()
306
307  build() {
308    Column() {
309      Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20)
310      PatternLock(this.patternLockController)
311        .sideLength(200)
312        .circleRadius(9)
313        .pathStrokeWidth(18)
314        .activeColor('#B0C4DE')
315        .selectedColor('#228B22')
316        .pathColor('#90EE90')
317        .backgroundColor('#F5F5F5')
318        .autoReset(true)
319        .activateCircleStyle({
320          color: '#90EE90',
321          radius: { value: 16, unit: LengthUnit.VP },
322          enableWaveEffect: true
323        })
324        .onDotConnect((index: number) => {
325          console.log("onDotConnect index: " + index)
326        })
327        .onPatternComplete((input: Array<number>) => {
328          // 输入的密码长度小于5时，提示重新输入
329          if (input.length < 5) {
330            this.message = 'The password length needs to be greater than 5, please enter again.'
331            return
332          }
333          // 判断密码长度是否大于0
334          if (this.passwords.length > 0) {
335            // 判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入
336            if (this.passwords.toString() === input.toString()) {
337              this.passwords = input
338              this.message = 'Set password successfully: ' + this.passwords.toString()
339              this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT)
340            } else {
341              this.message = 'Inconsistent passwords, please enter again.'
342              this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG)
343            }
344          } else {
345            // 提示第二次输入密码
346            this.passwords = input
347            this.message = "Please enter again."
348          }
349        })
350      Button('Reset PatternLock').margin(30).onClick(() => {
351        // 重置密码锁
352        this.patternLockController.reset()
353        this.passwords = []
354        this.message = 'Please input password'
355      })
356    }.width('100%').height('100%')
357  }
358}
359```
360
361![patternlock](figures/patternlock.gif)
362