window.ty 兼容接口

HeimLink 为双路浇花器实际使用的 38 个涂鸦原生 API 提供同名入口。32 项有宿主实现（部分受设备/平台限制），4 项明确 NOT_PLANNED，2 项当前 NOT_SUPPORTED。2026-09-29 起另外提供这些入口在涂鸦中的配对接口：各事件的 offXxx、device.unregisterDeviceListListener 与 device.publishDps。逐项权威清单见 API 入口。

这不是完整的涂鸦小程序运行时：没有 App/Page/setData、JSSDK、涂鸦账号、产品云身份或通用云 DP 日志。仅新增命名空间，不代表原 DOWT 包可直接运行，也没有新增浇花器硬件协议。现有 window.rti 签名、DP 名称、物理单位和 Base64 形态保持不变。

调用形态

同步接口直接返回快照或结果。一般异步方法接受 {...参数, success?, fail?, complete?}：成功只调用 success，失败只调用 fail，之后调用 complete，各一次。传入任何回调时返回 undefined；无回调时返回 Promise，失败会 reject。这样兼容 DOWT 的回调封装，以及 connectBLEDevice/getAnalyticsLogsStatusLog 的 Promise 用法。调用者必须处理 Promise 拒绝。

panel.initPanelKit 与 createWebviewContext 是例外：它们同步返回 NOT_PLANNED 对象。前者还支持 fail/complete 回调，避免原壳的无等待初始化调用留下未处理拒绝。不会提供假的 context.postMessage。

事件注册接受函数并返回 () => void，同时提供涂鸦的 offXxx 注销：offXxx(callback) 移除该回调的全部注册，offXxx() 移除本事件的全部回调。不自动回放。初始值通过对应查询获取。跨页面消息订阅随页面销毁清理；原生断连、状态通知不会扩展到其他设备。

统一失败

{
  success: false,
  errorCode: "NOT_PLANNED",
  errorMsg: "This API is intentionally not implemented in HeimLink.",
  innerError: {
    errorCode: "NOT_PLANNED",
    errorMsg: "This API is intentionally not implemented in HeimLink."
  },
  api: "ty.getUserInfo",
  errMsg: "ty.getUserInfo:fail This API is intentionally not implemented in HeimLink."
}

字段与涂鸦失败对象对齐：errorCode、errorMsg、innerError。涂鸦用 innerError 放插件外部依赖的错误；HeimLink 没有这一层，innerError 与外层相同。errorCode 是 HeimLink 字符串错误码，不是涂鸦的数字错误码（如 20028）：涂鸦没有公开完整的错误码对照，HeimLink 不做换算，按涂鸦数字码分支的代码需要改成按下列字符串码处理。

NOT_PLANNED 表示明确不实现这项涂鸦平台能力。NOT_SUPPORTED 表示有业务意义但当前版本、驱动、参数或平台不支持，不能混同。网络、断连、权限、超时等故障使用各自错误码，不会归入“不计划实现”。通用失败还包括 BAD_REQUEST、DEVICE_SCOPE_VIOLATION、UNAUTHORIZED、NOT_CONNECTED、NOT_PAIRED、TIMEOUT、NETWORK_ERROR、PERMISSION_DENIED、CANCELLED、STORAGE_NOT_FOUND、DP 错误及 INTERNAL。

设备与状态

只接受 getLaunchOptionsSync().query.deviceId 提供的本地句柄。没有跨设备枚举、扫描或任意 GATT 权限。设备字段缺失时不伪造：不能把手机时区当设备时区、添加时间当激活时间、认证产品 hash 当涂鸦 productId。

