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-component-general-attributes.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 \| string | 是 | 连线的宽度。<br/>默认值：12vp<br/>取值范围：[0, sideLength/3]，超过最大值按最大值处理。 | 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**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192 193| 名称 | 类型 | 必填 | 说明 | 194| ------------- | ------- | ---- | -------- | 195| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 背景圆环颜色。 <br/>默认值：与pathColor值相同<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 196| radius | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 背景圆环的半径。<br/>默认值：circleRadius的11/6<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 197| enableWaveEffect | boolean | 否 | 波浪效果开关。<br/>默认值：true<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 198| enableForeground<sup>15+</sup> | boolean | 否 | 背景圆环是否在前景显示。<br/>默认值：false，背景圆环不在前景显示。 <br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 199 200### skipUnselectedPoint<sup>15+</sup> 201 202skipUnselectedPoint(skipped: boolean) 203 204设置未选中的宫格圆点在密码路径经过时是否自动选中。 205 206**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 207 208**系统能力：** SystemCapability.ArkUI.ArkUI.Full 209 210**参数：** 211 212| 参数名 | 类型 | 必填 | 说明 | 213| ------ | ------- | ---- | ------------------------------------------------------------ | 214| skipped | boolean | 是 | 未选中的宫格圆点在密码路径经过时是否自动选中。<br/>默认值：false，自动选中密码路径经过的宫格圆点。| 215 216## 事件 217 218除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 219 220### onPatternComplete 221 222onPatternComplete(callback: (input: Array\<number\>) => void) 223 224密码输入结束时触发该回调。 225 226**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 227 228**系统能力：** SystemCapability.ArkUI.ArkUI.Full 229 230**参数：** 231 232| 参数名 | 类型 | 必填 | 说明 | 233| ------ | --------------- | ---- | ------------------------------------------------------------ | 234| input | Array\<number\> | 是 | 与选中宫格圆点顺序一致的数字数组，数字为选中宫格圆点的索引值（第一行圆点从左往右依次为0、1、2，第二行圆点依次为3、4、5，第三行圆点依次为6、7、8）。 | 235 236### onDotConnect<sup>11+</sup> 237 238onDotConnect(callback: [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<number\>) 239 240密码输入选中宫格圆点时触发该回调。 241 242回调参数为选中宫格圆点顺序的数字，数字为选中宫格圆点的索引值（第一行圆点从左往右依次为0、1、2，第二行圆点依次为3、4、5，第三行圆点依次为6、7、8）。 243 244**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 245 246**系统能力：** SystemCapability.ArkUI.ArkUI.Full 247 248## PatternLockController 249 250PatternLock组件的控制器，可以通过它进行组件状态重置。 251 252### 导入对象 253 254```typescript 255let patternLockController: PatternLockController = new PatternLockController() 256``` 257 258### constructor 259 260constructor() 261 262PatternLockController的构造函数。 263 264**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268### reset 269 270reset() 271 272重置组件状态。 273 274**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 275 276**系统能力：** SystemCapability.ArkUI.ArkUI.Full 277 278### setChallengeResult<sup>11+</sup> 279 280setChallengeResult(result: PatternLockChallengeResult): void 281 282用于设置图案密码正确或错误状态。 283 284**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 285 286**系统能力：** SystemCapability.ArkUI.ArkUI.Full 287 288| 名称 | 类型 | 必填 | 说明 | 289| ------ | ------------------------------------------------------------ | ---- | -------------- | 290| result | [PatternLockChallengeResult](#patternlockchallengeresult11枚举说明) | 是 | 图案密码状态。 | 291 292## PatternLockChallengeResult<sup>11+</sup>枚举说明 293 294**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 295 296**系统能力：** SystemCapability.ArkUI.ArkUI.Full 297 298| 名称 | 值 | 说明 | 299| ------- | ----- | -------------- | 300| CORRECT | 1 | 图案密码正确。 | 301| WRONG | 2 | 图案密码错误。 | 302 303## 示例 304 305### 示例1（创建图案密码锁） 306 307该示例展示了PatternLock组件的基本使用方法。 308 309```ts 310// xxx.ets 311@Entry 312@Component 313struct PatternLockExample { 314 @State passwords: Number[] = [] 315 @State message: string = 'please input 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 339 340### 示例2（判断密码是否正确） 341 342该示例通过sideLength设置九宫格的大小、circleRadius等属性设置宫格圆点样式、onPatternComplete属性设置密码输入时的回调。 343 344当用户密码输入完成后，按输入的密码不同，给予不同的回应：输入的密码长度小于5时，提示重新输入；第一次输入完成后，提示第二次输入密码；第二次输入完成后，判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入。 345 346通过'Reset PatternLock'按钮，用户可以重置密码锁。 347 348```ts 349// xxx.ets 350import { LengthUnit } from '@kit.ArkUI' 351 352@Entry 353@Component 354struct PatternLockExample { 355 @State passwords: Number[] = [] 356 @State message: string = 'please input password!' 357 private patternLockController: PatternLockController = new PatternLockController() 358 359 build() { 360 Column() { 361 Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20) 362 PatternLock(this.patternLockController) 363 .sideLength(200) 364 .circleRadius(9) 365 .pathStrokeWidth(5) 366 .activeColor('#707070') 367 .selectedColor('#707070') 368 .pathColor('#707070') 369 .backgroundColor('#F5F5F5') 370 .autoReset(true) 371 .activateCircleStyle({ 372 color: '#707070', 373 radius: { value: 16, unit: LengthUnit.VP }, 374 enableWaveEffect: true 375 }) 376 .onDotConnect((index: number) => { 377 console.log("onDotConnect index: " + index) 378 }) 379 .onPatternComplete((input: Array<number>) => { 380 // 输入的密码长度小于5时，提示重新输入 381 if (input.length < 5) { 382 this.message = 'The password length needs to be greater than 5, please enter again.' 383 return 384 } 385 // 判断密码长度是否大于0 386 if (this.passwords.length > 0) { 387 // 判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入 388 if (this.passwords.toString() === input.toString()) { 389 this.passwords = input 390 this.message = 'Set password successfully: ' + this.passwords.toString() 391 this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT) 392 } else { 393 this.message = 'Inconsistent passwords, please enter again.' 394 this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG) 395 } 396 } else { 397 // 提示第二次输入密码 398 this.passwords = input 399 this.message = "Please enter again." 400 } 401 }) 402 Button('Reset PatternLock').margin(30).onClick(() => { 403 // 重置密码锁 404 this.patternLockController.reset() 405 this.passwords = [] 406 this.message = 'Please input password' 407 }) 408 }.width('100%').height('100%') 409 } 410} 411``` 412 413 414
