Native SDK 布局 Tween 深度实战:split-collapse 示例三种折叠动画驱动方式全解析

原创2026-09-27 12:03:531,967 阅读
文章标签:开发工具跨平台桌面应用

Native SDK 布局 Tween 深度实战:split-collapse 示例三种折叠动画驱动方式全解析

<split-collapse 是 Native SDK 中一个专门用于测量"窗格折叠动画帧节奏"的最小示例应用:一个两窗格 split 布局,侧边栏在 180ms 内完成折叠与展开。它以三种方式驱动同一段动画——运行时布局 Tween(默认)、Markup 声明式 Tween、以及逐帧 Msg 手动驱动——并让每种方式把每一动画步的真实帧间隔打到 stderr 上,从而直观对比新旧两种动画习惯用语的实现成本与代码形态。读完本文,你将掌握 Native SDK 布局动画原语 CanvasWidgetLayoutTween 的完整用法、resize-duration/resize-easing 属性语义,以及如何用环境变量旋钮把同一个应用切换成三种测量形态。

示例定位:一个"诚实的"动画测量台

examples/split-collapse/README.md 将其定义为 "the smallest honest pane-collapse animation harness"。所谓"诚实",是指它不止演示动画,还让动画每一步的到达节奏(frame pacing)可被观测:每次 tween 步进都在 stderr 上打印日志,驱动方(自动化脚本或人)可以数出 180ms 折叠过程的可见步数,并读取帧与帧之间的真实时间差。

示例的参数在 examples/split-collapse/src/main.zig 顶部集中声明:

pub const canvas_label = "split-canvas";
pub const window_width: f32 = 800;
pub const window_height: f32 = 520;

pub const expanded_fraction: f32 = 0.35;
pub const collapsed_fraction: f32 = 0.06;
pub const tween_duration_ms: u32 = 180;
  • 侧边栏展开时占据 35% 的窗格宽度,折叠后仅剩 6%;
  • 动画时长固定 180ms;
  • 窗口 800×520,由 app.zon 中的 shell 配置(examples/split-collapse/app.zon)声明,GPU surface 后端为 Metal、bgra8_unorm、vsync=true。

模型本身极其精简(main.zig 中 Model 结构):一个 collapsed: bool 静止标志、一个当前渲染分数 fraction、一个可选的 tween(记录 from/to/start_ns)以及 manual_mode 开关。三种模式共享这同一个模型,区别只在于"谁把分数从 0.35 推向 0.06"。

三种驱动模式:一句话总览

README 用环境变量选择了三种驱动方式,main.zig 的 main 函数在启动时解析(main.zig):

环境变量 模式 驱动者 Zig hook
(缺省) runtime tween 运行时 layout_tweens 声明 layout_tweens
SPLIT_COLLAPSE_MARKUP=1 markup tween 视图文件 resize-duration 无(视图即动画)
SPLIT_COLLAPSE_MANUAL=1 manual ticks on_frame 返回 tick Msg on_frame + update
const mode: Mode = if (markup_mode) .markup else if (manual) .manual else .runtime;

模式选择还会影响 appOptions 中挂载哪些回调(main.zig):

.view = if (mode == .markup) CompiledSplitView.build else rootView,
.on_frame = if (mode == .manual) onFrame else null,
.layout_tweens = if (mode == .runtime) layoutTweens else null,

即:markup 模式连 Zig 的视图函数都不需要(视图完全来自 .native 文件),manual 模式独享 on_frame,runtime 模式独享 layout_tweens。三种模式并存在同一个文件里,本身就是一份并排对照的教材。

模式一:Runtime Tween(默认)—— 让运行时拥有动画

这是 README 描述的第一种、也是默认模式:"the model owns only the resting collapsed flag; the layout_tweens hook declares the split's target fraction and the runtime eases the rendered fraction toward it, one step per presented frame — no per-frame Msgs"。

模型只负责"静止真相"

切换侧边栏时,模型只翻转 collapsed 标志(main.zig):

fn applyToggle(model: *Model) void {
    model.collapsed = !model.collapsed;
    if (model.manual_mode) {
        // 只有手动模式在这里创建 tween 记录
        model.tween = .{ .from = model.fraction, .to = target };
        ...
    }
    // Runtime-driven mode changes NOTHING else: ...
}

