1# PatternLock 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @liyujie43--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9图案密码锁组件，以九宫格图案的方式输入密码，用于密码验证场景。手指在PatternLock组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。 10 11> **说明：** 12> 13> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## 子组件 16 17无 18 19## 接口 20 21PatternLock(controller?: PatternLockController) 22 23**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ---------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 31| controller | [PatternLockController](#patternlockcontroller) | 否 | 设置PatternLock组件控制器，可用于控制组件状态重置。 | 32 33## 属性 34 35除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 36 37### sideLength 38 39sideLength(value: Length) 40 41设置组件的宽度和高度（宽高相同）。当设置为0或负数时，组件不显示。 42 43> **说明：** 44> 45> PatternLock组件设置了通用属性宽高比[aspectRatio](ts-universal-attributes-layout-constraints.md#aspectratio)，且不等于1时（组件尺寸被设定为长方形），九宫格依然绘制为正方形（超出组件范围）。 46 47**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| ------ | ---------------------------- | ---- | ------------------ | 55| value | [Length](ts-types.md#length) | 是 | 组件的宽度和高度。默认值：288vp | 56 57### circleRadius 58 59circleRadius(value: Length) 60 61设置宫格中圆点的半径。设置为0或负数时，取默认值。 62 63**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 64 65**系统能力：** SystemCapability.ArkUI.ArkUI.Full 66 67**参数：** 68 69| 参数名 | 类型 | 必填 | 说明 | 70| ------ | ---------------------------- | ---- | ---------------------------------- | 71| value | [Length](ts-types.md#length) | 是 |宫格中圆点的半径。<br/>默认值：6vp<br/>取值范围：(0, sideLength/11]。设置小于等于0的值时，按默认值处理；超过最大值时，按最大值处理。| 72 73### backgroundColor 74backgroundColor(value: ResourceColor) 75 76设置背景颜色。 77 78**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 79 80**系统能力：** SystemCapability.ArkUI.ArkUI.Full 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| ------ | ------------------------------------------ | ---- | ---------------------------------------------------------- | 86| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 背景颜色。 | 87 88### regularColor 89 90regularColor(value: ResourceColor) 91 92设置宫格圆点在“未选中”状态的填充颜色。 93 94**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98**参数：** 99 100| 参数名 | 类型 | 必填 | 说明 | 101| ------ | ------------------------------------------ | ---- | ---------------------------------------------------------- | 102| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 宫格圆点在“未选中”状态的填充颜色。<br/>默认值：'#ff182431' | 103 104### selectedColor 105 106selectedColor(value: ResourceColor) 107 108设置宫格圆点在“选中”状态的填充颜色。 109 110**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 111 112**系统能力：** SystemCapability.ArkUI.ArkUI.Full 113 114**参数：** 115 116| 参数名 | 类型 | 必填 | 说明 | 117| ------ | ------------------------------------------ | ---- | -------------------------------------------------------- | 118| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 宫格圆点在“选中”状态的填充颜色。<br/>默认值：'#ff182431' | 119 120### activeColor 121 122activeColor(value: ResourceColor) 123 124设置宫格圆点在“激活”状态的填充颜色，“激活”状态为手指经过圆点但还未选中的状态。 125 126**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| ------ | ------------------------------------------ | ---- | -------------------------------------------------------- | 134| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 宫格圆点在“激活”状态的填充颜色。<br/>默认值：'#ff182431' | 135 136### pathColor 137 138pathColor(value: ResourceColor) 139 140设置连线的颜色。 141 142**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| ------ | ------------------------------------------ | ---- | ------------------------------------ | 150| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 连线的颜色。<br/>默认值：'#33182431' | 151 152### pathStrokeWidth 153 154pathStrokeWidth(value: number | string) 155 156设置连线的宽度。设置为0或负数时连线不显示。 157 158**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 159 160**系统能力：** SystemCapability.ArkUI.ArkUI.Full 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165| ------ | -------------------------- | ---- | ----------------------------- | 166| value | number \| string | 是 | 连线的宽度。<br/>默认值：12vp<br/>取值范围：(0, sideLength/3]，超过最大值按最大值处理。 | 167 168### autoReset 169 170autoReset(value: boolean) 171 172设置在完成密码输入后再次在组件区域按下时是否重置组件状态。 173 174**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 175 176**系统能力：** SystemCapability.ArkUI.ArkUI.Full 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| ------ | ------- | ---- | ------------------------------------------------------------ | 182| value | boolean | 是 | 在完成密码输入后再次在组件区域按下时是否重置组件状态。<br/>为true时，完成密码输入后再次在组件区域按下时会重置组件状态（即清除之前输入的密码）；为false时，不会重置组件状态。<br/>默认值：true | 183 184### activateCircleStyle<sup>12+</sup> 185 186activateCircleStyle(options: Optional\<CircleStyleOptions\>) 187 188设置宫格圆点在“激活”状态下的背景圆环样式。 189 190**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| ------ | ------- | ---- | ------------------------------------------------------------ | 198| options | Optional\<[CircleStyleOptions](#circlestyleoptions12对象说明)\> | 是 | 宫格圆点在“激活”状态的背景圆环样式。| 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**参数：** 249 250| 参数名 | 类型 | 必填 | 说明 | 251| ------ | --------------- | ---- | ------------------------------------------------------------ | 252| callback | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<number\> | 是 | 密码输入选中宫格圆点时触发该回调。 | 253 254## CircleStyleOptions<sup>12+</sup>对象说明 255 256圆环样式的参数说明。 257 258**系统能力：** SystemCapability.ArkUI.ArkUI.Full 259 260 261| 名称 | 类型 | 只读 | 可选 | 说明 | 262| ------------- | ------- | ---- | -------- | -------- | 263| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 背景圆环颜色。 <br/>默认值：与pathColor值相同。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 264| radius | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 是 | 背景圆环的半径。<br/>默认值：circleRadius的11/6。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 265| enableWaveEffect | boolean | 否 | 是 | 波浪效果开关。<br/>默认值：true，表示波浪效果开关打开，显示波浪效果。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 266| enableForeground<sup>15+</sup> | boolean | 否 | 是 | 背景圆环是否在前景显示。<br/>默认值：false，背景圆环不在前景显示。 <br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 267 268## PatternLockController 269 270PatternLock组件的控制器，用于重置组件状态。 271 272### 导入对象 273 274```typescript 275let patternLockController: PatternLockController = new PatternLockController() 276``` 277 278### constructor 279 280constructor() 281 282PatternLockController的构造函数。 283 284**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 285 286**系统能力：** SystemCapability.ArkUI.ArkUI.Full 287 288### reset 289 290reset() 291 292重置组件状态。 293 294**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 295 296**系统能力：** SystemCapability.ArkUI.ArkUI.Full 297 298### setChallengeResult<sup>11+</sup> 299 300setChallengeResult(result: PatternLockChallengeResult): void 301 302设置图案密码的正确或错误状态。 303 304**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 305 306**系统能力：** SystemCapability.ArkUI.ArkUI.Full 307 308**参数：** 309 310| 参数名 | 类型 | 必填 | 说明 | 311| ------ | ------------------------------------------------------------ | ---- | -------------- | 312| result | [PatternLockChallengeResult](#patternlockchallengeresult11枚举说明) | 是 | 图案密码状态。 | 313 314## PatternLockChallengeResult<sup>11+</sup>枚举说明 315 316图案密码状态。 317 318**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 319 320**系统能力：** SystemCapability.ArkUI.ArkUI.Full 321 322| 名称 | 值 | 说明 | 323| ------- | ----- | -------------- | 324| CORRECT | 1 | 图案密码正确。 | 325| WRONG | 2 | 图案密码错误。 | 326 327## 示例 328 329### 示例1（创建图案密码锁） 330 331该示例展示了PatternLock组件的基本使用方法。 332 333```ts 334// xxx.ets 335@Entry 336@Component 337struct PatternLockExample { 338 @State passwords: number[] = []; 339 @State message: string = 'please input password!'; 340 private patternLockController: PatternLockController = new PatternLockController(); 341 342 build() { 343 Column() { 344 Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20) 345 PatternLock(this.patternLockController) 346 .sideLength(200) 347 .circleRadius(9) 348 .pathStrokeWidth(5) 349 .activeColor('#707070') 350 .selectedColor('#707070') 351 .pathColor('#707070') 352 .backgroundColor('#F5F5F5') 353 .autoReset(true) 354 .onDotConnect((index: number) => { 355 console.info("onDotConnect index: " + index); 356 }) 357 }.width('100%').height('100%') 358 } 359} 360``` 361 362 363 364### 示例2（判断密码是否正确） 365 366该示例通过[sideLength](#sidelength)属性设置九宫格的大小、[circleRadius](#circleradius)等属性设置宫格圆点样式、[onPatternComplete](#onpatterncomplete)属性设置密码输入时的回调。 367 368当用户密码输入完成后，按输入的密码不同，给予不同的回应：输入的密码长度小于5时，提示重新输入；第一次输入完成后，提示第二次输入密码；第二次输入完成后，判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入。 369 370通过'Reset PatternLock'按钮，用户可以重置密码锁。 371 372```ts 373// xxx.ets 374import { LengthUnit } from '@kit.ArkUI'; 375 376@Entry 377@Component 378struct PatternLockExample { 379 @State passwords: number[] = []; 380 @State message: string = 'please input password!'; 381 private patternLockController: PatternLockController = new PatternLockController(); 382 383 build() { 384 Column() { 385 Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20) 386 PatternLock(this.patternLockController) 387 .sideLength(200) 388 .circleRadius(9) 389 .pathStrokeWidth(5) 390 .activeColor('#707070') 391 .selectedColor('#707070') 392 .pathColor('#707070') 393 .backgroundColor('#F5F5F5') 394 .autoReset(true) 395 .activateCircleStyle({ 396 color: '#707070', 397 radius: { value: 16, unit: LengthUnit.VP }, 398 enableWaveEffect: true 399 }) 400 .onDotConnect((index: number) => { 401 console.info("onDotConnect index: " + index); 402 }) 403 .onPatternComplete((input: Array<number>) => { 404 // 输入的密码长度小于5时，提示重新输入 405 if (input.length < 5) { 406 this.message = 'The password length needs to be greater than 5, please enter again.'; 407 return; 408 } 409 // 判断密码长度是否大于0 410 if (this.passwords.length > 0) { 411 // 判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入 412 if (this.passwords.toString() === input.toString()) { 413 this.passwords = input; 414 this.message = 'Set password successfully: ' + this.passwords.toString(); 415 this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT); 416 } else { 417 this.message = 'Inconsistent passwords, please enter again.'; 418 this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG); 419 } 420 } else { 421 // 提示第二次输入密码 422 this.passwords = input; 423 this.message = "Please enter again."; 424 } 425 }) 426 Button('Reset PatternLock').margin(30).onClick(() => { 427 // 重置密码锁 428 this.patternLockController.reset(); 429 this.passwords = []; 430 this.message = 'Please input password'; 431 }) 432 }.width('100%').height('100%') 433 } 434} 435``` 436 437 438
