• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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-component-general-attributes.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  | Width of the path stroke.<br>Default value: **12vp**<br>Value range: [0, sideLength/3]. If the value exceeds the maximum value, the maximum value is used.|
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**System capability**: SystemCapability.ArkUI.ArkUI.Full
191
192
193| Name         | Type| Mandatory| Description|
194| ------------- | ------- | ---- | -------- |
195| color | [ResourceColor](ts-types.md#resourcecolor) | No| Color of the background circle.<br>Default value: same as the value of **pathColor**<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
196| radius  | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Radius of the background circle.<br>Default value: 11/6 of **circleRadius**<br>**Atomic service API**: This API can be used in atomic services since API version 12. |
197| enableWaveEffect | boolean | No| Whether to enable the wave effect.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 12. |
198| enableForeground<sup>15+</sup> | boolean | No| Whether the background circle is displayed in the foreground.<br>Default value: **false**, meaning the background circle is not displayed in the foreground<br>**Atomic service API**: This API can be used in atomic services since API version 15.|
199
200### skipUnselectedPoint<sup>15+</sup>
201
202skipUnselectedPoint(skipped: boolean)
203
204Sets whether unselected dots in the grid are automatically selected when the password path passes over them.
205
206**Atomic service API**: This API can be used in atomic services since API version 15.
207
208**System capability**: SystemCapability.ArkUI.ArkUI.Full
209
210**Parameters**
211
212| Name| Type   | Mandatory| Description                                                        |
213| ------ | ------- | ---- | ------------------------------------------------------------ |
214| skipped  | boolean | Yes  | Whether unselected dots in the grid are automatically selected when the password path passes over them.<br>Default value: **false**, meaning unselected dots are automatically selected|
215
216## Events
217
218In addition to the [universal events](ts-component-general-events.md), the following events are supported.
219
220### onPatternComplete
221
222onPatternComplete(callback: (input: Array\<number\>) => void)
223
224Invoked when the pattern password input is complete.
225
226**Atomic service API**: This API can be used in atomic services since API version 12.
227
228**System capability**: SystemCapability.ArkUI.ArkUI.Full
229
230**Parameters**
231
232| Name| Type           | Mandatory| Description                                                        |
233| ------ | --------------- | ---- | ------------------------------------------------------------ |
234| 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.|
235
236### onDotConnect<sup>11+</sup>
237
238onDotConnect(callback: [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<number\>)
239
240Invoked when a grid dot is connected during pattern password input.
241
242The 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.
243
244**Atomic service API**: This API can be used in atomic services since API version 12.
245
246**System capability**: SystemCapability.ArkUI.ArkUI.Full
247
248## PatternLockController
249
250Implements the controller bound to the **PatternLock** component for resetting the component status.
251
252### Objects to Import
253
254```typescript
255let patternLockController: PatternLockController = new PatternLockController()
256```
257
258### constructor
259
260constructor()
261
262A constructor used to create a **PatternLockController** instance.
263
264**Atomic service API**: This API can be used in atomic services since API version 12.
265
266**System capability**: SystemCapability.ArkUI.ArkUI.Full
267
268### reset
269
270reset()
271
272Resets the component status.
273
274**Atomic service API**: This API can be used in atomic services since API version 12.
275
276**System capability**: SystemCapability.ArkUI.ArkUI.Full
277
278### setChallengeResult<sup>11+</sup>
279
280setChallengeResult(result: PatternLockChallengeResult): void
281
282Sets the authentication challenge result for the pattern password.
283
284**Atomic service API**: This API can be used in atomic services since API version 12.
285
286**System capability**: SystemCapability.ArkUI.ArkUI.Full
287
288| Name  | Type                                                        | Mandatory| Description          |
289| ------ | ------------------------------------------------------------ | ---- | -------------- |
290| result | [PatternLockChallengeResult](#patternlockchallengeresult11) | Yes  | Authentication challenge result of the pattern password.|
291
292## PatternLockChallengeResult<sup>11+</sup>
293
294**Atomic service API**: This API can be used in atomic services since API version 12.
295
296**System capability**: SystemCapability.ArkUI.ArkUI.Full
297
298| Name   | Value   | Description          |
299| ------- | ----- | -------------- |
300| CORRECT | 1  | The pattern password is correct.|
301| WRONG   | 2  | The pattern password is incorrect.|
302
303##  Example
304
305### Example 1: Creating a Pattern Lock
306
307This example shows the basic usage of the **PatternLock** component.
308
309```ts
310// xxx.ets
311@Entry
312@Component
313struct PatternLockExample {
314  @State passwords: Number[] = []
315  @State message: string = 'Enter password'
316  private patternLockController: PatternLockController = new PatternLockController()
317
318  build() {
319    Column() {
320      Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20)
321      PatternLock(this.patternLockController)
322        .sideLength(200)
323        .circleRadius(9)
324        .pathStrokeWidth(5)
325        .activeColor('#707070')
326        .selectedColor('#707070')
327        .pathColor('#707070')
328        .backgroundColor('#F5F5F5')
329        .autoReset(true)
330        .onDotConnect((index: number) => {
331          console.log("onDotConnect index: " + index)
332        })
333    }.width('100%').height('100%')
334  }
335}
336```
337
338![patternlock](figures/patternlock1.gif)
339
340### Example 2: Verifying the Password
341
342This example demonstrates how to set the size of the grid using **sideLength**, customize the dot styles using **circleRadius** and other attributes, and set a callback for password input using **onPatternComplete**.
343
344When the user completes the password input, different responses are given based on the input:
345
346- If the password length is less than 5, a message is displayed to prompt the user to re-enter the password.
347- After the first input, a message is displayed to prompt the user to enter the password again.
348- 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.
349
350The user can click **Reset PatternLock** to reset the password lock.
351
352```ts
353// xxx.ets
354import { LengthUnit } from '@kit.ArkUI'
355
356@Entry
357@Component
358struct PatternLockExample {
359  @State passwords: Number[] = []
360  @State message: string = 'please input password!'
361  private patternLockController: PatternLockController = new PatternLockController()
362
363  build() {
364    Column() {
365      Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20)
366      PatternLock(this.patternLockController)
367        .sideLength(200)
368        .circleRadius(9)
369        .pathStrokeWidth(5)
370        .activeColor('#707070')
371        .selectedColor('#707070')
372        .pathColor('#707070')
373        .backgroundColor('#F5F5F5')
374        .autoReset(true)
375        .activateCircleStyle({
376          color: '#707070',
377          radius: { value: 16, unit: LengthUnit.VP },
378          enableWaveEffect: true
379        })
380        .onDotConnect((index: number) => {
381          console.log("onDotConnect index: " + index)
382        })
383        .onPatternComplete((input: Array<number>) => {
384          // If the length of the entered password is less than 5, the system prompts the user to enter the password again.
385          if (input.length < 5) {
386            this.message = 'The password length needs to be greater than 5, please enter again.'
387            return
388          }
389          // Check whether the password length is greater than 0.
390          if (this.passwords.length > 0) {
391            // 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.
392            if (this.passwords.toString() === input.toString()) {
393              this.passwords = input
394              this.message = 'Set password successfully: ' + this.passwords.toString()
395              this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT)
396            } else {
397              this.message = 'Inconsistent passwords, please enter again.'
398              this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG)
399            }
400          } else {
401            // The system prompts the user to enter the password again.
402            this.passwords = input
403            this.message = "Please enter again."
404          }
405        })
406      Button('Reset PatternLock').margin(30).onClick(() => {
407        // Reset the pattern lock.
408        this.patternLockController.reset()
409        this.passwords = []
410        this.message = 'Please input password'
411      })
412    }.width('100%').height('100%')
413  }
414}
415```
416
417![patternlock](figures/patternlock.gif)
418