洛汐文档库

外观

Lua 表盘开发总览

约 623 字大约 2 分钟

2026-07-15

Xiaomi Vela 穿戴设备提供 Lua 5.4 表盘运行环境。脚本通过 lvgl 创建界面，通过 dataman 订阅时间、健康、天气和系统数据，通过 animengine 或 LVGL 动画驱动效果。

最小模块列表

local lvgl = require("lvgl")
local dataman = require("dataman")
local topic = require("topic")
local activity = require("activity")
local animengine = require("animengine")
local navigator = require("navigator")
local vibrator = require("vibrator")
local screen = require("screen")

screen 当前返回空表；屏幕状态由宿主内部处理，不应假定存在 screen.ON、screen.OFF 等常量。

最小表盘

local lvgl = require("lvgl")
local dataman = require("dataman")

local ui = {}
local tokens = {}

function ui.init(style)
  local root = lvgl.Object(nil, {
    w = lvgl.HOR_RES(),
    h = lvgl.VER_RES(),
    bg_color = 0x000000,
    bg_opa = 255,
    border_width = 0,
    pad_all = 0,
  })

  root:clear_flag(lvgl.FLAG.SCROLLABLE)

  local label = root:Label {
    text = "--:--",
    align = lvgl.ALIGN.CENTER,
    text_color = 0xFFFFFF,
  }

  tokens[#tokens + 1] = dataman.subscribe(
    "timeHour",
    label,
    function(obj, value)
      obj:set { text = string.format("%02d", value // 256) }
    end
  )

  ui.root = root
  return root
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

return ui

表盘包通常由入口脚本、资源目录和样式资源组成。资源路径可使用绝对路径，也可由宿主注入的 SCRIPT_PATH 拼接：

local function asset(name)
  return SCRIPT_PATH .. name
end

生命周期

函数调用时机应做的工作
ui.init(style)创建表盘创建根对象、控件、订阅与动画
pageOnPause()表盘隐藏或进入编辑态暂停定时器和订阅、移除动画
pageOnResume()表盘重新显示恢复订阅、计时和必要动画

页面退出后不要继续持有 LVGL userdata。定时器、动画、topic、文件和目录句柄都应主动停止或关闭。

运行环境限制

  • Lua 版本为 5.4.0；
  • 动态库加载关闭，不能用 package.loadlib() 加载 .so；
  • io.popen() 不可用；
  • 模块与 Lua state 由表盘宿主创建，不能在快应用 RPK 中直接 require；
  • 文件读写受进程权限和挂载属性限制；
  • 运行复杂探测代码时，优先放到按钮事件或短周期定时器中，避免初始化失败导致整个表盘无法显示。

文档导航

获取源代码