手势密码（Pattern Lock）是移动端最直观的身份验证方式之一。相比数字密码，手势密码更符合触屏设备的交互特性——用户不需要看着键盘，凭借肌肉记忆就能快速绘制。HarmonyOS NEXT ArkUI 提供了 PatternLock 组件，封装了 3×3 九宫格的手势识别、连线渲染和状态管理，开发者只需处理图案回调即可实现完整的设置与验证流程。

本文将深入讲解 PatternLock 组件的使用方法，并通过一个完整的"图案锁屏"实战案例展示手势密码的设置、确认、验证和强度评估等完整流程。

关键词：HarmonyOS、ArkUI、PatternLock、图案锁、手势密码、安全验证

一、PatternLock 组件基础

1.1 API 概述

PatternLock 是 ArkUI 提供的手势密码组件，呈现 3×3（9 个圆点）的矩阵网格。用户通过手指滑动依次连接圆点形成解锁图案：

PatternLock(controller: PatternLockController)
  .sideLength(280)                              // 组件边长（vp）
  .circleRadius(16)                                // 圆点半径
  .pathStrokeWidth(6)                           // 连线粗细
  .activeColor('#1677FF')                       // 激活态颜色（当前选中点）
  .selectedColor('#1677FF')                     // 已选中颜色（路径上的点）
  .regularColor('#CCCCDD')                      // 未选中颜色
  .backgroundColor('#F8F9FA')                   // 背景色
  .onPatternComplete((input: number[]) => { })  // 绘制完成回调

核心属性说明：

• controller：PatternLockController 实例，提供 .reset() 方法清除当前绘制的图案
• sideLength：整个组件的边长。一个正方形区域，9 个圆点在其中均匀排列
• circleRadius：每个圆点的半径。建议 14-18vp，太小不易点中，太大易误触
• pathStrokeWidth：连接线的宽度。建议 4-8vp，太细不明显，太粗遮挡圆点
• activeColor / selectedColor：通常设置为同一颜色，形成统一的连线颜色
• regularColor：未选中圆点的颜色，通常使用浅灰色表示"尚未参与图案"
• onPatternComplete：手指抬起时触发回调，参数为连接顺序的圆点索引数组

1.2 圆点索引

3×3 网格的 9 个圆点按从左到右、从上到下的顺序编号：

0   1   2
3   4   5
6   7   8

onPatternComplete 回调的 input 参数是一个数字数组，按用户连接顺序排列。例如 [0, 1, 2, 5, 8] 表示用户依次连接了第一行的三个点、中间行最右点、最后一行最右点（一个 L 形图案）。

1.3 最少连接数

PatternLock 组件本身不限制最少连接数（用户可以只连 1 个点），但安全最佳实践要求至少连接 4 个点。少于 4 个点的图案组合数太少（只有数百种可能），安全性极低。本文 Demo 在 handlePattern 中强制要求至少 4 个点：

if (input.length < 4) {
  this.showMessage('至少连接 4 个点', '#FF4D4F');
  return;
}

4 个点大约有 1624 种可能的连接方式，5 个点约 7152 种，9 个点可达 140704 种——点数每增加 1，可能的组合数增长约 3-5 倍。

二、设置与确认流程

2.1 两步确认模式

手势密码的设置采用"先绘制 → 再确认"的两步模式，类似设置新密码时的"输入密码 → 确认密码"流程：

if (this.mode === 'setup') {
  if (this.step === 'draw') {
    // 第一步：记住图案
    this.savedPattern = input;
    this.step = 'confirm';
    this.showMessage('请再次绘制以确认图案', '#1677FF');
  } else if (this.step === 'confirm') {
    // 第二步：确认图案
    if (this.arraysEqual(input, this.savedPattern)) {
      this.showMessage('图案设置成功！', '#00B894');
      this.step = 'draw';
    } else {
      this.showMessage('两次图案不一致，请重新绘制', '#FF4D4F');
      this.step = 'draw';
      this.savedPattern = [];
    }
  }
}

两步确认防止用户因为"画错了但不知道"而设置了错误的密码。如果两次绘制的图案不一致，回到第一步重新绘制——savedPattern 清空，之前记忆的图案作废。

arraysEqual 比较两个数组的逐位一致性——顺序和值都必须完全匹配：

arraysEqual(a: number[], b: number[]): boolean {
  if (a.length !== b.length) return false;
  for (let i = 0; i < a.length; i++) {
    if (a[i] !== b[i]) return false;
  }
  return true;
}

注意：图案的方向是敏感的——[0, 1, 2] 和 [2, 1, 0] 被认为是不同的图案（虽然连了相同的三个点，但连接顺序不同）。

2.2 第一步图案的预览

