更新记录

1.0.0(2026-11-16) 下载此版本

  • 新增纯前端 uni-app x Vapor 九宫格手势锁组件。
  • 支持 set、verify、display 三种模式。
  • 支持路径实时更新、完成、失败事件和 reset 方法。
  • verify 模式只抛出用户路径,由业务层结合安全存储完成校验。
  • 新增 disabled 属性和 showError() 方法。
  • 支持错误反馈、可选震动、自动补点和严格路径解析。
  • 支持最少节点数、重复节点拦截和中间节点自动补点。
  • 支持 Web、Android、iOS 和 HarmonyOS。

平台兼容性

uni-app x(5.34)

Chrome Chrome插件版本 Safari Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本 微信小程序
√ 1.0.0 × 5.0 1.0.0 12 1.0.0 20 1.0.0 -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
√ √ √ √

Diboy Pattern Lock

面向 uni-app x Vapor 的纯前端九宫格手势组件:滑动、连线、确认、验证反馈,一套 API 覆盖 Android、iOS、HarmonyOS 和 Web。

当前版本:1.0.0

适合登录解锁、账本隐私入口、应用手势锁和设置手势密码等场景。组件不包含原生代码,不存储密码,也不负责哈希或错误次数锁定。

为什么选择它

  • 纯 .uvue 实现,不引入原生插件和额外权限。
  • 支持 set、verify、display 三种工作模式。
  • 自动补齐跨越的中间节点,防止重复经过节点。
  • 支持最少节点数、错误轨迹、震动反馈和业务锁定。
  • verify 只抛出用户路径,安全校验交给业务层处理;业务层可以使用 Diboy.SecureStorage 安全存储校验所需的数据。
  • 可通过业务层主题色适配暗黑模式;组件无内置文案,适合多语言项目;支持通过 size 调整宽屏布局。

使用

组件符合 easycom 目录约定,可直接使用:

<DiboyPatternLock
  mode="verify"
  :min-points="4"
  @update="onUpdate"
  @complete="onComplete"
  @fail="onFail"
/>

先选模式

场景 模式 组件行为
设置新手势 set 用户连续绘制两次,路径一致后触发 complete
正式解锁 verify 绘制一次,把路径交给业务层进行哈希校验
展示或教学回显 display 只展示 path,不响应触摸,不触发事件

正式解锁推荐使用 verify,不要把正确路径作为组件属性传入,也不要在 display 模式中向用户展示敏感手势。

安装与支持范围

在 HBuilderX 中通过 uni_modules 安装,或将 uni_modules/diboy-pattern-lock 目录放入项目。

平台 支持情况 说明
Android 支持 uni-app x Vapor
iOS 代码支持,待真机验证 uni-app x Vapor
HarmonyOS 代码支持,待真机验证 uni-app x Vapor
Web 支持 Web 端不执行震动

建议使用 HBuilderX 5.34.0 或更高版本。

API

属性/事件 类型 默认值 说明
mode set \| verify \| display set 设置、验证或只读展示模式
path string '' display 模式的展示路径;verify 模式不需要传入
normal-color string #19be6b 正常轨迹和节点颜色
error-color string #e74c3c 错误轨迹和节点颜色
min-points number 4 有效路径的最少节点数
size number 300 组件边长,单位 px,宽屏布局时可由业务层动态设置
vibrate boolean true 是否启用成功/失败震动提示,Web 端自动忽略
disabled boolean false 是否禁止触摸输入,适合业务层锁定状态
@update (path: string) => void - 绘制过程实时触发
@complete (path: string) => void - 有效绘制完成时触发;set 模式需要二次确认,verify 模式单次完成
@fail (payload) => void - set 模式确认失败或少于最少点数时触发,payload 为 { path, reason }

暴露方法

方法 说明
reset() 清空当前路径、确认状态和错误状态
showError() 显示错误轨迹 500ms,供业务层校验失败后调用

path 的含义

path 是逗号分隔的节点编号,不是组件自动生成的密码文本。节点编号固定如下:

0 1 2
3 4 5
6 7 8

例如 path="0,1,2,5,8" 表示用户依次经过左上、上中、右上、右中、右下节点。

  • verify 模式:不传入正确路径。组件只负责采集一次用户路径并通过 complete 抛出,由业务层自行进行哈希校验;业务层可以使用 Diboy.SecureStorage 安全保存哈希结果。
  • display 模式:path 是组件需要展示的只读路径。
  • set 模式:通常不需要传入 path,组件会记录用户第一次绘制的路径,并要求第二次绘制确认。

