更新记录

v1.0.0（2026-03-10）下载此版本

jopark-Tuya

平台兼容性

nativeplugins 使用方案（uni-app 原生插件）

本文档用于说明本项目 nativeplugins/ 目录下原生插件的集成方式与推荐使用流程，并提供常用 API 的调用示例，便于稳定接入与排障。

当前目录内主要插件：TuYaUniPlugin（涂鸦/Thingclips/SmartLife 相关能力封装）。

1. 目录结构与插件清单

nativeplugins/
  TuYaUniPlugin/                 # uni-app 原生插件包（Android: aar / iOS: framework）
    package.json                 # 插件描述与原生入口类声明
    ios/LemuTuya.framework/      # iOS framework（内含二进制与依赖 Swift runtime）
  TuYaUniPlugin.zip              # 插件压缩包（用于分发/备份）

2. 插件信息（TuYaUniPlugin）

插件 ID：TuYaUniPlugin
平台：Android / iOS
集成形态：
- iOS：framework（入口类：LemuTuyaPlugin）
- Android：aar（入口类：com.liuguilin.uniplugin_module.TuYaModule）
manifest 注册位置：src/manifest.json → app-plus.nativePlugins.TuYaUniPlugin

插件元信息来源：nativeplugins/TuYaUniPlugin/package.json。

3. 接入步骤（项目已接入时用于核对）

3.1 放置插件目录

确认仓库内存在 nativeplugins/TuYaUniPlugin/（与本文档同级）。
若通过 zip 导入，解压后目录结构需与上面一致。

3.2 在 `manifest.json` 注册

项目目前已在 src/manifest.json 注册：

app-plus.nativePlugins.TuYaUniPlugin.__plugin_info__.name 为 TuYaUniPlugin

如后续替换/升级插件，需确保：

插件 ID 不变（仍为 TuYaUniPlugin），否则 requireNativePlugin 会取不到插件实例。

3.3 配置 AppKey / AppSecret（不要写死在代码里）

项目通过 Vite 环境变量提供涂鸦 AppKey/AppSecret，并在 JS 侧初始化时按平台读取：

Android：VITE_ANDROID_APPKEY / VITE_ANDROID_APPSECRET
iOS：VITE_IOS_APPKEY / VITE_IOS_APPSECRET

对应使用位置：src/utils/TuYaUniPlugin.ts。

建议：

不要把真实密钥写入文档或日志。
.env.* 若包含真实密钥，建议加入 .gitignore 或改为走 CI/私密变量注入。

3.4（可选）原生权限/能力核对

涂鸦配网、蓝牙扫描、家庭定位等能力通常涉及：

网络权限
定位权限（部分 Wi-Fi/蓝牙扫描与系统策略相关）
蓝牙权限（若使用 BLE 扫描/激活）

具体权限以你当前打包平台与插件内实现为准；出现权限类报错时优先检查系统授权与打包配置。

4. JS 侧推荐用法（统一入口 + 单例初始化）

项目内已经封装了两层调用方式：

src/utils/TuYaUniPlugin.ts：更偏“简单初始化”的薄封装（Tuya.init(appKey, appSecret)）
src/utils/TuYaPluginManager.ts：推荐，提供单例、初始化防重复、常用流程封装

4.1 获取插件实例

在 App 端（APP-PLUS）使用：

const plugin = uni.requireNativePlugin('TuYaUniPlugin');

项目推荐用：

import TuYaPluginManager from '@/utils/TuYaPluginManager';
const plugin = TuYaPluginManager.getPlugin();

4.2 初始化（建议在应用生命周期内只做一次）

推荐使用单例初始化，避免重复 init 导致状态不一致：

import TuYaPluginManager from '@/utils/TuYaPluginManager';

TuYaPluginManager.initialize((res) => {
  // res.success / res.data / res.code 等字段以原生返回为准
  console.log('tuya init result:', res);
});

注意：Android 侧实现中 init(appKey, appSecret, callback) 有 try/catch，但涂鸦 SDK 本身并不总能提供“真实初始化成功/失败”的明确回调；因此回调仅用于“是否执行到某一步”的结果提示。

5. 业务推荐流程（与现有页面逻辑一致）

结合 src/pages/index/index.vue 中现有业务流程，推荐顺序如下：

1) （登录阶段）完成 UID 登录

登录页完成 loginOrRegisterWithUid(...) 后，再进入后续家庭/业务包逻辑

2) 注册家庭服务（registerService()）