注意这段注释强调的设计:runtime 模式中翻转标志不改变其他任何东西。折叠/展开的目标分数由 layout_tweens hook 在每次重建时从 collapsed 推导,运行时负责把渲染分数缓动过去。

layout_tweens 钩子:声明目标而不是逐帧计算

layout_tweens 是 UiApp.Options 上的一个可选回调(定义于 src/runtime/ui_app.zig),签名是"给定模型与布局树,向 out 缓冲区写入要运行的 Tween 声明并返回数量"。split-collapse 的实现(main.zig):

fn layoutTweens(model: *const Model, tree: *const Ui.Tree, out: []canvas.CanvasWidgetLayoutTween) usize {
    const split = findWidgetByKind(tree.root, .split) orelse return 0;
    out[0] = .{
        .id = split.id,
        .to = if (model.collapsed) collapsed_fraction else expanded_fraction,
        .duration_ms = tween_duration_ms,
        .easing = .standard,
    };
    return 1;
}

它在布局树中递归找到 split widget(findWidgetByKind),然后声明:目标分数 to、时长 180ms、缓动曲线 standard。这个 hook 每个呈现帧都会被运行时询问,但运行时内部做了幂等去重——startCanvasWidgetLayoutTween "is idempotent per target"(src/runtime/ui_app.zig),目标未变化时不会重新启动动画。

底层原语:CanvasWidgetLayoutTween

layout_tweens 写入的类型定义在 src/primitives/canvas/render.zig:

pub const CanvasWidgetLayoutTween = struct {
    /// Split widget id whose first-pane fraction animates.
    id: ObjectId,
    /// Target first-pane fraction (what the model now declares).
    to: f32,
    duration_ms: u32 = 180,
    easing: Easing = .standard,
    spring: SpringToken = .{},
};

其注释明确界定了这一原语的性质:v1 覆盖的是布局自有通道——split 的第一窗格分数——从当前保留值动画到 to。与"渲染动画只移动像素"不同,布局 Tween 移动布局本身,因此相邻窗格每一步都像拖拽分隔条一样重新流式排布。

运行时契约:snap、幂等与重定目标

运行时把 hook 的声明下发到 startCanvasWidgetLayoutTween(src/runtime/canvas_widget_state.zig),其契约值得细读:

  • 只作用于 split:目标 widget 的 kind 必须是 .split,否则返回 InvalidCommand;
  • reduce-motion 直接 snap:const snap = self.appearance.reduce_motion or tween.duration_ms == 0;——系统开启减少动态效果,或时长声明为 0 时,不做动画直接落到目标。这正是 README 所说 "reduced-motion appearances snap" 的实现点;
  • 目标相同即幂等返回:已武装的 tween 目标与 tween.to 一致时直接 return,不会重启动画;
  • 重定目标保留时钟:目标变化时更新 spec、把 from 设为当前渲染分数、start_ns 清零,继续用同一个 tween 对象;
  • arm 时通知一次 resize 事件:announce 为 true(hook/命令路径)时记录一次目标 resize 事件,让模型在目标处重建一次——"one with the applied fraction — never one per step"。

回放纪律:只从呈现帧时间戳采样

CanvasWidgetLayoutTween 的注释(src/primitives/canvas/render.zig)还写明了重要的回放纪律:运行时只在呈现帧时间戳(GpuSurfaceFrameEvent.timestamp_ns)上采样已武装的 tween——这与 manual 模式的 on_frame/Msg-tick 习惯用语读取的是同一个录制时钟——并且每一步都走 split 拖拽变更路径,发出与指针拖拽相同的 on_resize 事件。因此一个录制的会话无需任何新事件类型即可回放出相同的帧。进度计算由 layoutTweenProgress(src/primitives/canvas/render.zig)完成:起点由第一个前进帧盖章,时长按帧时钟的墙钟毫秒计,Easing 成员在 src/primitives/canvas/tokens.zig 定义为 linear、standard、emphasized、spring 四种。

观测 echo:tween-echo 日志

runtime 模式没有逐帧 Msg,update 收到的只有 split_resized echo——每个 tween 步进经过 split-drag 变更路径都会回写一次分数(main.zig):

