dataman

数据订阅模块，绑定设备数据源到 LVGL 对象。

`dataman.subscribe(key, obj, callback)`

local token = dataman.subscribe("timeHour", labelObj, function(obj, value)
    local hour = value // 256
    obj:set { text = tostring(hour) }
end)

参数	类型	说明
`key`	`string`	数据源键名
`obj`	`userdata`	绑定的 LVGL 对象，回调中作为第一参数传回
`callback`	`function(obj, value)`	数据更新回调

value 经过 256 倍编码，使用前必须 value // 256。值为 2147483647（INT_MAX）表示数据无效。

`dataman.pause(token)` / `dataman.resume(token)`

dataman.pause(token)
dataman.resume(token)

参数	类型	说明
`token`	`any`	`subscribe` 的返回值

已知键名

键名	说明	值范围
`timeHour`	小时	0–23
`timeMinute`	分钟	0–59
`timeSecond`	秒	0–59
`dateDay`	日期	未知
`dateMonth`	月份	未知
`dateWeek`	星期	未知
`systemStatusBattery`	电池电量	未知
`timeHourHigh`	高位小时	未知
`timeHourLow`	低位小时	未知
`timeMinuteHigh`	高位分钟	未知
`timeMinuteLow`	低位分钟	未知
`timeSecondHigh`	低位秒	未知
`timeSecondLow`	低位秒	未知
`timeCentiSecond`	厘秒	未知
`healthPressureIndex`	压力指数	0–100
`systemSensorFusionAltitude`	海拔（米）	整数，INT_MAX 无效
`weatherCurrentSunRiseHour`	日出时	0–23，INT_MAX 无效
`weatherCurrentSunRiseMinute`	日出分	0–59，INT_MAX 无效
`weatherCurrentSunSetHour`	日落时	0–23，INT_MAX 无效
`weatherCurrentSunSetMinute`	日落分	0–59，INT_MAX 无效
`batteryLevel`	AOD/表盘绑定（观察到）	未知
`calorie`	AOD/表盘绑定（观察到）	未知
`heartRate`	AOD/表盘绑定（观察到）	未知
`healthHeartRate`	心率	未知
`healthStepCount`	步数	未知
`step`	AOD/表盘绑定（观察到）	未知
`weatherCondition`	AOD/表盘绑定（观察到）	未知

标记为“观察到”的键来自设备表盘/AOD 资源绑定，尚未通过 dataman.subscribe 验证。键名规则为驼峰式：healthXxx、weatherXxx、timeXxx、systemXxx。

社区补充（洛汐文档库）

以下内容来自洛汐文档库《dataman 数据订阅》：https://docs.luoxe.cn/docs/vela/lua/dataman/

dataman 把表盘数据源绑定到一个 LVGL 对象。数据变化时，宿主把对象和值传给回调。subscribe(key, object, callback) 三个参数均为必填，回调签名为 function(object, value)。

local token = dataman.subscribe("timeHour", label, function(obj, value)
  local hour = value // 256
  obj:set { text = string.format("%02d", hour) }
end)

Q24.8 定点数值解码

大多数数值采用 Q24.8 定点格式，即真实值乘以 256。使用整数除法 value // 256 解码。无效值通常为该运行环境的整数最大值（如 2147483647）；使用数据前应按数据源定义判断。

pause / resume 语义

pause 暂停派发但保留订阅；resume 恢复。建议页面隐藏时暂停，显示时恢复。

时间与日期数据源（补充键名）

数据源	含义
`timeHourLow` / `timeHourHigh`	小时低位/高位
`timeMinuteLow` / `timeMinuteHigh`	分钟低位/高位
`timeSecondLow` / `timeSecondHigh`	秒低位/高位
`timeCentiSecond`	厘秒
`timeCentiSecondLow` / `timeCentiSecondHigh`	厘秒低位/高位
`dateYear`	年
`dateYearDigit1..4`	年的各位数字
`dateMonth` / `dateMonthLow` / `dateMonthHigh`	月及拆分位
`dateDay` / `dateDayLow` / `dateDayHigh`	日及拆分位
`dateWeek`	星期
`dateLunarYear` / `dateLunarMonth` / `dateLunarDay`	农历年月日
`dateWeekStringShortCN` / `dateWeekStringFullCN`	中文星期文本
`dateWeekStringFullPascalEN` / `FullUpperEN` / `FullLowerEN`	英文完整星期文本
`dateWeekStringShortPascalEN` / `ShortUpperEN` / `ShortLowerEN`	英文短星期文本
`dateMonthStringShortCN`	中文月份文本
`dateMonthStringFullPascalEN` / `FullUpperEN` / `FullLowerEN`	英文完整月份文本
`dateMonthStringShortPascalEN` / `ShortUpperEN` / `ShortLowerEN`	英文短月份文本
`miscIsPM`	是否下午
`miscIs24H`	是否 24 小时制
`miscTimeSection`	时间段
`miscdateYestarday` / `miscdateTomorrow`	昨日/明日标识；拼写以接口为准
`dualtimeHour` / `dualtimeMinute` / `dualtimeSecond`	第二时区时间
`dualtimeHour12H` / `dualtimeHour24H`	第二时区小时格式
`dualtimeCity`	第二时区城市