在确认步骤中，用户需要再次绘制刚才的图案。为了帮助用户回忆，本文 Demo 在确认步骤时显示第一步绘制的图案序列：

if (this.mode === 'setup' && this.step === 'confirm') {
  Text('第一步绘制的图案')
  Row() {
    ForEach(this.savedPattern, (dot: number, idx: number) => {
      Text(dot.toString())       // 数字圆点
        .backgroundColor('#1677FF')
      if (idx < savedPattern.length - 1) {
        Text('→')                // 方向箭头
      }
    })
  }
}

每个连接点显示为一个蓝色数字圆点，点之间用 → 箭头连接。这是纯视觉辅助——用户仍然需要通过手势在 PatternLock 组件上绘制图案来确认，不能通过点击这些数字来"自动填充"。

2.3 图案显示规则

第一步绘制的图案在确认步骤中显示为数字序列（如 1 → 4 → 7 → 8）。这帮助用户回忆刚才的连接顺序，但同时也是一次"安全意识测试"——如果用户看着数字序列也想不起来当初怎么画的，说明这个图案可能过于复杂，不适合日常使用。

显示时间只在确认步骤（step === 'confirm'），成功设置或重新绘制后隐藏。

三、验证流程

3.1 模式切换

页面支持两种模式：设置模式（setup）和验证模式（verify）。通过"切换验证" / "切换设置"按钮切换：

switchMode(): void {
  this.mode = this.mode === 'setup' ? 'verify' : 'setup';
  this.step = 'draw';
  this.attemptCount = 0;
  this.controller.reset();
  // 更新提示信息
}

切换到验证模式时：

• 如果已保存图案 → 提示"请绘制已保存的图案进行验证"
• 如果未保存图案 → 提示"请先设置解锁图案"（黄色警告）

3.2 验证逻辑

验证模式下的图案比对：

if (this.mode === 'verify') {
  this.attemptCount++;
  if (this.savedPattern.length === 0) {
    this.showMessage('请先设置解锁图案', '#E09F3E');
    return;
  }
  if (this.arraysEqual(input, this.savedPattern)) {
    this.showMessage('验证成功！图案匹配', '#00B894');
    this.attemptCount = 0;
  } else {
    let remaining = 5 - this.attemptCount;
    if (remaining <= 0) {
      this.showMessage('尝试次数过多，请稍后再试', '#FF4D4F');
    } else {
      this.showMessage('图案错误，还剩 ' + remaining + ' 次机会', '#FF4D4F');
    }
  }
}

验证结果的三种状态：

• 成功：绿色消息"验证成功！"，尝试计数归零
• 失败（有剩余机会）：红色消息"图案错误，还剩 N 次机会"
• 失败（次数用完）：红色消息"尝试次数过多，请稍后再试"

3.3 尝试次数限制

最大允许 5 次错误尝试。5 次全部失败后锁定——这是移动端安全设计的标准做法（Android 默认 5 次，iOS 滑动解锁 5 次后需等待）。超过限制后不显示剩余次数，提示"请稍后再试"。

尝试计数显示在验证记录面板中，“剩余机会"在 >= 3 次错误后变为红色——视觉上的紧迫感提示用户"要小心了”。

四、图案强度评估

4.1 强度分级

图案的强度由连接点数决定：

连接点数	强度	颜色	说明
1-3	弱	红色 #FF4D4F	不安全，组合太少
4-5	一般	橙色 #E09F3E	勉强可用，日常低风险场景
6-7	较强	蓝色 #1677FF	安全性较好，推荐级别
8-9	强	绿色 #00B894	高安全级别，适合重要应用

getStrength(pattern: number[]): { label: string; color: string; level: number } {
  let len = pattern.length;
  if (len <= 3) return { label: '弱', color: '#FF4D4F', level: 1 };
  if (len <= 5) return { label: '一般', color: '#E09F3E', level: 2 };
  if (len <= 7) return { label: '较强', color: '#1677FF', level: 3 };
  return { label: '强', color: '#00B894', level: 4 };
}

强度在设置模式中以进度条形式展示——4 段进度条，填充数与强度等级对应。这是一种比纯文字更直观的视觉化表达。

4.2 不只是点数

实际的安全性不仅取决于点数，还取决于图案的复杂度——交叉线比直线更难猜测，跳点（跳过中间点连接到非相邻点）增加了复杂度。本文的强度评估仅考虑点数，是一个简化的度量。真实的强度评估可以综合考虑：

• 连接点数
• 图案中方向变化的次数
• 是否有交叉线
• 是否使用了全部 4 个角落点

4.3 安全建议

提示文字"建议使用 6 个以上连接点以获得较高安全性"引导用户设置更安全的图案。这个建议放在强度进度条下方，用户设置完成后自然而然看到。

五、PatternLockController 的使用

