1# PatternLock
2
3The **PatternLock** component allows users to use a pattern password for authentication. It enters the input state once a finger is pressed against it, and exits the input state and completes the input once the finger leaves the screen.
4
5>  **NOTE**
6>
7> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Child Components
10
11Not supported
12
13##  APIs
14
15PatternLock(controller?: PatternLockController)
16
17**Atomic service API**: This API can be used in atomic services since API version 12.
18
19**System capability**: SystemCapability.ArkUI.ArkUI.Full
20
21**Parameters**
22
23| Name    | Type                                       | Mandatory| Description|
24| ---------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
25| controller | [PatternLockController](#patternlockcontroller) | No  | Controller of a component to reset the component status.      |
26
27## Attributes
28
29In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
30
31### sideLength
32
33sideLength(value: Length)
34
35Sets the width and height (same value) of the component. If this attribute is set to **0** or a negative number, the component is not displayed.
36
37**Atomic service API**: This API can be used in atomic services since API version 12.
38
39**System capability**: SystemCapability.ArkUI.ArkUI.Full
40
41**Parameters**
42
43| Name| Type                        | Mandatory| Description              |
44| ------ | ---------------------------- | ---- | ------------------ |
45| value  | [Length](ts-types.md#length) | Yes  | Width and height of the component. Default value: **288vp**|
46
47### circleRadius
48
49circleRadius(value: Length)
50
51Sets the radius of the grid dot. If this attribute is set to **0** or a negative value, the default value is used.
52
53**Atomic service API**: This API can be used in atomic services since API version 12.
54
55**System capability**: SystemCapability.ArkUI.ArkUI.Full
56
57**Parameters**
58
59| Name| Type                        | Mandatory| Description                              |
60| ------ | ---------------------------- | ---- | ---------------------------------- |
61| value  | [Length](ts-types.md#length) | Yes  | Radius of the grid dot.<br>Default value: **6vp**|
62
63### backgroundColor
64backgroundColor(value: ResourceColor)
65
66Sets the background color.
67
68**Atomic service API**: This API can be used in atomic services since API version 12.
69
70**System capability**: SystemCapability.ArkUI.ArkUI.Full
71
72| Name| Type                                      | Mandatory| Description                                                      |
73| ------ | ------------------------------------------ | ---- | ---------------------------------------------------------- |
74| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Background color.|
75
76### regularColor
77
78regularColor(value: ResourceColor)
79
80Sets the fill color of the grid dot in the unselected state.
81
82**Atomic service API**: This API can be used in atomic services since API version 12.
83
84**System capability**: SystemCapability.ArkUI.ArkUI.Full
85
86**Parameters**
87
88| Name| Type                                      | Mandatory| Description                                                      |
89| ------ | ------------------------------------------ | ---- | ---------------------------------------------------------- |
90| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Fill color of the grid dot in the unselected state.<br>Default value: **'#ff182431'**|
91
92### selectedColor
93
94selectedColor(value: ResourceColor)
95
96Sets the fill color of the grid dot in the selected state.
97
98**Atomic service API**: This API can be used in atomic services since API version 12.
99
100**System capability**: SystemCapability.ArkUI.ArkUI.Full
101
102**Parameters**
103
104| Name| Type                                      | Mandatory| Description                                                    |
105| ------ | ------------------------------------------ | ---- | -------------------------------------------------------- |
106| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Fill color of the grid dot in the selected state.<br>Default value: **'#ff182431'**|
107
108### activeColor
109
110activeColor(value: ResourceColor)
111
112Sets the fill color of the grid dot in the activated state, which is when the dot is highlighted but not selected.
113
114**Atomic service API**: This API can be used in atomic services since API version 12.
115
116**System capability**: SystemCapability.ArkUI.ArkUI.Full
117
118**Parameters**
119
120| Name| Type                                      | Mandatory| Description                                                    |
121| ------ | ------------------------------------------ | ---- | -------------------------------------------------------- |
122| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Fill color of the grid dot in the activated state.<br>Default value: **'#ff182431'**|
123
124### pathColor
125
126pathColor(value: ResourceColor)
127
128Sets the path color.
129
130**Atomic service API**: This API can be used in atomic services since API version 12.
131
132**System capability**: SystemCapability.ArkUI.ArkUI.Full
133
134**Parameters**
135
136| Name| Type                                      | Mandatory| Description                                |
137| ------ | ------------------------------------------ | ---- | ------------------------------------ |
138| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Path color.<br>Default value: **'#33182431' **|
139
140### pathStrokeWidth
141
142pathStrokeWidth(value: number | string)
143
144Sets the width of the path stroke. If this attribute is set to **0** or a negative value, the path stroke is not displayed.
145
146**Atomic service API**: This API can be used in atomic services since API version 12.
147
148**System capability**: SystemCapability.ArkUI.ArkUI.Full
149
150**Parameters**
151
152| Name| Type                      | Mandatory| Description                         |
153| ------ | -------------------------- | ---- | ----------------------------- |
154| value  | number \| string | Yes  | Wdth of the path stroke.<br>Default value: **12vp**|
155
156### autoReset
157
158autoReset(value: boolean)
159
160Sets whether to allow the user to reset the component status (that is, clear the input) by touching the component again after the input is complete.
161
162**Atomic service API**: This API can be used in atomic services since API version 12.
163
164**System capability**: SystemCapability.ArkUI.ArkUI.Full
165
166**Parameters**
167
168| Name| Type   | Mandatory| Description                                                        |
169| ------ | ------- | ---- | ------------------------------------------------------------ |
170| value  | boolean | Yes  | Whether to allow the user to reset the component status (that is, clear the input) by touching the component again after the input is complete.<br>The value **true** means that the user can reset the component status by touching the component again after the input is complete, and **false** means the opposite.<br>Default value: **true**|
171
172### activateCircleStyle<sup>12+</sup>
173
174activateCircleStyle(options: Optional\<CircleStyleOptions\>)
175
176Sets the background circle style of the grid dot in the activated state.
177
178**Atomic service API**: This API can be used in atomic services since API version 12.
179
180**System capability**: SystemCapability.ArkUI.ArkUI.Full
181
182**Parameters**
183
184| Name| Type   | Mandatory| Description                                                        |
185| ------ | ------- | ---- | ------------------------------------------------------------ |
186| options  | [CircleStyleOptions](#circlestyleoptions12)| Yes  | Background circle style of the grid dot in the activated state.|
187
188## CircleStyleOptions<sup>12+</sup>
189
190**Atomic service API**: This API can be used in atomic services since API version 12.
191
192**System capability**: SystemCapability.ArkUI.ArkUI.Full
193
194
195| Name         | Type| Mandatory| Description|
196| ------------- | ------- | ---- | -------- |
197| color | [ResourceColor](ts-types.md#resourcecolor) | No| Color of the background circle.<br>Default value: same as the value of **pathColor**|
198| radius  | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Radius of the background circle.<br>Default value: 11/6 of **circleRadius**|
199| enableWaveEffect | boolean | No| Whether to enable the wave effect.<br>Default value: **true**|
200
201## Events
202
203In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
204
205### onPatternComplete
206
207onPatternComplete(callback: (input: Array\<number\>) => void)
208
209Invoked when the pattern password input is complete.
210
211**Atomic service API**: This API can be used in atomic services since API version 12.
212
213**System capability**: SystemCapability.ArkUI.ArkUI.Full
214
215**Parameters**
216
217| Name| Type           | Mandatory| Description                                                        |
218| ------ | --------------- | ---- | ------------------------------------------------------------ |
219| input  | Array\<number\> | Yes  | Array of digits that are the indexes of the connected grid dots and are arranged in the same sequence as the dots are connected. The indexes of the grid dots are as follows: 0, 1, 2 for the dots in the first row from left to right; 3, 4, 5 for the dots in the second row; 6, 7, 8 for the dots in the third row.|
220
221### onDotConnect<sup>11+</sup>
222
223onDotConnect(callback: [CallBack](../../apis-basic-services-kit/js-apis-base.md#callback)\<number\>)
224
225Invoked when a grid dot is connected during pattern password input.
226
227The callback parameter is a digit that is the index of the connected grid dot. The indexes of the grid dots are as follows: 0, 1, 2 for the dots in the first row from left to right; 3, 4, 5 for the dots in the second row; 6, 7, 8 for the dots in the third row.
228
229**Atomic service API**: This API can be used in atomic services since API version 12.
230
231**System capability**: SystemCapability.ArkUI.ArkUI.Full
232
233## PatternLockController
234
235Implements the controller bound to the **PatternLock** component for resetting the component status.
236
237### Objects to Import
238
239```typescript
240let patternLockController: PatternLockController = new PatternLockController()
241```
242
243**Atomic service API**: This API can be used in atomic services since API version 12.
244
245**System capability**: SystemCapability.ArkUI.ArkUI.Full
246
247### reset
248
249reset()
250
251Resets the component status.
252
253**Atomic service API**: This API can be used in atomic services since API version 12.
254
255**System capability**: SystemCapability.ArkUI.ArkUI.Full
256
257### setChallengeResult<sup>11+</sup>
258
259setChallengeResult(result: PatternLockChallengeResult): void
260
261Sets the authentication challenge result for the pattern password.
262
263**Atomic service API**: This API can be used in atomic services since API version 12.
264
265**System capability**: SystemCapability.ArkUI.ArkUI.Full
266
267| Name  | Type                                                    | Mandatory| Description      |
268| ------ | ------------------------------------------------------------ | ---- | -------------- |
269| result | [PatternLockChallengeResult](#patternlockchallengeresult11) | Yes  | Authentication challenge result of the pattern password.|
270
271## PatternLockChallengeResult<sup>11+</sup>
272
273**Atomic service API**: This API can be used in atomic services since API version 12.
274
275**System capability**: SystemCapability.ArkUI.ArkUI.Full
276
277| Name   | Description          |
278| ------- | -------------- |
279| CORRECT | The pattern password is correct.|
280| WRONG   | The pattern password is incorrect.|
281
282##  Example
283
284```ts
285// xxx.ets
286import { LengthUnit } from '@kit.ArkUI'
287
288@Entry
289@Component
290struct PatternLockExample {
291  @State passwords: Number[] = []
292  @State message: string = 'please input password!'
293  private patternLockController: PatternLockController = new PatternLockController()
294
295  build() {
296    Column() {
297      Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20)
298      PatternLock(this.patternLockController)
299        .sideLength(200)
300        .circleRadius(9)
301        .pathStrokeWidth(18)
302        .activeColor('#B0C4DE')
303        .selectedColor('#228B22')
304        .pathColor('#90EE90')
305        .backgroundColor('#F5F5F5')
306        .autoReset(true)
307        .activateCircleStyle({
308          color: '#90EE90',
309          radius: { value: 16, unit: LengthUnit.VP },
310          enableWaveEffect: true
311        })
312        .onDotConnect((index: number) => {
313          console.log("onDotConnect index: " + index)
314        })
315        .onPatternComplete((input: Array<number>) => {
316          // If the length of the entered password is less than 5, the system prompts the user to enter the password again.
317          if (input === null || input === undefined || input.length < 5) {
318            this.message = 'The password length needs to be greater than 5, please enter again.'
319            return
320          }
321          // Check whether the password length is greater than 0.
322          if (this.passwords.length > 0) {
323            // Check whether the two passwords are the same. If yes, the system displays a message indicating that the password is set successfully. If no, the system prompts the user to enter the password again.
324            if (this.passwords.toString() === input.toString()) {
325              this.passwords = input
326              this.message = 'Set password successfully: ' + this.passwords.toString()
327              this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT)
328            } else {
329              this.message = 'Inconsistent passwords, please enter again.'
330              this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG)
331            }
332          } else {
333            // The system prompts the user to enter the password again.
334            this.passwords = input
335            this.message = "Please enter again."
336          }
337        })
338      Button('Reset PatternLock').margin(30).onClick(() => {
339        // Reset the pattern lock.
340        this.patternLockController.reset()
341        this.passwords = []
342        this.message = 'Please input password'
343      })
344    }.width('100%').height('100%')
345  }
346}
347```
348
349![patternlock](figures/patternlock.gif)
350