部分环境还提供 timeHour、timeMinute、timeSecond 组合值。

健康数据源（补充键名）

分类	数据源
步数	`healthStepCount`、`healthStepCountDigit1..5`、`healthStepProgress`、`healthStepKiloMeter`、`healthStepTarget`
心率	`healthHeartRate`、`healthHeartRateZone`、`healthHeartRateMin`、`healthHeartRateMax`
热量	`healthCalorie`、`healthCalorieValue`、`healthCalorieProgress`、`healthCalorieTarget`
站立	`healthStandCount`、`healthStandProgress`、`healthStandTarget`
血氧/压力	`healthOxygenSpO2`、`healthPressureIndex`
血压	`healthBloodDiastolicPressureMmhg`、`healthBloodSystolicPressureMmhg`、`healthBloodDiastolicPressureKpa`、`healthBloodSystolicPressureKpa`、`healthBloodPressureUnit`
睡眠	`healthSleepDuration`、`healthSleepDurationMinute`、`healthSleepScore`、`healthSleepQuality`、`healthSleepTargetProgress`
运动	`healthExerciseDuration`、`healthExerciseProgress`、`healthExerciseTarget`、`healthEnergyConsumed`
其他	`healthMiscRecoveryTime`、`healthMiscRunPowerIndex`、`healthMiscTodayVitalityValue`、`healthMiscSevenDaysVitalityValue`
血糖	`healthBloodSugarValue`、`healthBloodSugarUpdateTsString`

天气数据源（补充键名）

分类	数据源
日出日落	`weatherCurrentSunRise`、`weatherCurrentSunSet`、`weatherCurrentSunRiseHour`、`weatherCurrentSunRiseMinute`、`weatherCurrentSunSetHour`、`weatherCurrentSunSetMinute`
温度	`weatherTemperatureUnit`、`weatherCurrentTemperature`、`weatherCurrentTemperatureFahrenheit`、`weatherCurrentTemperatureFeel`
当前天气	`weatherCurrentHumidity`、`weatherCurrentWeather`、`weatherCurrentWindDirection`、`weatherCurrentWindAngle`、`weatherCurrentWindSpeed`、`weatherCurrentWindLevel`
环境	`weatherCurrentAirQualityIndex`、`weatherCurrentAirQualityLevel`、`weatherCurrentChanceOfRain`、`weatherCurrentPressure`、`weatherCurrentVisibility`、`weatherCurrentUVIndex`、`weatherCurrentDressIndex`
今日	`weatherTodayTemperatureMax`、`weatherTodayTemperatureMin`、`weatherTodayTemperatureMaxFahrenheit`、`weatherTodayTemperatureMinFahrenheit`
明日	`weatherTomorrowTemperatureMax`、`weatherTomorrowTemperatureMin`、`weatherTomorrowTemperatureMaxFahrenheit`、`weatherTomorrowTemperatureMinFahrenheit`

系统与闹钟数据源（补充键名）

systemStatusBattery、systemStatusCharge、systemStatusDisturb、systemStatusBluetooth、systemStatusWifi、systemStatusScreenLock、systemSensorFusionAltitude、appAlarmHour、appAlarmMinute。

完整示例

local tokens = {}

local function bind(key, obj, render)
  tokens[#tokens + 1] = dataman.subscribe(key, obj, function(target, raw)
    render(target, raw // 256)
  end)
end

bind("systemStatusBattery", batteryLabel, function(obj, value)
  obj:set { text = string.format("%d%%", value) }
end)

function pageOnPause
  for _, token in ipairs(tokens) do dataman.pause(token) end
end

function pageOnResume
  for _, token in ipairs(tokens) do dataman.resume(token) end
end

机型可用性

机型	可用性
Xiaomi Smart Band 10 Pro	✅
Xiaomi Watch S4 41mm	✅

参考来源：官方 docs-lua / 洛汐文档库

官方文档：docs-lua 能力模块 dataman/overview.md（Vela 官方能力模块文档）
社区实战：洛汐文档库《dataman 数据订阅》https://docs.luoxe.cn/docs/vela/lua/dataman/
社区源文档：github.com/FangAiden/Vela_Application_Documentation/blob/main/docs-lua/dataman/overview.md

dataman

大纲