.split_resized => |fraction| {
    if (model.tween != null) return; // 手动 tween 运行时忽略 echo
    if (!model.manual_mode and fraction != model.fraction) {
        std.debug.print("tween-echo fraction={d:.3}\n", .{fraction});
    }
    model.fraction = fraction;
},

于是运行时驱动期间,每一帧的到达都被打印为 tween-echo fraction=...,这正是 README 所说的测量通道:"every tween step logs its arrival cadence on stderr"。

模式二:Markup Tween —— 视图文件就是整个动画

SPLIT_COLLAPSE_MARKUP=1 展示的是同一原语的声明式形态:不写一行 Zig 动画逻辑,动画完全声明在 .native 视图文件里。README 原话:"the view file is the whole animation and no Zig hook exists"。

完整的视图文件 examples/split-collapse/src/split_collapse.native:

<column grow="1" background="background">
  <row height="48" padding="8" gap="8" cross="center">
    <button on-press="toggle" label="Toggle sidebar">{toggle_label}</button>
    <text foreground="text_muted">markup tween</text>
  </row>
  <split grow="1" value="{pane_fraction}" resize-duration="180" resize-easing="standard" on-resize="split_resized">
    <column padding="12" gap="8" background="surface">
      <text>Sidebar</text>
      <text foreground="text_muted">Inbox</text>
      <text foreground="text_muted">Drafts</text>
      <text foreground="text_muted">Archive</text>
    </column>
    <column padding="16" gap="8">
      <text size="lg">Content</text>
      <text foreground="text_muted">{content_hint}</text>
      <column grow="1" label="content-web-pane"></column>
    </column>
  </split>
</column>

关键在 <split> 这一行:

  • value="{pane_fraction}" 把 split 分数绑定到模型的 pane_fraction() 方法——它由 collapsed 标志推导出静止目标(展开 0.35 / 折叠 0.06,见 main.zig);
  • resize-duration="180" 使这个绑定的 value 成为 tween 目标:一次翻转 collapsed 的重建把声明值移动到新目标,运行时把渲染分数缓动过去,而不是立即 snap;
  • resize-easing="standard" 指定缓动曲线;
  • on-resize="split_resized" 让每一步应用后的分数 echo 回模型——与拖拽分隔条走同一条路径,所以同一个 tween-echo 日志通道照样工作。

Zig 一侧的接入极简(main.zig):

pub const markup_source = @embedFile("split_collapse.native");
pub const CompiledSplitView = canvas.CompiledMarkupView(Model, Msg, markup_source);

@embedFile 在编译期嵌入视图源码,CompiledMarkupView(定义于 src/primitives/canvas/ui_markup_compiled.zig)在编译期解析、展开绑定与消息,生成与手写 view(ui, model) 等价的代码。markup 模式下 appOptions 不再挂 on_frame 与 layout_tweens,动画完全由视图声明驱动。

resize-duration / resize-easing 属性语义

这两个属性是 Native SDK canvas 标记语言(markup schema)中 split 专用的布局 Tween 声明,schema 定义在 src/primitives/canvas/ui_schema.zig,其注释给出了权威语义:

  • resize-duration(code 71,whole 类):以毫秒为单位的整数,仅作用于 split;0(或缺省)就是今天的 snap——因此所有既有文档行为不变;非零时使 split 的 value 成为运行时向之缓动的目标,每呈现帧一步;
  • resize-easing(code 72):命名 canvas.Easing 成员之一(linear、standard、emphasized、spring),只在有非零 duration 时有意义——无 duration 的 easing 是教学错误而不是静默忽略(校验器会报错,见 src/primitives/canvas/ui_markup.zig 的错误消息);
  • 两者都被校验器限定在 split 上,用在其他地方会被判定为静默惰性(ui_markup.zig 中 resize_duration_element_message 与 resize_easing_element_message);
  • 减少动态效果(reduce-motion)在运行时内部 snap,文档无需声明任何东西。

schema 还顺带定义了相关扩展 resize-origin(code 78,src/primitives/canvas/ui_schema.zig):新挂载的 split 可以从某个进入分数滑向声明值,负值(缺省)表示无原点、保持"挂载从不动画"的既有行为。

与 Zig 声明是同一个原语:全栈测试钉住

