• 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-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| enableForeground<sup>14+</sup> | boolean | No| Whether the background circle is displayed in the foreground.<br>Default value: **true**|
201
202### skipUnselectedPoint<sup>14+</sup>
203
204skipUnselectedPoint(skipped: boolean)
205
206Sets whether unselected dots in the grid are automatically selected when the password path passes over them.
207
208**Atomic service API**: This API can be used in atomic services since API version 14.
209
210**System capability**: SystemCapability.ArkUI.ArkUI.Full
211
212**Parameters**
213
214| Name| Type   | Mandatory| Description                                                        |
215| ------ | ------- | ---- | ------------------------------------------------------------ |
216| skipped  | boolean | Yes  | Whether unselected dots in the grid are automatically selected when the password path passes over them. Default value: **false**|
217
218## Events
219
220In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
221
222### onPatternComplete
223
224onPatternComplete(callback: (input: Array\<number\>) => void)
225
226Invoked when the pattern password input is complete.
227
228**Atomic service API**: This API can be used in atomic services since API version 12.
229
230**System capability**: SystemCapability.ArkUI.ArkUI.Full
231
232**Parameters**
233
234| Name| Type           | Mandatory| Description                                                        |
235| ------ | --------------- | ---- | ------------------------------------------------------------ |
236| 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.|
237
238### onDotConnect<sup>11+</sup>
239
240onDotConnect(callback: [CallBack](../../apis-basic-services-kit/js-apis-base.md#callback)\<number\>)
241
242Invoked when a grid dot is connected during pattern password input.
243
244The 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.
245
246**Atomic service API**: This API can be used in atomic services since API version 12.
247
248**System capability**: SystemCapability.ArkUI.ArkUI.Full
249
250## PatternLockController
251
252Implements the controller bound to the **PatternLock** component for resetting the component status.
253
254### Objects to Import
255
256```typescript
257let patternLockController: PatternLockController = new PatternLockController()
258```
259
260### constructor
261
262constructor()
263
264A constructor used to create a **PatternLockController** instance.
265
266**Atomic service API**: This API can be used in atomic services since API version 12.
267
268**System capability**: SystemCapability.ArkUI.ArkUI.Full
269
270### reset
271
272reset()
273
274Resets the component status.
275
276**Atomic service API**: This API can be used in atomic services since API version 12.
277
278**System capability**: SystemCapability.ArkUI.ArkUI.Full
279
280### setChallengeResult<sup>11+</sup>
281
282setChallengeResult(result: PatternLockChallengeResult): void
283
284Sets the authentication challenge result for the pattern password.
285
286**Atomic service API**: This API can be used in atomic services since API version 12.
287
288**System capability**: SystemCapability.ArkUI.ArkUI.Full
289
290| Name  | Type                                                        | Mandatory| Description          |
291| ------ | ------------------------------------------------------------ | ---- | -------------- |
292| result | [PatternLockChallengeResult](#patternlockchallengeresult11) | Yes  | Authentication challenge result of the pattern password.|
293
294## PatternLockChallengeResult<sup>11+</sup>
295
296**Atomic service API**: This API can be used in atomic services since API version 12.
297
298**System capability**: SystemCapability.ArkUI.ArkUI.Full
299
300| Name   | Description          |
301| ------- | -------------- |
302| CORRECT | The pattern password is correct.|
303| WRONG   | The pattern password is incorrect.|
304
305##  Example
306
307This 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**.
308
309When 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.
310
311The user can click **Reset PatternLock** to reset the password lock.
312
313```ts
314// xxx.ets
315import { LengthUnit } from '@kit.ArkUI'
316
317@Entry
318@Component
319struct PatternLockExample {
320  @State passwords: Number[] = []
321  @State message: string = 'please input password!'
322  private patternLockController: PatternLockController = new PatternLockController()
323
324  build() {
325    Column() {
326      Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20)
327      PatternLock(this.patternLockController)
328        .sideLength(200)
329        .circleRadius(9)
330        .pathStrokeWidth(18)
331        .activeColor('#B0C4DE')
332        .selectedColor('#228B22')
333        .pathColor('#90EE90')
334        .backgroundColor('#F5F5F5')
335        .autoReset(true)
336        .activateCircleStyle({
337          color: '#90EE90',
338          radius: { value: 16, unit: LengthUnit.VP },
339          enableWaveEffect: true
340        })
341        .onDotConnect((index: number) => {
342          console.log("onDotConnect index: " + index)
343        })
344        .onPatternComplete((input: Array<number>) => {
345          // If the length of the entered password is less than 5, the system prompts the user to enter the password again.
346          if (input.length < 5) {
347            this.message = 'The password length needs to be greater than 5, please enter again.'
348            return
349          }
350          // Check whether the password length is greater than 0.
351          if (this.passwords.length > 0) {
352            // 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.
353            if (this.passwords.toString() === input.toString()) {
354              this.passwords = input
355              this.message = 'Set password successfully: ' + this.passwords.toString()
356              this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT)
357            } else {
358              this.message = 'Inconsistent passwords, please enter again.'
359              this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG)
360            }
361          } else {
362            // The system prompts the user to enter the password again.
363            this.passwords = input
364            this.message = "Please enter again."
365          }
366        })
367      Button('Reset PatternLock').margin(30).onClick(() => {
368        // Reset the pattern lock.
369        this.patternLockController.reset()
370        this.passwords = []
371        this.message = 'Please input password'
372      })
373    }.width('100%').height('100%')
374  }
375}
376```
377
378![patternlock](figures/patternlock.gif)
379