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 dots in a grid. 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 dots in a grid.<br>Default value: **6vp**<br>Value range: (0, sideLength/11]<br>Values less than or equal to 0 are handled as the default value, and values exceeding the maximum are handled as the maximum.|
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 for the dots in a grid when they are 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 dots 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### constructor
244
245constructor()
246
247A constructor used to create a **PatternLockController** instance.
248
249**Atomic service API**: This API can be used in atomic services since API version 12.
250
251**System capability**: SystemCapability.ArkUI.ArkUI.Full
252
253### reset
254
255reset()
256
257Resets the component status.
258
259**Atomic service API**: This API can be used in atomic services since API version 12.
260
261**System capability**: SystemCapability.ArkUI.ArkUI.Full
262
263### setChallengeResult<sup>11+</sup>
264
265setChallengeResult(result: PatternLockChallengeResult): void
266
267Sets the authentication challenge result for the pattern password.
268
269**Atomic service API**: This API can be used in atomic services since API version 12.
270
271**System capability**: SystemCapability.ArkUI.ArkUI.Full
272
273| Name  | Type                                                        | Mandatory| Description          |
274| ------ | ------------------------------------------------------------ | ---- | -------------- |
275| result | [PatternLockChallengeResult](#patternlockchallengeresult11) | Yes  | Authentication challenge result of the pattern password.|
276
277## PatternLockChallengeResult<sup>11+</sup>
278
279**Atomic service API**: This API can be used in atomic services since API version 12.
280
281**System capability**: SystemCapability.ArkUI.ArkUI.Full
282
283| Name   | Description          |
284| ------- | -------------- |
285| CORRECT | The pattern password is correct.|
286| WRONG   | The pattern password is incorrect.|
287
288##  Example
289
290This example shows the basic usage of the **PatternLock** component. It sets the size of the grid using **sideLength**, customizes the dot styles using **circleRadius** and other attributes, and sets a callback for password input using **onPatternComplete**.
291
292When the user completes the password input, different responses are given based on the input:<br>- If the password length is less than 5, a message is displayed to prompt the user to re-enter the password.<br>- After the first input, a message is displayed to prompt the user to enter the password again.<br>- After the second input, the system checks whether the two inputs match. If they match, a message is displayed to indicate that the password setup is successful; otherwise, the user is prompted to re-enter the password.
293
294The user can click **Reset PatternLock** to reset the password lock.
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          // If the length of the entered password is less than 5, the system prompts the user to enter the password again.
329          if (input.length < 5) {
330            this.message = 'The password length needs to be greater than 5, please enter again.'
331            return
332          }
333          // Check whether the password length is greater than 0.
334          if (this.passwords.length > 0) {
335            // 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.
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            // The system prompts the user to enter the password again.
346            this.passwords = input
347            this.message = "Please enter again."
348          }
349        })
350      Button('Reset PatternLock').margin(30).onClick(() => {
351        // Reset the pattern lock.
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