animengine

JSON 配置驱动的 LVGL 属性动画引擎。

`animengine.create(object, configString)`

local anim = animengine.create(targetObj, jsonConfig)
anim:start

参数	类型	说明
`object`	`userdata`	LVGL 对象
`configString`	`string`	JSON 动画配置

返回值：动画实例（userdata）

方法	说明
`anim:start`	启动动画
`anim:remove`	停止并销毁
`anim:modify(json)`	修改参数（传入新的 JSON 配置字符串）

可动画属性

以下属性已验证可用，支持同时动画多个属性（如 x + y 同时运动）：

属性	说明
`x`	水平位置
`y`	垂直位置
`rotate`	旋转角度
`opacity`	透明度
`scale`	缩放

JSON 配置格式

键	类型	说明
`fromState`	`object`	起始属性
`toState`	`object`	结束属性
`config.duration`	`number`	持续时间（秒，float）
`config.delay`	`number`	延迟时间（秒，float）
`config.easing`	`string`	缓动函数
`config.iterations`	`string`	循环次数

easing 缓动函数

值	说明
`"linear"`	线性
`"ease_in"`	缓入
`"ease_out"`	缓出
`"ease_in_out"`	缓入缓出
`"spring"`	弹性

iterations 循环次数

值	说明
`"0"`	不循环
`"1"`	播放一次
`"2"`	播放两次
`"-1"`	无限循环
`"loop"`	无限循环
`"once"`	播放一次
`"infinite"`	无限循环
(省略)	默认行为

JSON 格式注意：JSON 必须是单行或正确格式化的字符串。包含字面换行符的多行 JSON 可能导致解析错误。使用 Lua 多行字符串 [[ ]] 时需注意格式。

旋转模板

local tpl = [[
    {
        "fromState": {
            "rotate": { "value": 0, "ease": ["linear", 5.0] }
        },
        "toState": {
            "rotate": { "value": 3600, "delay": 0, "duration": %d, "ease": ["linear", 5.0] }
        },
        "config": { "ease": ["linear", 5.0], "iterations": "1" }
    }
]]
local anim = animengine.create(obj, string.format(tpl, 1000))
anim:start

多属性动画示例

local tpl = [[
    {
        "fromState": {
            "x": { "value": 0, "ease": ["ease_in_out", 5.0] },
            "y": { "value": 0, "ease": ["ease_in_out", 5.0] }
        },
        "toState": {
            "x": { "value": 100, "delay": 500, "duration": 1000, "ease": ["ease_in_out", 5.0] },
            "y": { "value": 50, "delay": 500, "duration": 1000, "ease": ["ease_in_out", 5.0] }
        },
        "config": { "ease": ["ease_in_out", 5.0], "iterations": "1" }
    }
]]
local anim = animengine.create(obj, tpl)
anim:start

缩放模板

local tpl = [[
    {
        "fromState": {
            "img_zoom": { "value": 1, "ease": ["linear", 5.0], "minVisible": 0.01 }
        },
        "toState": {
            "img_zoom": { "value": %f, "delay": %d, "duration": %d, "ease": ["linear", 5.0], "minVisible": 0.01 }
        },
        "config": { "ease": ["linear", 5.0], "delay": 3 }
    }
]]
local anim = animengine.create(img, string.format(tpl, 1.3, 0, 400))
anim:start

社区补充（洛汐文档库）

以下内容来自洛汐文档库《animengine 动画引擎》：https://docs.luoxe.cn/docs/vela/lua/animengine/

animengine 使用 JSON 字符串描述一组对象属性动画。使用前先引入模块：

local animengine = require("animengine")

简化 JSON 写法

除上文“每个属性一个状态对象”的写法外，属性也可以直接写数值，config 中直接给出 duration（浮点秒）：

{
  "fromState": {
    "rotate": 0
  },
  "toState": {
    "rotate": 3600
  },
  "config": {
    "duration": 1.0,
    "interations": "1"
  }
}

内置表盘使用过的动画属性（补充）

属性	说明
`x` / `y`	坐标
`rotate`	旋转；常见单位为 0.1 度
`opacity`	不透明度
`scale` / `img_zoom`	缩放
`start_angle` / `end_angle`	弧线角度
`custom_translate`	自定义平移
`custom_rotate`	自定义旋转

duration / delay 单位

duration 和 delay 在不同生成器中可能使用秒或毫秒。内置表盘模板以浮点秒传入；复杂状态对象也可能在单项中使用 duration、delay 和 ease（可对照上文多属性示例中的毫秒写法）。

拼写兼容：iterations / interations

部分内置表盘使用 interations，而其他资料写作 iterations。目标设备可能只识别其中一种。新脚本应先用单次短动画验证，再决定采用哪一拼写。

旋转示例（简化模板）

local template = [[
{
  "fromState": { "rotate": %d },
  "toState": { "rotate": %d },
  "config": { "duration": %f, "interations": "1" }
}
]]

local config = string.format(template, 0, 3600, 1.0)
local anim = assert(animengine.create(image, config))
anim:start

多属性示例（社区写法）

local config = [[
{
  "fromState": {
    "x": { "value": 0, "ease": ["ease_in_out", 5.0] },
    "y": { "value": 0, "ease": ["ease_in_out", 5.0] }
  },
  "toState": {
    "x": { "value": 120, "delay": 0, "duration": 1000 },
    "y": { "value": 40, "delay": 0, "duration": 1000 }
  },
  "config": { "iterations": "1" }
}
]]

local anim = animengine.create(obj, config)
anim:start

生命周期管理

local animations = {}

local function start(obj, json)
  local anim = animengine.create(obj, json)
  animations[#animations + 1] = anim
  anim:start
  return anim
end

function pageOnPause
  for _, anim in ipairs(animations) do anim:remove end
  animations = {}
end

注意点：

动画目标被删除后，animation userdata 不能继续使用。
重复 remove 或在对象销毁后调用 modify 可能报错。

机型可用性

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

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

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

animengine

大纲