更新记录

1.0.0（2026-08-25）

1.0.0

• 首次发布。
• 支持 uni-app 与 uni-app x。
• 支持 Android、iOS、HarmonyOS。
• 提供扫描、初始化、开关锁、密码、IC 卡、指纹、人脸和 WiFi 等 38 项门锁能力。
• 提供统一错误码、持续事件监听和平台能力检测。

平台兼容性

uni-app(5.15)

uni-app x(5.15)

HF TTLock 通通锁蓝牙门锁插件使用说明

hf-ttlock 是面向 uni-app 与 uni-app x 的 UTS API 插件，用于在 Android、iOS 和 HarmonyOS App 中通过蓝牙操作兼容的 TTLock 门锁。插件提供扫描、初始化、开关锁、时间、电量、操作记录、密码、IC 卡、指纹、人脸、WiFi、远程开锁开关等 38 项能力。

本插件是第三方 UTS 封装，不是 TTLock 官方产品。插件只封装端侧 SDK，不包含 TTLock 云平台账号、网关远程开锁、业务服务器或门锁数据托管服务。

运行环境

• 推荐使用 HBuilderX 5.23 或更高版本。
• 最低要求为 HBuilderX、uni-app 或 uni-app x 5.15。
• Android 5.0（API 21）及以上。
• iOS 11.0 及以上。
• HarmonyOS API 17（HarmonyOS 5.0.5）及以上。
• 仅支持 App，不支持 Web、小程序和快应用。
• 普通 uni-app 的 Vue 2 项目可用于 Android 和 iOS；普通 uni-app 如需发行 HarmonyOS，应使用 Vue 3。

普通 uni-app 的加密付费插件目前不能发行到 HarmonyOS。如需在普通 uni-app 项目中使用 HarmonyOS 实现，请购买源码授权版。具体规则以 DCloud UTS 插件发布说明 为准。

安装插件

1. 将插件安装到项目的 uni_modules 目录。
2. 确认插件目录为 uni_modules/hf-ttlock。
3. 在 HBuilderX 中重新运行或构建 App。
4. 真机调试前完成蓝牙权限、HarmonyOS ACL 权限及签名配置。

请从插件根目录导入 API，不要直接导入 utssdk 内部文件：

import {
  checkReady,
  requestBleEnable,
  onScanLock,
  offScanLock,
  startScanLock,
  stopScanLock,
  initLock,
  getCapabilities,
  unlock,
  lock
} from '@/uni_modules/hf-ttlock'

所有异步 API 均使用 success 和 fail 回调，不返回 Promise。

基本使用流程

1. 检查运行环境

