更新记录
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

收藏人数:
https://cnb.cool/diboycn/Diboy.PatternLock
下载插件并导入HBuilder
下载示例项目ZIP
赞赏(0)
下载 4
赞赏 0
下载 12768266
赞赏 1959
赞赏
京公网安备:11010802035340号