path 本身属于敏感业务数据,不能直接当作安全密码保存、日志输出或网络传输。正式业务应由业务层完成哈希校验、错误次数限制、锁定和冷却时间,并可使用 Diboy.SecureStorage 保存校验所需的数据;组件不是安全验证边界。

震动反馈

组件默认开启震动提示,但可以通过 :vibrate="false" 关闭。成功完成时触发一次轻振动,路径点数不足、验证失败或两次设置不一致时触发一次中振动。绘制过程中经过节点不会连续震动,避免造成噪音和交互卡顿。display 模式不会触发震动。设备静音、关闭系统触感或电量不足时,系统可能不会产生震动,这不影响组件使用。

组件暴露 reset() 方法:

<script setup>
const patternLock = ref<any>(null)
function resetLock() {
  patternLock.value?.reset()
}
</script>

<DiboyPatternLock ref="patternLock" />

组件同时暴露 showError(),业务层完成安全校验后发现路径不匹配时调用它,组件会显示错误颜色 500ms 并触发一次中振动:

import { getItem, initialize } from '@/uni_modules/diboy-secure-storage'

async function onComplete(path: string) {
  const inputHash = hash(path)
  await initialize()
  const savedHash = await getItem('pattern_hash')
  if (inputHash === savedHash) {
    unlock()
  } else {
    patternLock.value?.showError()
  }
}

上例中的 hash 由业务项目提供,initialize() 和 getItem() 来自 Diboy.SecureStorage。实际业务应补充异常处理,不要把正确路径作为 verify 模式的属性传入组件。手势路径空间有限,哈希结果并不等于绝对安全;高安全场景还应叠加系统生物识别、PIN 或服务端风控。

设置手势时,在 set 模式的 complete 回调中对确认后的路径计算哈希,再写入安全存储:

import { initialize, setItem } from '@/uni_modules/diboy-secure-storage'

async function onPatternSet(path: string) {
  const patternHash = hash(path)
  await initialize()
  await setItem('pattern_hash', patternHash)
}

安全存储中只保存哈希或加盐结果,不保存 0,1,2,5,8 这类明文路径。

路径使用逗号分隔,例如 0,1,2,5,8。跨越一个未访问的中间节点时会自动补入,例如 0 -> 2 会变为 0,1,2。重复节点不会再次加入。

set 模式需要连续绘制两次相同路径;第一次有效绘制后组件清空轨迹等待确认。verify 模式绘制一次后直接触发 complete,由业务层进行安全校验。display 模式只展示 path,不响应触摸,也不会触发事件。错误轨迹显示 500ms 后自动清空。disabled 为 true 时保留展示状态但不响应触摸。

业务层错误次数锁定

错误次数、冷却时间和安全存储应由业务层管理。业务页面在 complete 中结合 Diboy.SecureStorage 比较哈希;失败时先调用 showError(),再根据策略设置 disabled,达到阈值后锁定并启动冷却,冷却结束后调用 reset()。手势路径只用于内存中的即时哈希计算,不应直接当作安全凭据保存。

平台与主题

组件使用简单 class、绝对定位和容器级触摸事件,支持 Vapor 模式。节点几何位置根据实际布局重新测量,组件保持正方形并支持 size 调整,适用于宽屏。组件不包含可翻译文案,业务层可自由实现多语言;组件不会自动切换系统暗黑主题,业务层应按主题传入适合背景的颜色。

验证状态

  • Android:已完成 HBuilderX 5.34 Vapor 字节码编译、Android 14 真机九项交互验收和 3/3 自动化 Smoke 测试。
  • Web:已完成 Chrome 自动化测试 3/3 和手动交互验收。
  • iOS:组件代码按 uni-app x Vapor 编写,当前发布环境未完成签名基座真机验证。
  • HarmonyOS:组件代码按 uni-app x Vapor 编写,当前发布环境未配置 DevEco Studio,暂未完成真机验证。

欢迎在真实设备上反馈触摸坐标、布局或震动差异。

作者:Diboy · 许可证:MIT

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT License

Copyright (c) Diboy

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

暂无用户评论。