数字 DP ID/code、类型、范围和读写权限来自本次启动为当前已识别产品选定的契约，不套用浇花器或其他同品类产品的 DP 表。ShimLink 产品的这部分取自协议 05 章第 4 节 的共用 dataPoint 表，所有 ShimLink 产品相同；温度类 DP 的 scale 为 0.1，例如 setpoint 21.5 摄氏度为 215。schema.type === "raw" 保留 DOWT 启动过滤 RAW 查询的逻辑；RAW 值用偶数长度 hex。数值 DP 遵守涂鸦十进制 scale，例如 setpoint 21.5 摄氏度在 scale=2 时为 2150。不存在的 ID 失败；相同编号即使在同品类也可能有不同含义，必须使用产品匹配的控制 App。

getDeviceInfo 的顶层 productId 和 heimlink.productId 返回 HeimLink 产品字符串，例如 50d8cf，不是涂鸦云 PID，也不是认证 hash。heimlink.contractRevision 是正整数修订号，heimlink.contractDigest 是 64 位小写十六进制 SHA-256 摘要；它们标识本次 App 构建锁定的契约，不表示在线协商结果。无法可靠确定产品时返回 NOT_SUPPORTED，不按品类猜测。

例如 50d8cf 的 DP4 为 childLock/BOOLEAN，b6wrhc 的 DP4 为 heating/BOOLEAN。schema、DP 查询、写入和通知均按产品解释。离线缓存仅在产品及契约来源匹配时返回，否则为空；不会因此删除配对密钥或用户信息。

getDeviceInfo 的 heimlink.stateSource 区分 authenticated-live 与 last-known。dpsTime 不编造单 DP 时间。BLE 物理在线与完成安全配对是两个状态。publishCommands 复用设备驱动本身的写语义，不给 TRV901Z 的逐项 ACK 增加虚假的原子性保证。

同步快照与存储

同步 launch/system/storage 数据在页面业务脚本之前可用。返回拷贝，不允许页面修改快照对象来改宿主身份。系统变化更新镜像；原生 get/set/removeStorage 完成前刷新当前页镜像，并通知同范围其他页面。刚发起但未完成的异步写入，不保证立即可由 getStorageSync 看到。

数据按应用和本地设备记录隔离，跨页面/重启持久化，不访问宿主账号、密钥或任意 MMKV key。存储内容与种子中的文本安全转义，不能通过 </script> 或替换字符串元字符插入脚本。

网络与 DOWT 启动

当前 DOWT 中 getUserInfo 是非阻塞资料读取，失败仅记录日志；不是服务探测。getAppInfo.regionCode 用于服务选区，HeimLink 不伪造该字段，调用方采用缺失区域的回退路径。

真正的连通性检查是 ty.request 访问 RTI /v1/version，并检查状态码以及 service/version 字段。本层返回真实 HTTP 响应，不替调用者判断健康、不自动附加宿主秘密。HTTP 401/503 不等于传输失败，更不等于服务健康。产品服务所需的真实认证和产品上下文仍由业务层解决。

支持边界

• NOT_PLANNED：getUserInfo、getAnalyticsLogsStatusLog、panel.initPanelKit、createWebviewContext；非定位的涂鸦权限 scope 也返回此结果。
• NOT_SUPPORTED：当前 map.chooseLocation 和 device.getOTAUpdateInfo。前者不冒充 GPS 取点；后者不返回“无更新”，但可打开原生 OTA 页实际检查。
• 位置和触感依赖原生模块；旧二进制缺少模块时返回 NOT_SUPPORTED，必须重建 App。只请求前台定位，不请求后台位置。
• 纯浏览器中没有原生宿主时，ty 不复用 rti 的离线模拟设备来制造成功。

默认异步 RPC 超时 15 秒；BLE 连接 20 秒；定位/授权 62 秒；HTTP 使用自身 1..60000ms 超时加 2 秒交付预算。Promise 超时不会撤销已经提交到硬件的写入；查询/命令并非事务取消接口。

以下 38 项起始于 HeimLink ty compatibility v1（2026-09-13），标注“2026-09-29 新增”的 6 项是它们在涂鸦中的配对接口；稳定性均为会调整。方法存在不等于具备全部涂鸦能力。通用语义与支持边界见 通用约定。

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

读取当前设备页面的启动上下文。