3) 登录家庭（loginFamily()）

4) 查询家庭列表（queryHomeList(cb)）

5) 查询家庭详情（getHomeDetail(homeId, cb)）

6) 初始化业务 UI 包（initBizBundle(cb)）

现有实现中，即使返回 500 也会继续后续流程（视为“可忽略的异常情况”）

7) 设置当前家庭（shiftCurrentFamily(homeId, homeName)）

8) 获取配网 Token（getToken(homeId, cb) 或 Android 侧 getActivatorToken(homeId, cb)）

并将 Token 保存到本地，供配网页使用：

uni.setStorageSync('configToken', tokenRes)

6. 常用 API 速查（以项目封装为准）

以下清单主要来自：

JS 侧：src/utils/TuYaPluginManager.ts 的 TuYaPluginInterface
Android 原生侧：src/utils/TuYaModule.java 的 @UniJSMethod 方法

iOS 侧能力以 LemuTuya.framework 实现为准；若两端能力不一致，建议以“项目 JS 封装层实际调用得到的结果”为准，并在封装层做平台分支兜底。

6.1 插件与调试

init(callback)：初始化（JS 管理器封装）
setDebugMode(enable: boolean)：设置调试模式
pluginVersion(callback)：获取插件版本

6.2 账号体系（Android 原生侧较完整）

queryVerifyCodeArea(cb)：查询可发送手机验证码的地区白名单
sendVerifyCode(userName, region, countryCode, type, cb)：发送手机验证码
register(countryCode, phoneNumber, passwd, code, cb)：手机号注册
login(countryCode, phone, passwd, cb)：手机号+密码登录
loginWithCode(countryCode, phone, code, cb)：手机号+验证码登录
resetPassword(countryCode, phone, code, newPasswd, cb)：手机号重置密码
sendEmailCode(userName, region, countryCode, type, cb)：发送邮箱验证码
verifyCode(userName, region, countryCode, code, type, cb)：校验验证码
registerAccountWithEmail(countryCode, email, passwd, code, cb)：邮箱注册
loginWithEmail(countryCode, email, passwd, cb)：邮箱+密码登录
loginWithEmailCode(countryCode, email, code, cb)：邮箱+验证码登录
resetPasswordWithEmail(countryCode, email, passwd, emailCode, cb)：邮箱重置密码
sendBindPhoneCode(countryCode, phoneNumber, cb)：绑定手机号前获取验证码
bindPhone(countryCode, phoneNumber, code, cb)：绑定手机号
getBindEmailCode(countryCode, email, cb) / bindEmail(...)：绑定邮箱相关
loginOrRegisterWithUid(countryCode, uid, passwd, cb)：UID 登录（可选创建默认家庭的重载版本）

6.3 家庭（Home）管理

createHome(name, lon, lat, geoName, rooms, cb)：创建家庭
queryHomeList(cb)：查询家庭列表
getHomeDetail(homeId, cb)：查询家庭详情（设备/群组/房间等）
updateHome(homeId, name, lon, lat, geoName, cb)：更新家庭
dismissHome(homeId, cb)：解散家庭
addRoom(homeId, name, cb)：新增房间

JS 侧还封装了：

shiftCurrentFamily(familyId, curName)：UI 业务包设置当前家庭（打开面板前的关键步骤）

6.4 配网（Activator）

Android 原生侧提供：

getActivatorToken(homeId, cb)：获取配网 Token
initConfigWifiParams(ssid, password, timeout, token, cb)：初始化配网参数（监听激活结果/进度）
startConfigWifi() / stopConfigWifi() / destroyConfigWifi()：开始/停止/销毁配网流程

JS 侧封装中存在（视原生实现而定）：

getToken(homeId, cb)：获取配网 Token
startActivator(data, token, homeId, ssid, password, cb)：开始激活
stopActivator(cb)：停止激活
getActivatorDeviceInfo(productId, uuid, mac, cb)：查询待激活设备信息

6.5 面板与小程序（JS 封装侧）

goPanelWithCheckAndTip(devId)：打开设备控制面板（带检查与提示）

小程序相关：

initMiniApp(cb)
openMiniAppByAppId(appId)
openMiniAppByUrl(url)
preloadMiniApp(appId)
vConsoleDebugEnable(isDebug)
clearCacheMiniApp()

7. 回调返回结构与错误处理建议

项目内对回调返回的判断方式主要有两类（取决于原生实现）：