checkReady({
  success(result) {
    console.log('运行平台：', result.platform)
    console.log('蓝牙状态：', result.isBleEnabled)
    console.log('SDK 状态：', result.sdkPrepared)

    if (!result.isBleEnabled) {
      requestBleEnable({
        success(enableResult) {
          console.log('蓝牙开启请求结果：', enableResult)
        },
        fail(error) {
          console.error(error.errCode, error.errMsg)
        }
      })
    }
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

调用扫描前，应用还需要按系统要求申请蓝牙相关运行时权限。requestBleEnable 用于请求开启蓝牙，不能代替系统权限申请。

2. 扫描附近门锁

应先注册监听，再启动扫描：

onScanLock((event) => {
  if (event.event == 'deviceFound' && event.device != null) {
    const device = event.device
    console.log(device.scanId)
    console.log(device.deviceName)
    console.log(device.lockMac)
    console.log(device.rssi)
    console.log(device.isSettingMode)
  }

  if (event.event == 'failed' && event.error != null) {
    console.error(event.error.errCode, event.error.errMsg)
  }
})

startScanLock({
  timeout: 15000,
  success(result) {
    console.log('扫描已启动：', result.started)
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

只允许初始化用户有权管理且处于设置模式的门锁。扫描结束或页面退出时停止扫描并取消监听：

stopScanLock({})
offScanLock()

3. 初始化门锁

把扫描结果中的 scanId 和 lockMac 传给 initLock：

initLock({
  scanId: selectedDevice.scanId,
  lockMac: selectedDevice.lockMac,
  timeout: 20000,
  success(result) {
    console.log('门锁初始化成功：', result.lockMac)

    // 请立即把 result.lockData 和 result.lockMac 安全保存到业务系统。
    // 不要把 lockData 输出到生产日志或明文存储。
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

lockData 是门锁鉴权所需的敏感数据。除初始化外，大多数门锁操作都需要显式传入以下上下文：

const context = {
  lockData: '初始化或业务服务器返回的 lockData',
  lockMac: 'AA:BB:CC:DD:EE:FF'
}

每次调用都传入对应门锁的上下文，可避免多把门锁并发使用时串用凭据。

4. 查询门锁能力

不同门锁型号和固件支持的功能可能不同。展示密码、人脸、WiFi、常开模式等入口前，建议先查询能力：

getCapabilities({
  context,
  success(result) {
    console.log('密码：', result.supportsPasscode)
    console.log('IC 卡：', result.supportsICCard)
    console.log('指纹：', result.supportsFingerprint)
    console.log('人脸：', result.supportsFace)
    console.log('WiFi：', result.supportsWifi)
    console.log('远程开锁开关：', result.supportsRemoteUnlockSwitch)
    console.log('常开模式：', result.supportsPassageMode)
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

5. 开锁和关锁

unlock({
  context,
  timeout: 15000,
  success(result) {
    console.log('开锁成功：', result.lockMac)
    console.log('门锁时间：', result.lockTime)
    console.log('剩余电量：', result.electricQuantity)
  },
  fail(error) {
    console.error(error.errCode, error.errMsg, error.nativeCode)
  }
})

lock({
  context,
  success(result) {
    console.log('关锁成功：', result.lockMac)
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

同一时刻只执行一个蓝牙门锁操作。不要并行调用开锁、关锁、凭证管理或配置类接口。

凭证录入示例

新增 IC 卡、指纹或人脸前，应注册统一的进度监听。以下示例录入一张有效期为 7 天的 IC 卡：

import {
  onCredentialProgress,
  offCredentialProgress,
  addICCard
} from '@/uni_modules/hf-ttlock'

onCredentialProgress((event) => {
  console.log(event.kind, event.event, event.currentCount, event.totalCount)

  if (event.event == 'completed' ||
      event.event == 'failed' ||
      event.event == 'cancelled') {
    offCredentialProgress()
  }
})

const startDate = Date.now()
const endDate = startDate + 7 * 24 * 60 * 60 * 1000

addICCard({
  context,
  startDate,
  endDate,
  success(result) {
    console.log('IC 卡编号：', result.cardNumber)
  },
  fail(error) {
    offCredentialProgress()
    console.error(error.errCode, error.errMsg)
  }
})

startDate、endDate、timestamp 和 lockTime 均使用 Unix 毫秒时间戳。

WiFi 配置示例

scanWifiByLock 是让门锁扫描附近 WiFi，并非读取手机系统的 WiFi 列表。配置时，SSID 和密码会通过蓝牙发送给当前门锁。

import {
  scanWifiByLock,
  configWifi
} from '@/uni_modules/hf-ttlock'

scanWifiByLock({
  context,
  success(result) {
    console.log('门锁扫描到的网络：', result.networks)
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

configWifi({
  context,
  ssid: 'WiFi 名称',
  password: 'WiFi 密码',
  success(result) {
    console.log('WiFi 配置完成：', result.ssid)
  },
  fail(error) {
    console.error(error.errCode, error.errMsg)
  }
})

请勿记录或上传 WiFi 密码。setRemoteUnlockSwitch 只配置门锁的远程开锁开关，不提供网关或云端远程开锁服务。

API 列表

完整参数和返回类型以插件中的 utssdk/interface.uts 为准。

权限配置

Android

插件声明以下权限：

• Android 11 及以下：BLUETOOTH、BLUETOOTH_ADMIN、定位权限。
• Android 12 及以上：BLUETOOTH_SCAN、BLUETOOTH_CONNECT、BLUETOOTH_ADVERTISE。

蓝牙扫描和连接权限需要在运行时申请。旧版 Android 的 BLE 扫描与系统定位权限相关，应用应向用户说明权限用于发现和连接附近门锁。

iOS

插件提供以下用途说明键：

• NSBluetoothAlwaysUsageDescription
• NSBluetoothPeripheralUsageDescription

首次访问蓝牙时系统会展示用途说明。正式应用可在打包配置中使用更贴合业务的文案，但应准确说明蓝牙用途。

HarmonyOS

插件声明以下权限：

• ohos.permission.ACCESS_BLUETOOTH
• ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

PERSISTENT_BLUETOOTH_PEERS_MAC 是受限 ACL 权限。使用 HarmonyOS 版本前必须：

1. 在 AppGallery Connect 中为实际应用包名申请该 ACL 权限。
2. 审批通过后重新创建包含该权限的调试或发布 Profile。
3. 确认调试 Profile 同时绑定当前证书和测试设备。
4. 在 HBuilderX 中换用新 Profile 后重新构建。

Profile 未包含该权限时，即使项目编译成功，HAP 也可能因授权失败而无法安装。

错误码

所有失败回调返回实现 IUniError 的错误对象。常用字段包括 errCode、errMsg、operation、platform 和 nativeCode。

nativeCode 仅用于定位三方 SDK 错误，不应作为跨平台业务逻辑的唯一判断条件。

安全与使用注意事项

• lockData 应按门锁密钥材料管理，使用系统安全存储或加密后端保存。
• 不要把 lockData、门锁密码、WiFi 密码或完整错误详情写入日志、埋点和崩溃上报。
• 不要仅使用门锁 MAC 作为身份认证依据。
• 初始化、重置门锁、重置密码、清空凭证等高风险操作应增加业务权限校验和二次确认。
• 扫描以及 IC 卡、指纹、人脸录入属于持续事件；页面退出、任务完成或失败后必须取消对应监听。
• 门锁型号和固件决定具体功能是否可用，接入前请使用 getCapabilities 检查。
• 插件自身不建立账号，也不会把业务数据上传到插件作者服务器；接入方仍需根据实际业务完成隐私合规评估和披露。

常见问题

扫描不到门锁

确认手机蓝牙和系统权限已开启，靠近门锁，并确认待初始化门锁处于设置模式。已初始化的门锁可能不会以可初始化状态出现。

收到 9019005

当前已有蓝牙操作正在执行。等待该操作成功、失败或超时后再发起下一项操作，不要并行发送命令。

HarmonyOS 编译成功但无法安装

重点检查签名 Profile 是否包含 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC，以及 Profile 是否绑定当前证书和测试设备。

某项凭证或 WiFi 功能不可用

先调用 getCapabilities。插件提供统一接口，但不能让门锁获得硬件或固件本身不支持的功能。

是否支持云端远程开锁

不支持。本插件负责手机与门锁之间的端侧蓝牙能力；云平台、网关、业务后台和远程开锁链路需要接入方另行实现。