请求字段

无参数。

返回字段

{query: {deviceId, ...页面查询参数}, path}；deviceId 是本地不透明句柄，不是涂鸦云设备 ID 或蓝牙地址。

错误与限制

无原生上下文时 NOT_SUPPORTED。

超时

同步，无 RPC 超时。

示例

const launch = ty.getLaunchOptionsSync();

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：NOT_PLANNED。

继承 ty 通用约定、安全模型 和 数据类型。

功能

明确拒绝初始化涂鸦 PanelKit。HeimLink 已拥有设备会话及配对界面。

请求字段

原调用的配置对象可以传入，但不会启动 PanelKit，也不会改变配对、离线遮罩或 OTA 策略。

返回字段

同步返回统一失败对象；传入 fail/complete 时异步调用它们，不调用 success。

错误与限制

NOT_PLANNED；不返回被忽略后产生未处理拒绝的 Promise。

超时

同步，无 RPC 超时。

示例

const result = ty.panel.initPanelKit({ deviceId });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

读取真实手机系统与安全区快照。

请求字段

无参数。

返回字段

platform, system, language, timezoneId, theme, pixelRatio, screenWidth, screenHeight, windowWidth, windowHeight, statusBarHeight, safeArea。safeArea 含 top/right/bottom/left/width/height，单位为逻辑像素；是屏幕坐标矩形，不是 rti.insets。heimlink.uses24HourClock 为扩展字段。不伪造品牌、型号或涂鸦 SDK 版本。

错误与限制

无原生上下文时 NOT_SUPPORTED。

超时

同步，无 RPC 超时。

示例

const info = ty.getSystemInfoSync();

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

读取 HeimLink 宿主名称和版本，不伪造涂鸦账号服务区。

请求字段

仅通用回调参数。

返回字段

{appName, version, heimlink:{runtime:"heimlink", regionSource:"unavailable"}}。有实际配置才返回版本；不包含 regionCode。DOWT 会走缺少服务区时的回退，并通过真实 HTTP 探测服务。

错误与限制

通用错误。

超时

SDK 15 秒。

示例

const info = await ty.getAppInfo();

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：NOT_PLANNED。

继承 ty 通用约定、安全模型 和 数据类型。

功能

HeimLink 不实现涂鸦账号资料。

请求字段

仅通用回调参数。

返回字段

失败对象，不返回假用户，不调用成功回调。当前 DOWT 的此调用是非阻塞资料读取，不是服务连通性门禁。

错误与限制

NOT_PLANNED。

超时

SDK 15 秒。

示例