为什么 markup 声明不需要 Zig hook?因为源码声明的 tween 与 Zig hook 声明的 tween 收敛到同一个运行时实现。startCanvasWidgetLayoutTweenForView 的注释(src/runtime/canvas_widget_state.zig)写明:split 的 SOURCE 声明 resize_duration_ms 时会武装与 Zig hook 相同的 tween,"both authoring surfaces step identical fractions on identical frame clocks";唯一差别是 announce 参数——源码声明路径不需要回显 arm 事件,因为"武装这个 tween 的源码本身就是目标声明"。

这一断言有逐位相等的测试证据。tests 目录下的全栈测试 "a markup-declared tween steps the same fractions as the Zig-declared one"(src/runtime/canvas_widget_split_tree_tests.zig)在同一个录制帧时钟上分别用 Zig 命令与 markup 声明驱动 0.5 → 0.2(180ms standard),然后断言:

for (zig_fractions, markup_fractions) |zig_fraction, markup_fraction| {
    try std.testing.expectEqual(zig_fraction, markup_fraction);
}

注释直言这是 "The full-stack pin: resize-duration/resize-easing in markup and startCanvasWidgetLayoutTween in Zig are ONE primitive"。同文件还有 clip-slide 测试(buildSlideTree,src/runtime/canvas_widget_split_tree_tests.zig):两个窗格都放满需要换行的文本,tween 在窗格内置 clip 下滑动分隔条,验证"零中途 re-wrap"的排版纪律。

模式三:Manual Ticks —— 被替代的历史习惯用语

SPLIT_COLLAPSE_MANUAL=1 展示的是布局 Tween 原语要替代的旧做法。README 描述:"on_frame returns a tick Msg carrying the presented frame's timestamp, update eases the fraction, and every tick is a full rebuild"。

实现分三步:

1. on_frame 钩子每帧产生 tick Msg(main.zig):

fn onFrame(model: *const Model, frame: native_sdk.platform.GpuFrame) ?Msg {
    if (model.tween != null) return Msg{ .frame_tick = frame.timestamp_ns };
    return null;
}

只要有 tween 在跑,每个呈现帧都会产生一个携带帧时间戳的 frame_tick Msg。

2. update 里手写缓动(main.zig):

.frame_tick => |timestamp_ns| {
    const tween = &(model.tween orelse return);
    if (tween.start_ns == 0) tween.start_ns = timestamp_ns;
    if (model.last_frame_ns != 0) {
        const dt_ns = timestamp_ns -| model.last_frame_ns;
        std.debug.print("tween-frame dt_ms={d:.1} fraction={d:.3}\n", .{...});
    }
    ...
    const t = @as(f32, @floatFromInt(elapsed_ns)) / @as(f32, @floatFromInt(duration_ns));
    model.fraction = tween.from + (tween.to - tween.from) * easeInOutCubic(t);
},

注意 start_ns 的设计:第一个 tick 才盖章起点,0 表示尚未开始——tween 的时钟从第一个呈现帧起算,而不是从更早的输入时间戳起算。缓动函数 easeInOutCubic 定义在同文件(main.zig),是经典三次缓入缓出。

3. 每次 tick 都是完整重建:模型分数改变 → rebuild → 布局变化 → 请求下一帧 → on_frame 再次触发。整个循环依赖"变更 → 请求帧 → 再变更"的自我维持。

这解释了为什么 README 称 runtime Tween 是它的替代品:手动模式里模型每帧都被 Msg 唤醒、完整重建,而 runtime 模式模型只在翻转 collapsed 时醒来一次。观测差异也很直观——manual 模式打印 tween-frame dt_ms=... fraction=...(并带 tween-done frames=N 收尾),runtime/markup 模式打印 tween-echo fraction=...,同一测量,两种开销。

模型契约测试:headless 验证三种模式

示例自带的 examples/split-collapse/src/tests.zig 是模型契约测试,README 给出的运行方式是:

native test -Dplatform=null