code 风格：res.code === '200' 视为成功，'500' 视为失败/异常（例如首页对 queryHomeList/getHomeDetail/initBizBundle 的判断）。
success/data 风格：res.success === true 或 res.data === 'initSuccess'（例如 TuYaPluginManager.initialize）。

建议在业务层做兼容判断：

以 code === '200' 为主
兼容 success === true
兼容 data === 'initSuccess'

8. 常见问题（FAQ）

8.1 `requireNativePlugin('TuYaUniPlugin')` 返回空/报错

检查 src/manifest.json 是否注册 app-plus.nativePlugins.TuYaUniPlugin
仅在 APP-PLUS 环境调用（建议使用 #ifdef APP-PLUS 包裹）
确认插件目录存在：nativeplugins/TuYaUniPlugin/

8.2 初始化后仍然无法获取家庭/打开面板

确保已完成账号登录（尤其是 UID 登录）
确保已执行 registerService() 与 loginFamily()
打开面板前务必先 shiftCurrentFamily(homeId, homeName)

8.3 配网相关失败/扫描不到设备

检查系统权限（定位/蓝牙/附近设备等）
确认 Wi-Fi SSID/密码与 Token 是否正确
注意不同系统版本对扫描能力的限制（需用户授权）

9. 维护与升级建议

插件升级优先替换 nativeplugins/TuYaUniPlugin/（并同步 zip 备份）
变更 API 时，先在 src/utils/TuYaPluginManager.ts 做单一封装入口，业务页面只调用管理器方法，减少散落调用
iOS/Android 能力不一致时，在管理器层做平台分支与降级策略（避免页面层到处写 isIos 判断）

jopark-Tuya jopark-Tuya

更新记录

v1.0.0（2026-03-10）下载此版本

平台兼容性

nativeplugins 使用方案（uni-app 原生插件）

1. 目录结构与插件清单

2. 插件信息（TuYaUniPlugin）

3. 接入步骤（项目已接入时用于核对）

3.1 放置插件目录

3.2 在 `manifest.json` 注册

3.3 配置 AppKey / AppSecret（不要写死在代码里）

3.4（可选）原生权限/能力核对

4. JS 侧推荐用法（统一入口 + 单例初始化）

4.1 获取插件实例

4.2 初始化（建议在应用生命周期内只做一次）

5. 业务推荐流程（与现有页面逻辑一致）

6. 常用 API 速查（以项目封装为准）

6.1 插件与调试

6.2 账号体系（Android 原生侧较完整）

6.3 家庭（Home）管理

6.4 配网（Activator）

6.5 面板与小程序（JS 封装侧）

7. 回调返回结构与错误处理建议

8. 常见问题（FAQ）

8.1 `requireNativePlugin('TuYaUniPlugin')` 返回空/报错

8.2 初始化后仍然无法获取家庭/打开面板

8.3 配网相关失败/扫描不到设备

9. 维护与升级建议

隐私、权限声明

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

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

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

许可协议

MIT协议

jopark-Tuya

jopark-Tuya jopark-Tuya

更新记录

v1.0.0（2026-03-10） 下载此版本

平台兼容性

nativeplugins 使用方案（uni-app 原生插件）

1. 目录结构与插件清单

2. 插件信息（TuYaUniPlugin）

3. 接入步骤（项目已接入时用于核对）

3.1 放置插件目录

3.2 在 manifest.json 注册

3.3 配置 AppKey / AppSecret（不要写死在代码里）

3.4（可选）原生权限/能力核对

4. JS 侧推荐用法（统一入口 + 单例初始化）

4.1 获取插件实例

4.2 初始化（建议在应用生命周期内只做一次）

5. 业务推荐流程（与现有页面逻辑一致）

6. 常用 API 速查（以项目封装为准）

6.1 插件与调试

6.2 账号体系（Android 原生侧较完整）

6.3 家庭（Home）管理

6.4 配网（Activator）

6.5 面板与小程序（JS 封装侧）

7. 回调返回结构与错误处理建议

8. 常见问题（FAQ）

8.1 requireNativePlugin('TuYaUniPlugin') 返回空/报错

8.2 初始化后仍然无法获取家庭/打开面板

8.3 配网相关失败/扫描不到设备

9. 维护与升级建议

隐私、权限声明

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

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

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

许可协议

MIT协议

jopark-Tuya

Modal title

v1.0.0（2026-03-10）下载此版本

3.2 在 `manifest.json` 注册

8.1 `requireNativePlugin('TuYaUniPlugin')` 返回空/报错