ty.getUserInfo({ fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（有限字段）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

读取当前绑定设备元数据、契约 schema 和状态。

请求字段

deviceId?；省略时使用当前会话。传入时必须是启动上下文的句柄。

返回字段

devId, deviceId, name, productId, schema, dps, dpCodes, dpsTime:{}, isOnline, deviceOnline, isCloudOnline:false, isLocalOnline:false, isShare:false, capability:1024。schema 使用当前已识别产品锁定契约的编号/code、权限及类型，ShimLink 产品的这部分来自协议共用 dataPoint 表（见 README）；RAW 为 hex，数值按 schema.scale 编码。同品类其他产品的 DP 表不能复用。

productId 为 HeimLink 产品字符串，不是涂鸦云 PID 或 hash。heimlink 包含 category, productId, contractRevision, contractDigest, transport, stateSource, unavailableFields；修订号是正整数，摘要是 64 位小写十六进制 SHA-256，表示当前 App 构建的契约 pin，不是设备在线协商的版本。

activeTime, devTimezoneId, latitude, longitude 缺失时不伪造；不把本地添加时间称为激活/配对时间。离线业务缓存只有在产品与契约来源匹配时返回，否则为空；绑定和用户信息不因此删除。

错误与限制

产品未知、身份冲突或缺少产品契约为 NOT_SUPPORTED，不按品类回退；设备已删除为 BAD_REQUEST；跨设备为 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

const info = await ty.device.getDeviceInfo({ deviceId });

起始版本：registerDeviceListListener 为 HeimLink ty compatibility v1（2026-09-13），unregisterDeviceListListener 于 2026-09-29 新增。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

确认设备事件订阅范围；不创建第二条 BLE 监听。unregisterDeviceListListener 是涂鸦对应的注销入口，参数与校验相同。设备事件本来就只来自本会话设备，注销不会停止事件，停止接收请用对应的 offXxx 或退订函数。

请求字段

deviceIdList: [deviceId]，只接受当前设备一个句柄。

返回字段

{}。事件监听器可在此前或此后注册，均仅接收本会话设备。

错误与限制

空列表、其他设备或多个设备为 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

await ty.device.registerDeviceListListener({ deviceIdList: [deviceId] });
// 页面卸载时：
await ty.device.unregisterDeviceListListener({ deviceIdList: [deviceId] });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

订阅本会话设备的已认证 DP 变化以及 queryDps 的查询结果。

订阅签名

ty.device.onDpDataChange(callback) 返回退订函数；ty.device.offDpDataChange(callback) 按涂鸦约定注销，移除该回调的全部注册，不传参数时移除本事件的全部回调。两种写法可以混用。

事件字段

{deviceId, devId, dps, dpsMapCode}；dps 为数字 ID 字符串键的部分映射，RAW 为 hex，数值遵守 schema.scale。dpsMapCode 与 dps 是同一批数据，键换成 DP code（即 getDeviceInfo 中 schema 的 code，也是 dpCodes 的值），取值与 dps 相同。HeimLink 的 DP code 是产品契约中的数据点名称（如 setpoint），不是涂鸦云产品上定义的 code。不自动回放初始状态；queryDps 可报告与已有值相同的数据。

错误与限制

无监听回放；不能把事件到达时间当作设备执行时间。

超时

订阅无 RPC 超时；调用退订函数、off 方法或卸载页面时清理。

示例

const onChange = event => update(event.dpsMapCode);
ty.device.onDpDataChange(onChange);
// 页面卸载时：
ty.device.offDpDataChange(onChange);

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（BLE）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

通过当前认证设备会话下发控制指令。ty.device.publishDps 参数与写入行为相同，只是成功值不同。

请求字段

deviceId?, dps；mode 省略或 2；options 省略或空对象；pipelines 省略或包含 3（BLE）的数组。

返回字段

成功 {}，不返回乐观状态。数字 ID 映射至实际设备契约，RAW hex 转为现有 rti Base64；数值从缩放整数转为物理单位。HeimLink 会话保留原子 SET_STATE；TRV901Z 驱动为逐字段 ACK，可能部分提交，不提升其原子性。

错误与限制

DP_UNKNOWN, DP_READ_ONLY, DP_TYPE_MISMATCH, DP_VALUE_INVALID, NOT_CONNECTED, NOT_PAIRED；非 BLE 选择或扩展选项为 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

await ty.device.publishCommands({ deviceId, dps: { 1: "heat" }, mode: 2, pipelines: [3] });

起始版本：HeimLink ty compatibility v1，2026-09-29 新增。稳定性：会调整。状态：已实现（BLE）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

通过当前认证设备会话下发 DP。与 ty.device.publishCommands 走同一条写入路径，请求字段、DP 换算、校验和错误完全相同。

请求字段

deviceId?, dps；mode 省略或 2；options 省略或空对象；pipelines 省略或包含 3（BLE）的数组。

返回字段

成功为 true，与涂鸦 publishDps 相同。

涂鸦的成功只表示指令已发出；HeimLink 在设备确认写入后才成功。设备状态以 ty.device.onDpDataChange 为准。超时失败时设备可能已经执行了该指令。

错误与限制

同 ty.device.publishCommands。

超时

SDK 15 秒。

示例

ty.device.publishDps({
  deviceId,
  dps: { 2: 215 },
  mode: 2,
  pipelines: [3],
  options: {},
  success: () => {},
  fail: err => showError(err.errorMsg),
});

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（支持主动读取的驱动）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

主动读取指定 DP，并通过事件交付结果。

请求字段

deviceId?, dpIds: number[] 非空；queryType 省略或 0。

返回字段

成功 {} 不含 DP；值通过 onDpDataChange 返回。当前 HeimLink 驱动读取完整状态后筛选指定编号。TRV901Z 没有通用读取命令：每个连接第一次读取时主动取日程与阀门校准状态，其余 DP 只报告最近一次上报的值，不能当成主动查询。事件可能先于成功回调，需先订阅。

错误与限制

TRV901Z 或未返回全部指定 DP 为 NOT_SUPPORTED；未知 ID 为 DP_UNKNOWN。

超时

SDK 15 秒。

示例

await ty.device.queryDps({ deviceId, dpIds: [1, 2] });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

查询当前设备真实 BLE 物理连接状态。

请求字段

deviceId?。

返回字段

{isOnline:boolean}。其他设备的连接不会使当前设备在线；物理在线不代表已认证或控制命令一定可用。

错误与限制

通用设备范围错误。

超时

SDK 15 秒。

示例

const state = await ty.device.getBLEOnlineState({ deviceId });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

定向连接本页面绑定设备并发现服务。

请求字段

deviceId?。

返回字段

{isOnline:boolean}。保留无回调时返回 Promise 的调用方式。连接成功不等于安全配对完成。

错误与限制

连接和权限失败如实返回，不能当作 NOT_PLANNED。

超时

SDK 20 秒。

示例

await ty.device.connectBLEDevice({ deviceId });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（BLE）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

订阅本设备 BLE 在线状态变化。

订阅签名

ty.device.onDeviceOnlineStatusUpdate(callback) 返回退订函数；ty.device.offDeviceOnlineStatusUpdate(callback) 按涂鸦约定注销，移除该回调的全部注册，不传参数时移除本事件的全部回调。两种写法可以混用。

事件字段

{deviceId, devId, online:boolean, heimlink:{transport:"ble"}}。不伪造涂鸦云在线、网关或 onlineType 枚举。不初始回放；用 getBLEOnlineState 查询当前值。

错误与限制

只报告当前设备的变化。

超时

订阅无 RPC 超时；调用退订函数、off 方法或卸载页面时清理。

示例

const off = ty.device.onDeviceOnlineStatusUpdate(event => updateOnline(event.online));

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

订阅当前已保存设备被移除。

订阅签名

ty.device.onDeviceRemoved(callback) 返回退订函数；ty.device.offDeviceRemoved(callback) 按涂鸦约定注销，移除该回调的全部注册，不传参数时移除本事件的全部回调。两种写法可以混用。

事件字段

{deviceId, devId}，均为本地句柄。事件不是删除命令；收到后原生设备页面将退出。

错误与限制

不返回原始蓝牙 locator。

超时

订阅无 RPC 超时；调用退订函数、off 方法或卸载页面时清理。

示例

const off = ty.device.onDeviceRemoved(event => handleRemoved(event));

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：NOT_PLANNED。

继承 ty 通用约定、安全模型 和 数据类型。

功能

明确拒绝涂鸦云端 DP 分析日志查询。

请求字段

可传原涂鸦查询对象；deviceId 若传入仍检查范围。

返回字段

失败对象，不返回空数组伪装“没有日志”。HeimLink 温控历史模型并不等价于 DOWT 浇水/流量/故障日志。

错误与限制

NOT_PLANNED。未来本地通用设备日志需独立定义，不代表日志能力整体永远不做。

超时

SDK 15 秒。

示例

try { await ty.getAnalyticsLogsStatusLog({ deviceId, dpIds: "1" }); } catch (error) { handleFailure(error); }

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

同步读取本应用、本设备的持久化数据镜像。

请求字段

字符串 key，不是 {key}。

返回字段

直接返回 JSON 值的拷贝，不包 {data}；缺失返回空字符串。0、false、null 不当作缺失。镜像在页面加载及原生提交事件后刷新。

错误与限制

空 key 或非字符串为 BAD_REQUEST；它不阻塞等待尚未完成的 setStorage。

超时

同步，无 RPC 超时。

示例

const theme = ty.getStorageSync("theme");

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

读取本应用、本设备的持久化存储。

请求字段

key：非空字符串，最多 256 字符。

返回字段

{data: JSON值}；读取时也刷新同步镜像。

错误与限制

缺失为 STORAGE_NOT_FOUND，不是成功的空值。

超时

SDK 15 秒。

示例

const result = await ty.getStorage({ key: "theme" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

写入本应用、本设备的持久化存储。

请求字段

key：1..256 字符；data：JSON 值，不接受 undefined。

返回字段

{}；提交成功并更新镜像后才成功。不同应用/设备隔离，同范围多个页面同步。每范围总 JSON 序列化内容上限 1 Mi 字符。

错误与限制

参数或配额错误为 BAD_REQUEST。

超时

SDK 15 秒。

示例

await ty.setStorage({ key: "theme", data: "dark" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

移除本应用、本设备存储项。

请求字段

key：1..256 字符。

返回字段

{}；缺失也成功，完成前更新同步镜像。不允许操作宿主其他存储区域。

错误与限制

通用错误。

超时

SDK 15 秒。

示例

await ty.removeStorage({ key: "theme" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（文本 HTTP）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

通过原生网络栈发起真实业务 HTTP 请求，包括 RTI /v1/version 探测。

请求字段

url 绝对 HTTPS URL；method 默认 GET，可为 GET/HEAD/POST/PUT/PATCH/DELETE/OPTIONS；header（兼容 headers）；data；timeout 1..60000ms；responseType 仅 text。

返回字段

{statusCode, data:string, header}。HTTP 4xx/5xx 仍是成功收到 HTTP 响应，调用者检查状态码和内容；不会伪造 service/version。GET/HEAD 对象编码为查询参数，POST 等对象默认 JSON，表单 content-type 时使用表单编码。请求体和响应体各限制 1 Mi 字符。

错误与限制

非法 URL/参数为 BAD_REQUEST；传输失败 NETWORK_ERROR；超时 TIMEOUT；页面关闭 CANCELLED。生产只允许 HTTPS，开发/preview 允许 HTTP；不允许 URL 内嵌凭据。不提供 RequestTask/abort、二进制或上传/下载接口。

超时

宿主默认 60 秒；SDK 多留 2 秒交付失败结果。

示例

ty.request({ url: "https://example.com/v1/version", success: inspectResponse, fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（定位）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

查询系统定位授权，不弹出授权框。

请求字段

scope.userLocation；Android 额外支持 scope.userPreciseLocation。

返回字段

{authorized, granted?, denied, canAskAgain}；权限尚未询问时省略 granted，不返回 granted:false，避免 DOWT 将其误判为明确拒绝并跳过授权。授权存在不等于定位服务开启或能取得位置。

错误与限制

其他涂鸦 scope 为 NOT_PLANNED；iOS 精确授权 scope 为 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

const state = await ty.authorizeStatus({ scope: "scope.userLocation" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（定位）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

请求前台定位授权。

请求字段

scope.userLocation；Android 额外支持 scope.userPreciseLocation。

返回字段

授权成功返回 {authorized, granted, denied, canAskAgain}；用户拒绝进入失败通道。不会请求后台定位。

错误与限制

PERMISSION_DENIED；其他 scope 为 NOT_PLANNED；iOS 精确授权 scope 为 NOT_SUPPORTED。

超时

SDK 62 秒（含授权交互）；位置采集本身最多 30 秒。

示例

ty.authorize({ scope: "scope.userLocation", success: onAuthorized, fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（WGS84）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

获取实际手机位置，不伪造设备安装位置。

请求字段

type 省略或 "wgs84"。

返回字段

{latitude, longitude, accuracy, altitude, speed, type:"wgs84"}；坐标为数值，精度/海拔/速度可为 null。前台授权后获取一次位置，定位采集最多 30 秒，完成/超时/页面关闭清理监听。

错误与限制

PERMISSION_DENIED, TIMEOUT, CANCELLED；非 WGS84 为 NOT_SUPPORTED。系统授权框由 OS 管理，页面关闭不能撤销已经显示的授权框。

超时

SDK 62 秒（含授权交互）；位置采集本身最多 30 秒。

示例

const position = await ty.map.getLocation({ type: "wgs84" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：NOT_SUPPORTED。

继承 ty 通用约定、安全模型 和 数据类型。

功能

地图选点具有业务意义，但当前 HeimLink 尚无原生地图选点界面。

请求字段

接受原调用配置，但目前不执行选点。

返回字段

明确失败，不用当前 GPS 坐标冒充用户选点，也不打开一个无法回传结果的外部地图后声称成功。

错误与限制

NOT_SUPPORTED，不是 NOT_PLANNED。

超时

SDK 15 秒。

示例

ty.map.chooseLocation({ fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（平台限制）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

打开手机系统设置。

请求字段

Android scope：Settings（默认）、Settings-Bluetooth、Settings-WiFi、Settings-Location。

返回字段

成功 {}；Android 打开对应系统设置页；iOS 受平台限制只打开当前 App 的设置页，不使用私有设置 URL。

错误与限制

未支持的 Android 目标为 NOT_SUPPORTED；系统打开失败如实返回。

超时

SDK 15 秒。

示例

await ty.openSystemSettingPage({ scope: "Settings-Location" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

打开 HeimLink 自身的系统权限设置页。

请求字段

可传原 scope；当前各 App 设置 scope 均落在同一个 App 设置入口，不承诺直达某个开关。

返回字段

{} 表示已请求打开设置页，不表示权限已变更。

错误与限制

系统打开失败如实返回。

超时

SDK 15 秒。

示例

await ty.openAppSystemSettingPage({ scope: "App-Settings" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现（已注册页面）。

继承 ty 通用约定、安全模型 和 数据类型。

功能

在当前设备的 Web App 页面栈中打开声明的路由。

请求字段

url：manifest 中的 route 名或对应文件路径，可附查询参数。

返回字段

{}；查询参数在目标页的 getLaunchOptionsSync().query 中返回。这里只支持 HeimLink 注册的页面，不提供涂鸦 Page/setData 或 webview:// 路由壳。

错误与限制

未知路由、外部 URL、父级跳转为 BAD_REQUEST；尝试覆盖 id/deviceId/route/tyParams 为 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

await ty.navigateTo({ url: "/settings?section=general" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

返回当前设备页面栈中的前若干页。

请求字段

delta 默认为 1，必须为 1..100 整数且不超过当前设备栈深度。

返回字段

{}。不会把返回一页当成退出整个设备页面；根页应使用 exitMiniProgram。

错误与限制

超过栈深度或非法 delta 为 BAD_REQUEST。

超时

SDK 15 秒。

示例

await ty.navigateBack({ delta: 1 });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

退出整个设备控制页面栈，回到宿主上一级。

请求字段

仅通用回调参数。

返回字段

{} 表示发起离开设备控制流程，不退出手机 App、不删除设备、不主动解绑。

错误与限制

不存在可返回的父设备页面时 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

ty.exitMiniProgram({ fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

修改当前设备在 HeimLink 中的本地名称。

请求字段

deviceId?, name：去除首尾空白后非空，原始长度最多 100 字符。

返回字段

{}，使用既有设备持久化流程；不改广播名、云端名或出水口别名。

错误与限制

空白名称 BAD_REQUEST；跨设备 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

await ty.device.renameDeviceName({ deviceId, name: "Garden timer" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：NOT_SUPPORTED。

继承 ty 通用约定、安全模型 和 数据类型。

功能

OTA 查询有业务意义，但当前尚无等价的模块状态/可升级性查询。

请求字段

deviceId?。

返回字段

明确失败；不返回 [] 或 upgradeStatus:0 冒充“没有更新”。可用 openOTAUpgrade 进入原生页面进行实际检查。

错误与限制

NOT_SUPPORTED，不是 NOT_PLANNED。

超时

SDK 15 秒。

示例

ty.device.getOTAUpdateInfo({ deviceId, fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

打开当前设备的原生固件升级页面。

请求字段

deviceId?。

返回字段

{} 表示打开页面，不表示升级开始或成功；仍由原生页校验固件、设备家族、权限和版本。

错误与限制

通用设备范围/导航错误；不允许页面提供任意固件 URL 绕过校验。

超时

SDK 15 秒。

示例

await ty.device.openOTAUpgrade({ deviceId });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

打开当前设备的 HeimLink 原生设置页。

请求字段

deviceId?。

返回字段

{}；不承诺提供涂鸦分享、账号或云自动化入口。

错误与限制

通用设备范围/导航错误。

超时

SDK 15 秒。

示例

await ty.device.openDeviceDetailPage({ deviceId });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

显示宿主原生消息提示。

请求字段

title：1..500 字符；duration 默认 1500ms，范围 1..10000；icon 的 success/error 映射提示类型，其余为普通提示。

返回字段

{} 表示提示已提交，不等待消失；不承诺涂鸦精确视觉样式、图片或遮罩。

错误与限制

参数错误 BAD_REQUEST。

超时

SDK 15 秒。

示例

ty.showToast({ title: "Saved", icon: "success" });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

将文本写入系统剪贴板。

请求字段

data 字符串，最多 1 Mi 字符，可为空。

返回字段

{}；不提供读取剪贴板能力。

错误与限制

参数错误 BAD_REQUEST；系统失败如实返回。

超时

SDK 15 秒。

示例

await ty.setClipboardData({ data: deviceId });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

请求系统短触感反馈。

请求字段

type 为 light（默认）、medium、heavy。

返回字段

{}；设备硬件、系统触感设置及低电量策略可能使其无可感知反馈，不保证物理振动。

错误与限制

非法 type 为 BAD_REQUEST；原生模块缺失为 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

ty.vibrateShort({ type: "light", fail: handleFailure });

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：已实现。

继承 ty 通用约定、安全模型 和 数据类型。

功能

订阅系统键盘显示/隐藏高度变化。

订阅签名

ty.onKeyboardHeightChange(callback) 返回退订函数；ty.offKeyboardHeightChange(callback) 按涂鸦约定注销，移除该回调的全部注册，不传参数时移除本事件的全部回调。两种写法可以混用。

事件字段

{height:number}，逻辑像素；隐藏时为 0。来源为原生 keyboardDidShow/keyboardDidHide，不是安全区 inset；不提供逐帧动画或 willShow/willHide。

错误与限制

遵循平台键盘事件可用性，不初始回放。

超时

订阅无 RPC 超时；调用退订函数、off 方法或卸载页面时清理。

示例

const off = ty.onKeyboardHeightChange(event => setHeight(event.height));

起始版本：HeimLink ty compatibility v1（2026-09-13）。稳定性：会调整。状态：NOT_PLANNED。

继承 ty 通用约定、安全模型 和 数据类型。

功能

不提供涂鸦原生 Page 逻辑层对子 WebView 的上下文对象。

请求字段

原调用的 WebView 标识可传入。

返回字段

同步返回统一失败对象，不含 postMessage。当前页面使用 window.ty/window.rti 调用宿主；不得把 window.postMessage 回环当作跨层通信。

错误与限制

NOT_PLANNED。完整 App/Page/JSSDK 和嵌套 WebView 壳不在此兼容层内。

超时

同步，无 RPC 超时。

示例

const context = ty.createWebviewContext("webview-container");