三个测试分别钉住三种模式的关键不变式:

  1. manual tween 数学:翻转后 tween 创建;第一个 tick 只盖章起点(分数仍在原点 0.35);90ms 中点时分数严格介于两端点之间;200ms 后精确落到 0.06 且 tween 清空;
  2. runtime 模式只翻静止标志:翻转后 fraction 仍是上次 echo 的值(0.35)、tween == null——运行时才是分数的唯一写者;并验证 split_resized echo 路径确实能更新分数;
  3. markup 模式推导声明分数:pane_fraction() 随 collapsed 在 0.35/0.06 间切换——这正是 value="{pane_fraction}" 绑定在模型侧的契约。

测试同时确认了"runtime-tween 的覆盖在运行时自己的布局动画测试里"(src/runtime/canvas_widget_split_tree_tests.zig),示例测试只负责模型层契约——职责划分清晰。

额外旋钮:自动切换与实时 WebView 重排

README 还提供了两个"重负载形态"旋钮,都从环境变量解析(main.zig):

SPLIT_COLLAPSE_AUTO_MS=

以毫秒为间隔武装一个重复自动切换计时器,让 tween 无需自动化脚本也能持续观察:

fn initFx(model: *Model, fx: *Effects) void {
    if (auto_toggle_interval_ms == 0) return;
    fx.startTimer(.{
        .key = 1,
        .interval_ms = auto_toggle_interval_ms,
        .mode = .repeating,
        .on_fire = Effects.timerMsg(.auto_toggle),
    });
}

auto_toggle Msg 与按钮的 toggle 走同一个 applyToggle,动画行为完全一致。

SPLIT_COLLAPSE_WEB=1

把一个实时 webview 吸附到内容窗格的锚点上,让 tween 期间真实网页内容随窗格一起流式重排——README 称之为 "the heavy field shape"。实现分三层:

  • 视图侧在内容窗格预留锚点:Zig 视图是 ui.column(.{ .grow = 1, .semantics = .{ .label = web_pane_anchor } }, .{})(main.zig),markup 侧是 <column grow="1" label="content-web-pane"></column>(split_collapse.native);
  • webPanes 回调把 webview 的标签与锚点填进输出(main.zig);
  • shell_views 里声明了 kind = .webview、parent = canvas_label 的视图(main.zig),运行时每个呈现帧把它吸附到锚点布局帧上。

运行方式与项目配置

示例面向 macOS 系统后端(app.zon 中 platforms = .{"macos"}),按 README 的说明,在示例目录下运行:

native dev

即可启动 800×520 的 "Split Collapse" 窗口,看到侧边栏在按钮(或 SPLIT_COLLAPSE_AUTO_MS 计时器)触发下以 180ms 折叠/展开,同时观察 stderr 上的 tween-echo / tween-frame 帧节奏日志。模型契约测试则完全 headless:

native test -Dplatform=null

应用声明(examples/split-collapse/app.zon)还展示了示例的权限与安全基线:permissions = .{ "view", "command" }、能力 native_views + gpu_surfaces,导航只允许 zero://app 与 zero://inline 源,外部链接一律 deny——这与 main.zig 中 app_permissions 及 security 配置(允许 https://example.com 作为 webview 源)相互印证。

小结:三种写法,一个原语

split-collapse 的价值在于把同一段 180ms 动画写成三种形态,并让它们共享同一测量通道:

  • Runtime Tween(默认):模型只持有静止 collapsed 标志,layout_tweens 声明目标,运行时按呈现帧缓动——无逐帧 Msg、无完整重建,reduce-motion 自动 snap;
  • Markup Tween:resize-duration="180" + resize-easing="standard" 写在 <split> 上,视图文件即动画,Zig 侧零 hook,与 Zig 声明逐位等价(有全栈测试钉住);
  • Manual Ticks:on_frame → frame_tick → update 手写 easeInOutCubic 缓动,每 tick 完整重建——这正是新原语要替代的历史习惯用语。

无论哪种形态,tween-frame dt_ms=... 与 tween-echo fraction=... 都让帧节奏可数、可读、可自动化断言。如果你想在自己的 Native SDK 应用里加入窗格折叠动画,最省力的路径就是照抄 markup 形态的三行属性;如果你想理解动画到底发生在哪一层,startCanvasWidgetLayoutTween 的契约(src/runtime/canvas_widget_state.zig)与全栈对比测试(src/runtime/canvas_widget_split_tree_tests.zig)是最完整的教材。

登录后查看全文
native