PatternLockController 是控制组件行为的对象，主要用途是 .reset() 方法——清除当前绘制状态（圆点恢复未选中、连线消失）：

private controller: PatternLockController = new PatternLockController();

// 在需要清除图案时调用
this.controller.reset();

何时调用 reset：

• 设置成功后
• 设置失败（两次不一致）
• 切换模式时
• 重置按钮点击时

reset 只清除视觉状态，不影响 onPatternComplete 回调。用户重新绘制时会再次触发回调。

六、完整交互流程

6.1 设置图案（初始）

进入页面，默认"设置模式"。提示"请绘制解锁图案"。PatternLock 组件显示 9 个灰色圆点，等待用户手势。

6.2 绘制第一步

用户连接了 6 个点（如 0→1→2→5→8→7），手指抬起。提示变为"请再次绘制以确认图案"（蓝色）。PatternLock 自动恢复初始状态，上方显示第一步的数字序列 0 → 1 → 2 → 5 → 8 → 7。

6.3 确认成功

用户再次绘制相同的 0→1→2→5→8→7 图案。提示变为"图案设置成功！“（绿色）。强度面板显示"较强”（蓝色），6/9 个点，进度条 3/4 填充。

6.4 切换到验证

点击"切换验证"按钮，进入验证模式。提示变为"请绘制已保存的图案进行验证"（蓝色）。验证记录面板出现：尝试次数 0，剩余机会 5。

6.5 验证失败

用户绘制了不同的图案。提示变为"图案错误，还剩 4 次机会"（红色）。验证记录更新：尝试次数 1，剩余机会 4。

6.6 验证成功

用户正确绘制保存的图案。提示变为"验证成功！图案匹配"（绿色）。尝试计数归零。

6.7 重置

点击"重置"按钮，保存的图案清除，回到初始设置状态。

七、安全设计原则

7.1 加密存储

本文 Demo 的 savedPattern 存储在内存中（@State 变量），页面关闭后丢失。在实际应用中，图案数据应加密后持久化存储：

• 使用 cryptoFramework API 进行 SHA-256 哈希
• 将哈希值存入 PersistentStorage 或本地数据库
• 验证时将输入图案的哈希值与存储值比较——永远不存储明文图案

7.2 防止暴力尝试

本文的 5 次尝试限制需要在持久化层面强化：

• 连续失败达到上限后，增加 30 秒的冷却时间（不能 reset 绕过）
• 冷却时间随连续失败次数递增（第 2 次超限等 60 秒，第 3 次等 120 秒）
• 在应用层记录失败次数，不能在进程重启后清零

7.3 图案可见性

绘制图案时，连线在屏幕上显示——这在公共场合可能有"肩窥"（Shoulder Surfing）风险。一些安全级别高的应用会在 PatternLock 中增加隐私模式——连线不可见或仅显示短时间，增加被偷窥的难度。

八、进阶扩展方向

8.1 备用验证方式

在图案验证之外提供备用验证——如数字 PIN 码或生物识别（指纹/面部）。图案忘记或连续失败后，用户可以通过备用方式解锁并重置图案。

8.2 图案复杂度校验

在设置图案时增加复杂度校验——拒绝过于简单的图案（如直线、L 形、正方形边框等），强制用户设置有一定复杂度的图案。Android 系统在设置图案锁时会拒绝同一直线上的连接（如 1-2-3）。

8.3 超时自动锁定

验证成功后启动一个计时器——如果用户在一段时间内（如 5 分钟）没有操作，自动重新锁定并需要再次验证。适用于应用锁、支付确认等需要"持续验证"的场景。

8.4 生物特征与图案组合

将 PatternLock 与生物特征验证（指纹、面部）结合——图案作为生物特征不可用时的回退方案，或在关键操作（如修改密码、大额转账）时同时要求两种验证。

九、总结

本文通过"图案锁屏"这个实战案例，全面讲解了 ArkUI PatternLock 组件的使用方法。核心知识点包括：

1. PatternLock API：controller、circleRadius、pathStrokeWidth、activeColor、onPatternComplete
2. 两步确认模式：先绘制 → 再确认 → 防止误设
3. 验证流程：模式切换 + 图案比对 + 5 次尝试限制
4. 图案强度评估：四档分级（弱/一般/较强/强）+ 进度条可视化
5. 安全保障：加密存储、防止暴力尝试、肩窥防护
6. PatternLockController：reset 清除视觉状态

PatternLock 组件将复杂的手势追踪、连线渲染、状态判断封装为简洁的 API，开发者只需关注图案的"业务逻辑"——存储什么、怎么比对、成功/失败后做什么。这种封装度在 ArkUI 组件中具有代表性：复杂交互被简化为"组件 + 回调"的清晰模型。

---