洛汐文档库

外观

system.exchange

约 655 字大约 2 分钟

2026-07-15

跨作用域字符串键值交换。与 system.storage 的应用私有数据库不同，底层使用系统 property/exchange 服务。

import exchange from '@system.exchange'

作用域

scope含义限制
global全局交换域默认；不能同时提供 package、sign
vendor厂商域不能同时提供 package、sign
application指定应用域固件实现要求同时提供目标 package 与 sign

package、sign 是目标固件实现中存在的扩展字段；上游 JIDL 没有公开它们。

底层会给 key 加作用域前缀，因此同名 key 在不同 scope 下不是同一条记录。固件会拒绝不支持的 scope、超长 key/value，以及 scope 与 package/sign 的非法组合。

exchange.set(options)

参数类型必填
keyString是
valueString是
scopeString否，默认 global
packageStringapplication scope 时是
signStringapplication scope 时是
successFunction否；接收字符串
failFunction否；(message, code)
completeFunction否

同步返回 void。success 的字符串参数由底层 property 回调产生，业务代码通常不需要解析它。

exchange.get(options)

参数同上但不需要 value。成功回调接收 { value: string }。

exchange.remove(options)

删除指定 key。参数为 key、作用域字段和通用回调。

exchange.clear(options)

清空指定作用域。参数为作用域字段和通用回调。

exchange.set({
  key: 'demo-key',
  value: 'demo-value',
  scope: 'global',
  success: () => exchange.get({
    key: 'demo-key',
    scope: 'global',
    success: res => console.log(res.value)
  })
})

Promise 封装与完整 CRUD

function getExchange(key, scope = 'global') {
  return new Promise((resolve, reject) => {
    exchange.get({
      key,
      scope,
      success: ({ value }) => resolve(value),
      fail: (message, code) => reject({ message, code })
    })
  })
}

function removeExchange(key, scope = 'global') {
  return new Promise((resolve, reject) => {
    exchange.remove({
      key,
      scope,
      success: resolve,
      fail: (message, code) => reject({ message, code })
    })
  })
}

function clearExchange(scope = 'global') {
  return new Promise((resolve, reject) => {
    exchange.clear({
      scope,
      success: resolve,
      fail: (message, code) => reject({ message, code })
    })
  })
}

clear() 会影响整个指定作用域，不要用它代替逐 key 清理。特别是 global 或 vendor 可能由多个组件共享。

application scope 探测模板

exchange.get({
  key: 'shared-key',
  scope: 'application',
  package: '目标应用包名',
  sign: '目标应用签名标识',
  success: ({ value }) => console.log(value),
  fail: (message, code) => console.error(code, message)
})

固件证明这两个字段必须同时提供，但没有证明 sign 需要证书摘要、别名还是厂商内部 token。除非你掌握目标系统协议，否则不要猜测其格式。

固件会检查 key 和 value 长度，但二进制没有暴露稳定的 JS 层最大值；不要把它用于大块数据。

它只存字符串：对象需要 JSON.stringify()，读取后用 JSON.parse()，并处理旧版本/损坏数据。敏感 token 不应明文放入全局交换域。

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
✅❌

获取源代码