洛汐文档库

外观

使用前准备

约 562 字大约 2 分钟

2026-07-15

本文档中的 API 分为两类：具有完整参数契约的接口，以及仅恢复到部分成员定义的私有接口。前者可以按示例直接试用；后者的示例会标记为“探测模板”。

1. 声明 Feature

除特别说明外，在 manifest.json 中声明 feature：

{
  "features": [
    { "name": "system.zlib" }
  ]
}

一个应用可以一次声明多个接口：

{
  "features": [
    { "name": "system.zlib" },
    { "name": "system.sensor" },
    { "name": "system.exchange" }
  ]
}

如果安装阶段提示 feature 或权限不允许，应删除该声明或改用公开 API；不要依靠捕获 JS 异常绕过 manifest 校验。

2. 导入与能力探测

在 JS 中导入：

import zlib from '@system.zlib'
// 或
const zlib = require('@system.zlib')

运行前应进行能力探测：

import app from '@system.app'

if (app.canIUse('@system.zlib.decompressSync')) {
  // 调用 API
}

canIUse() 只能证明运行时导出了成员；它不代表当前应用签名、权限、设备状态或配套手机端服务一定允许调用。

推荐同时探测 feature 与方法：

export function canUse(feature, method) {
  try {
    const name = feature.startsWith('@') ? feature : `@${feature}`
    return app.canIUse(name) && app.canIUse(`${name}.${method}`)
  } catch (e) {
    return false
  }
}

3. 统一封装回调接口

多数旧 feature 使用 success/fail/complete，并且 fail 通常是两个位置参数，而不是一个 Error 对象：

export function callFeature(invoke) {
  return new Promise((resolve, reject) => {
    invoke({
      success: resolve,
      fail: (message, code) => reject({ message, code })
    })
  })
}

// 用法
const result = await callFeature(callbacks => {
  exchange.get({ key: 'demo', ...callbacks })
})

不要假定所有 complete 都无参数：例如 system.exchange 和 system.internal.power 的同源 JIDL 把它定义成接收一个字符串。

4. 真机探测记录

逆向文档不能替代目标设备验证。建议至少记录：

  • 固件版本、设备型号、应用包名和签名类型；
  • canIUse('@feature') 与 canIUse('@feature.method') 的结果；
  • 同一参数下同步返回值、成功回调、失败回调和异常；
  • 是否需要手机蓝牙连接、登录状态或健康权限；
  • 应用退到后台、页面销毁后订阅是否仍然存在。

5. 清理原则

传感器、健康数据、微信事件和消息中心都属于订阅型接口。请在页面销毁或应用退出时调用对应取消方法，避免重复回调、句柄泄漏和后台耗电。