Keel v0.5.1 English GitHub

元素与视图(ui/el)

ui/el 是 GPUI 风格的写法:界面是一个视图(普通的 Go struct),每一帧调用它的 Render,返回一棵用链式样式搭起来的元素树。状态就是 struct 的字段,事件回调直接改字段,下一帧自动重画。

type Counter struct{ n int }

func (c *Counter) Render(cx *el.Context) el.Element {
    return el.Div().P(24).Gap(12).Items(el.Start).Child(
        el.Text(fmt.Sprintf("点了 %d 次", c.n)).TextSize(20).Bold(),
        el.Div().Px(16).Py(8).Rounded(6).Bg(theme.Primary).TextColor(theme.OnColor).
            CursorPointer().Hover(func(s *el.Style) { s.Bg(theme.PrimaryHover) }).
            OnClick(func() { c.n++ }).
            Child(el.Text("+1")),
    )
}

window.Open(window.Options{Title: "计数", Content: el.Root(&Counter{})})
window.Main()

和直接写 Gio 比:

Gio el
交互状态 每个组件自己声明 widget.Clickable 等字段 框架按元素位置(或 ID)自动保存,不用声明
布局 层层嵌套 layout.Flex{}.Layout(gtx, layout.Rigid(...)) flexbox:内外边距、间距、伸缩、对齐、百分比尺寸、滚动、绝对定位
样式 每次绘制手写 每个元素都能链式设置,悬停、按下有样式变体
事件结果 处理顺序取决于布局顺序 先处理事件再渲染,同一帧就画出
Agent 语义 手动声明 自动:有 OnClick 的是按钮,文字是文本,Input 是输入框

现成组件在 ui/kit,它们都是 el 视图。

一帧里发生了什么

1. 分发事件   上一帧登记过的点击 → 调用对应元素的 OnClick
2. 渲染       view.Render(cx) → 元素树(按当前状态,每帧新建)
3. 布局       flexbox 引擎算出每个元素的位置和尺寸
4. 绘制       背景、边框、文字;登记点击区域;生成语义信息
5. 回收       这一帧没出现的元素,状态删掉

Render 每帧都会调用,要保持便宜:只根据状态搭树,不做 I/O、不做大计算。耗时的事放 goroutine,完成后用 core.Update 改状态。线程规则和其他模块相同,见架构 · 线程规则。

Render 中创建的元素使用所属 root 的节点 arena,在该 root 下一次开始构建前可用于布局、绘制和尺寸查询。回调可能让同一帧构建两次。下一次构建开始后,旧元素即使尚未复用槽位,访问也会 panic;不同 root 的临时元素也不能混入同一棵树。跨帧保留视图状态和 ID,在 Render 中重新搭树。

Context.Cache 的构建函数使用独立的持久节点。整棵缓存子树都要在构建函数内创建;引用外层 Render 的临时元素会 panic。在 Render 之外创建的元素仍保留原有的持久生命周期。元素构建和渲染同样受 UI 帧锁保护,后台 goroutine 通过 core.Update 提交状态。

arena 从第二次构建起按 32 个节点分块复用,并保留节点的 children、流式布局位置和文字颜色区间缓冲。只使用一次的 root 首次按需分配节点。未使用的节点清掉引用,多留一块应对可见行数的小幅变化。指针 API 对应的小句柄按批分配,每个句柄保存独立代号,后续构建不会覆盖它;这部分仍会产生少量分配。

句柄批容量参考上一轮用量,限制在 4~32 个,避免小 root 为每种元素都预留整批。颜色、文字属性、定位偏移和圆角半径采用内联值和设置标记;显式透明色和零值仍覆盖继承,复制 Style 不会共享这些值。静止绘制样式留在栈上,只有实际执行用户样式回调时才分配私有副本,同一节点的回调共用它,后续帧不覆盖。文字测量复用帧内条目,哈希冲突仍校验完整 key;输入文档按不可变内容和对象模式缓存只读文字映射,编辑、撤销及 IME 变化都会使旧映射失效。

未显式设置的文字颜色在绘制时按当前调色板解析,Themed 子树不会提前捕获全局默认色。

迁移:不要跨帧保存临时元素

节点 arena 是破坏性的生命周期变更,即使 builder 方法签名没有变化。在 Render 中创建并保存的元素,到了下一次构建再访问就会 panic;同一帧内第二次构建也会让旧元素失效。不要跨帧保存 *DivEl、*TextEl、*InputEl、*WidgetEl 或 Element 字段,设置 ID 也不会延长元素寿命。

把应用状态留在视图中,每次重新构建元素:

func (v *Counter) Render(cx *el.Context) el.Element {
    return el.Text(strconv.Itoa(v.count))
}

不变的子树可以用 Context.Cache,整棵树都在 builder 内构建:

return cx.Cache("static-title", func() el.Element {
    return el.Div().Child(el.Text("设置").Bold())
})

缓存 key 应唯一标识子树,并包含会影响它的输入;不要把外层 Render 的临时元素传进缓存 builder。聚焦和滚动保存 ID,长期输入状态保存在视图或 InputDocument,不要保存在临时 InputEl 中。

数字标签图片缓存

大量数字标签持续变化的界面,可以按需共用一份字形图集:

atlas := new(theme.GlyphAtlas)
root := el.Root(view)
root.SetTextAtlas(atlas)
window.Open(window.Options{Content: root, OnClose: atlas.Release})

每个 root 使用独立的图集。root 应以整数像素平移绘制,不额外缩放或旋转;字号仍随显示比例换算。SubpixelPhases 保持零即可保留字形位置。root 先准备可见、较短、不透明且包含数字的单行标签,再统一提交变化的图片页并绘制。文字、字体、约束和颜色必须与准备时一致。标签原点带小数、复杂排版、Decorate 或滚动子树、浮层、富文本和编辑器继续使用原来的绘制路径,点击和无障碍标签保持有效。

每帧最多保留 2048 个标签、32768 个字形的准备数据,超出的标签使用原路径。图片和掩码遵守 GlyphAtlas 的预算,GPU 副本另占内存。首帧需要建立缓存,启用前应测量实际界面的启动、CPU 和物理内存。向 SetTextAtlas 传入 nil 可关闭;图集由调用方持有,不再使用时调用 Release。

元素

构造 说明
el.Div() 盒子,唯一能有子元素的元素。默认子元素从上到下排列
el.Text(s) 文字,按可用宽度自动换行
el.Input() / el.TextArea() 输入框,带默认边框样式,获得焦点时边框变蓝。单行框默认高 theme.ControlHeight,文字垂直居中,和 kit 的字段一致;点内边距也会聚焦
el.Widget(w) 嵌入任意 core.Widget,比如用 core.Func 包起来的一段 Gio 布局

输入框:

el.Input().ID("q").Placeholder("搜索").Bind(&v.query).OnChange(func(s string) { v.refresh() }).OnSubmit(v.search)

点击空白处会让输入框失去焦点。

Bind(&字符串) 双向绑定:用户输入会写进变量,程序改了变量,下一帧输入框也跟着变。Password() 遮盖内容。MaxLen(n) 限制字符数,Filter("0123456789") 只接受这些字符(输入和粘贴都会过滤),ReadOnly(true) 允许选择复制但不能编辑。单行输入框设置 OnKey 后,↑ ↓ PageUp PageDown 先交给它处理,编辑器不再收到这几个键(单行框里它们本来只能把光标移到开头或结尾);带 Shift 等修饰键的组合仍归编辑器,用来扩展选区。返回值不影响结果,这几个键总是被拿走。输入框位于 Disabled(true) 的子树里时不能编辑,el.Widget 嵌入的 Gio 代码也一样。

输入框外面再包一层框(带图标、按钮的搜索框)时,给外框设 ID 和 FocusOnPress(输入框ID):点外框里没有子元素接住的地方会聚焦输入框,鼠标显示文字光标;外框不会因此变成按钮,也不进 Tab 顺序。

样式方法

所有元素共享同一套方法(Styled[T] 泛型实现,链式调用返回原来的类型):

分类 方法
方向与对齐 Row()、Col()(默认)、Wrap() 自动换行、Grid(columns) 等宽列网格、ColSpan(n) 跨列、Gap(dp)、Justify(Start/Center/End/SpaceBetween/SpaceAround)、Items(Start/Center/End/Stretch)(交叉轴:Row/Wrap 默认 Center,图标与文字无需额外设置即可对齐;Col/Grid 默认 Stretch。需要子元素撑满行高时,如侧栏外壳、等高卡片,写 Items(el.Stretch);Items(el.FirstLine) 让每个子元素的第一行文字对齐,例如 label 配 Checkbox、输入框或段落,图标居中在这一行上)、Center()
伸缩 Grow() 等于 CSS 的 flex: 1:初始尺寸按 0 算,分享剩余空间;其他元素空间不够时按比例收缩,NoShrink() 禁止收缩
尺寸 W(l)、H(l)、Size(l)、MinW/MinH/MaxW/MaxH(l)、WFull()、HFull();长度用 el.Dp(40)、随字号缩放的 el.Sp(40)、el.Frac(0.5)、el.Full
间距 P、Px、Py、Pt、Pb、Pl、Pr(内边距),M、Mx、My、Mt、Mb、Ml、Mr(外边距),单位 dp
滚动与定位 ScrollX() 横向滚动(需要约束宽度)、ScrollY() 纵向滚动(需要确定的高度),StickToBottom() 跟随到底,ScrollToEndOn(v) 在 v 变化时跳到底部;Absolute() + Top/Right/Bottom/Left 绝对定位,同时给左右会拉伸宽度
外观 Bg(c)、Border(dp, c)、Rounded(dp)(用 theme.RadiusSm/Md/Lg/Xl/Full),RoundedCorners(左上, 右上, 右下, 左下) 分别设置四个角,比如按钮组只圆外侧的角、Shadow(theme.ElevationSm/Md/Lg) 阴影画在元素外面、不改变尺寸,Opacity(a) 设置整个子树 0–1 透明度(0 完全不绘制,仍保留布局和交互),CursorPointer()、Hidden(b)、IsHidden()(读取本元素声明的隐藏值,不包含祖先)
文字(向下继承) TextColor(c)、TextSize(sp)(用 theme.TextXs … theme.TextHeading)、Bold()、Medium()、Mono() 等宽字体(theme.MonoFace)、Italic() 斜体、LineHeight(倍数)、MaxLines(n)
状态变体 Hover(func(*el.Style))、Active(func(*el.Style)):悬停、按下时的颜色变化,背景在 120ms 内渐变过去;开启减少动画(theme.SetReducedMotion,自动化模式默认开启)时直接切换
交互 OnClick(fn)、OnDoubleClick(fn)
结构 ID(s)、Child(...)、Children(slice)、When(cond, func(*T))
Agent 语义 Role(s)、Name(s)、Value(s)、Selected(b)

布局规则按 flexbox 的直觉来,和 CSS 有几处不同:

  • Div 默认纵向排列、子元素拉满宽度(像块级元素),Row() 改成横向。
  • 横向排列的子元素宽度取内容宽度;空间不够时一起按比例收缩,文字随之换行。
  • ScrollY 的视口是内边距盒,内边距跟着内容滚动。
  • 文字样式像 CSS 一样向子元素继承。

状态和 ID

元素的内部状态(悬停、按下、滚动位置、输入框内容和光标)由框架保存,键是元素在树上的路径:每一层取它的 ID,没有就取它在兄弟中的序号。

会增删、重排的列表项要给 ID,否则状态会按位置错配(比如删掉第一行,第二行的输入框内容跑到第一行):

el.Div().Children(el.Map(v.rows, func(i int, r Row) el.Element {
    return el.Div().ID(r.ID).OnClick(func() { v.open(r) }).Child(el.Text(r.Name))
}))

元素某一帧没有出现,它的状态就被删除。隐藏再显示的输入框会清空;要保留内容,用 Bind 把内容放在视图的字段里。

视图与组合

视图是任何实现了 Render(*el.Context) el.Element 的类型。拆分界面就是拆分 struct,在父视图的 Render 里调用子视图的 Render:

type Page struct{ list *OrderList; form *OrderForm }

func (p *Page) Render(cx *el.Context) el.Element {
    return el.Div().Row().Gap(16).Child(
        el.Div().W(el.Dp(300)).Child(p.list.Render(cx)),
        el.Div().Grow().Child(p.form.Render(cx)),
    )
}

el.ViewFunc(func(cx *el.Context) el.Element { … }) 将函数适配成 View,适合传给 kit 的内容插槽。插槽持有 View,每帧调用 Render;主题色在函数内读取,不要在构造视图时保存 Element。

cx.Shortcut("mod+s", fn) 在视图渲染期间绑定快捷键。

动作与键位表

要让用户改键,就不要在视图里写死按键,改成命名动作:

core.Bind("editor.save", "mod+s")      // 启动时设默认键,可以给多个
core.LoadKeymap(userJSON)              // 叠加用户的 {"editor.save": ["ctrl+alt+s"]}

func (v *editor) Render(cx *el.Context) el.Element {
    cx.Action("editor.save", v.save)   // 绑定到这个动作的每个键都会触发
    ...
}
  • 键位表是全局的,core.Bind 替换一个动作的全部按键,不传按键就是解绑;按键写错时返回错误,什么都不改。
  • 改键后所有窗口重绘,下一帧起生效;cx.Action 每帧按当前键位表注册,不用重启。
  • cx.Perform(targetID, action) 在回调里直接执行一个动作,效果和焦点在 targetID 时按下它的快捷键一样:先找包住该元素的最内层 cx.ActionAt,再找 cx.Action;不需要绑定键。菜单的 ActionItem 和命令面板用它共用命令实现,返回值表示是否有处理器运行。
  • core.Bindings(name) 查一个动作的按键,core.Keymap() 返回全部,可以用来做快捷键设置页。
  • 显示按键用 kit.KbdFor(name) 和 Menu.ActionItem,它们跟着键位表变。

缓存不变的部分

长列表、聊天记录里大部分内容每帧都不变。cx.Cache(key, build) 在 key 不变时直接复用上一帧的元素和布局,build 不会被调用:

for _, m := range v.msgs {
    m := m
    list.Child(cx.Cache(msgKey{m.id, m.version}, func() el.Element { return v.message(m) }))
}

key 必须能比较,而且元素的样子只由 key 决定:外观会变时 key 也要变(比如带上版本号)。某一帧没用到的缓存项会被删掉。ui/markdown 就是这样缓存写完的块的。

构建函数必须自己创建要保留的元素。不要捕获外层 Render 中已经建好的临时元素;捕获它需要的数据,再在构建函数内搭树。

主题切换时 theme.Apply 会使 cx.Cache 的元素在下次访问时重建。自建缓存需要包含 theme.Revision();主题色应在 Render 或缓存构建函数内读取,固定颜色不会自动转换。

复制到剪贴板

el.WriteClipboard(text) 在回调里调用,当前帧写入系统剪贴板。

焦点、按键与禁用(E1 / E2)

el.Div().ID("save").Focusable(true).
    OnClick(save).
    FocusStyle(func(s *el.Style) { s.BorderColor(theme.Primary) }).
    Child(el.Text("保存"))

Focusable(true) 让元素接受点击焦点,并按绘制顺序参与 Tab / Shift+Tab 导航,与 Input、TextArea 共用原生焦点顺序。隐藏、移除和完全滚出绘制区域的节点不参与导航。带 OnClick 的元素默认可聚焦;Focusable(false) 显式退出 Tab 顺序。

聚焦元素收到无修饰键的 Space / Enter 时,在匹配的按键释放事件中调用一次 OnClick;失去焦点后不保留待激活按键。OnKey(func(el.KeyEvent) bool) 接收按下和释放事件,从聚焦元素向有处理器的祖先冒泡。返回 true 会停止冒泡并取消默认激活。KeyEvent 是 el 自己的结构体,包含 string 类型的 Name、KeyPress/KeyRelease 状态和 key.Modifiers。Tab 保留原生导航行为;全局快捷键继续使用 cx.Shortcut。

FocusStyle(func(*el.Style)) 是绘制样式,可改背景、边框色和文字色,不改变尺寸。普通元素通过 Tab、方向键、Space / Enter 或程序主动聚焦时,默认使用 2dp Primary 焦点边框。鼠标点击保留实际焦点和键盘操作能力,但不绘制焦点样式;点击回调中的同步 cx.Focus 也遵循此规则。输入框聚焦时始终沿用自身边框。文字色传递给未显式设置颜色的子元素,失焦后恢复。

cx.Focus("save") 在本帧绘制后请求焦点,也支持带 ID 的 Input / TextArea。ID 应在当前 root 内唯一;重复时选择第一个已绘制的匹配目标。目标不存在、隐藏或完全在视口外时保留原焦点;cx.Focus("") 清除焦点。只能在 Render 或其事件回调里调用。

当前 OnKey 冒泡源是可聚焦的普通元素;输入框编辑按键仍由 Gio editor 处理,不通过这条冒泡链。焦点陷阱留给浮层阶段。可运行 go run ./examples/components -section focus 验证接口。

cx.Focused(id) 读取当前焦点,查询支持普通元素和输入框。Disabled(true) 自上而下禁止子树的点击、悬停和按键,释放当前焦点,禁止程序聚焦,并将 Agent 语义标记为 disabled;解除禁用后可重新聚焦。DisabledStyle(func(*el.Style)) 设置禁用外观,默认文字为 Muted。显式禁用与测量时没有输入源分开处理,连续测量不会清空交互状态。

时间与减少动画(E3)

cx.Now() 返回本帧时间;动画只从它计算相位。cx.Animating() 请求下一帧,不创建 goroutine。循环指示器(Spinner、不确定进度、扫光、骨架屏脉冲)改用 cx.AnimatingAmbient():它请求墙钟上下一个 el.AmbientFrameInterval(1/30 秒)刻度的帧,所有可见指示器共用同一帧;窗口里只有指示器在动时按 30 Hz 重绘,而不是显示器刷新率。过渡动画、滚动和输入仍然每个显示帧都绘制。el.ReducedMotion() 查询应用偏好;theme.SetReducedMotion(true) 在帧锁内切换。当前没有原生系统偏好桥接,默认 false。

只改变绘制方式的指示器(例如环形的旋转)可以在绘制时读取相位:在 el.Widget 内调用 el.AmbientPhase(gtx, period),返回本帧时间的相位并请求下一个环境刻度。这样两次环境帧之间元素树保持不变,窗口的根元素直接用上一帧的元素树和布局重绘,不再调用 Render(纯绘制帧;这类帧在 el 中的工作量约减少三分之一)。以下情况仍完整渲染:本帧或上一帧有输入;core.Update 或任意回调之后;有等待中的计时器;窗口尺寸、缩放或状态变化;上一次 Render 调用了 cx.Now()、cx.Animating() 或 cx.AnimatingAmbient()。只有窗口自己的根元素这样重绘,嵌入的根元素和测试总是完整渲染。因此视图同样只能通过回调和 core.Update 改变。kit.Spinner 和不确定状态的 kit.ProgressCircle 在绘制时动画。

cx.After(key, duration, callback) 声明一次性定时器,key 必须可比较且在当前 root 内唯一。存活期间每次 Render 声明同一个 key;某帧没有声明即取消,与调用位置和声明顺序无关。duration 变化时重新计时。触发后持续声明不会重复执行,省略一帧再声明才会重新启动。回调在帧锁内、当前树绘制完成后通过 core.Call 执行,并通知所有窗口重绘。

type noticeTimerKey struct { ID string }
if visible {
    cx.After(noticeTimerKey{noticeID}, 3*time.Second, func() { visible = false })
}
return el.Div().Hidden(!visible).Child(el.Text("已保存"))

同类组件用自身稳定 ID 组成 key。不要在 cx.Cache 的构建函数里声明 After:缓存命中时不会执行构建函数,未再次声明的定时器会被取消。应把 After 放在每次执行的 Render 路径上,再单独缓存元素树。

滚动状态与锚定

ScrollX() 让子内容横向延展并裁剪到视口,可与 ScrollY() 组合。支持水平滚轮和触控板水平手势;横纵轴分别消费对应滚动量。cx.ScrollStateX(id) 返回偏移、视口宽度、内容宽度(dp);cx.ScrollIntoViewX(id, left, right) 最小滚动以显示目标区间。横纵滚动条支持拖动滑块、点击轨道定位,并随浅深色主题切换。滚动容器添加 Focusable(true) 后可用 Tab 聚焦,再用方向键、PageUp/PageDown、Home/End 滚动;双轴容器的 Shift+PageUp/PageDown、Shift+Home/End 操作横轴。组件自身 OnKey 优先处理(如表格行选择)。示例:go run ./examples/components -section scrollable。

Scrollbars(el.ScrollbarAlways / el.ScrollbarHover / el.ScrollbarScrolling) 设置单个滚动容器的显示策略,两轴共用;默认 System,跟随系统偏好;Always 在内容溢出时持续显示。Hover 在指针进入整个视口时显示;Scrolling 在偏移实际变化后显示,停止 900ms 后隐藏,鼠标拖动滚动条期间持续显示。程序定位、键盘滚动也会显示;停在边界且偏移不变不会重新计时。隐藏后不保留滚动条点击区域,内容仍能接收指针事件;滚轮和键盘滚动不受策略影响。ScrollOffset 的受控模式仍隐藏所有滚动条。Hover 和 Scrolling 模式下滚动条出现时 120ms 淡入、隐藏时 200ms 淡出(开启减少动画时直接显示或隐藏),淡出过程中不接收点击;Always 不渐变,从 Always 切到其他模式立即隐藏。

Scrollbars(el.ScrollbarHidden) 隐藏两轴滚动条,保留滚轮、触摸和键盘滚动,适用于紧凑的标签栏。

el.ScrollbarSystem 跟随系统设置:macOS 读"显示滚动条"(自动/滚动时 → Scrolling,始终 → Always,系统设置改变后实时更新),Windows 读"自动隐藏滚动条"(启动时读一次),其他平台按 Always。没有单独设置模式的容器使用 el.SetScrollbarDefault(mode) 设的默认值,默认值为 System;想让整个应用的滚动条常显,可调用 el.SetScrollbarDefault(el.ScrollbarAlways)。圆角容器会缩进轨道两端,避免滑块被圆角裁切;内容布局不变。内置可选列表行和横向组件条预留 12dp,包括 10dp 滚动条交互区和 2dp 间隔。自行组合 ScrollX/ScrollY 内容时,可用内边距或行外边距预留同样的空间。滚动条显示和隐藏不会改变内容尺寸。el.SystemScrollbars() 返回读到的系统偏好。已验证横纵双倍率交互、空闲隐藏后的点击穿透、拖出视口时继续拖动和显示策略切换的窗口像素。

cx.ScrollState(id) 返回带 ID 的 ScrollY 元素上一帧的滚动偏移、可视高度、内容高度,单位 dp;第一次绘制之前三个值都是 0。虚拟列表用它决定构建哪些行。cx.ScrollIntoView(id, top, bottom) 以最小的滚动量让内容中 [top, bottom] 这一段可见,在下一次绘制时生效。

KeepBottomOn(version):version 变化的那一帧,保持到底部的距离不变,在上方插入内容(比如加载更早的聊天记录)时画面不会跳动。在插入内容的同一个回调里递增 version,用法和 ScrollToEndOn 一样。

Flex(w) 和 Grow 一样占用剩余空间,但按权重分配:Flex(2) 分到的是 Flex(1) 或 Grow 的两倍。

拖动

el.Div().ID("track").W(el.Dp(240)).H(el.Dp(20)).OnDrag(func(e el.DragEvent) {
    v.value = clamp(e.X / e.W) // 按下、移动、松开都会调用
})

DragEvent.Kind 是 DragStart(按下)、DragMove(按住移动,指针移出元素也继续报告)、DragEnd(松开或取消)。X、Y 是相对元素左上角的 dp,W、H 是元素尺寸,所以 X/W 就是水平方向的比例。按下时会聚焦可聚焦的元素。禁用的元素收不到拖动。

浮层(E4 / E5)

在 Render 中调用 cx.Overlay(key, layer) 声明浮层。key 必须可比较,并在当前 root 内唯一。打开状态由视图保存,打开期间每次 Render 都声明;某帧省略就关闭。不要在 Cache 的构建函数里声明浮层。后声明的浮层在上层,Esc 只请求关闭最上层。

if v.open {
    cx.Overlay("filters", el.Anchored("filter-button",
        el.Div().W(el.Dp(280)).P(16).Bg(theme.Surface).Child(
            el.Text("筛选条件"),
            el.Input().ID("query").Bind(&v.query),
        ),
    ).Placement(el.Bottom, el.Start).OnDismiss(func() { v.open = false }))
}

Anchored(anchorID, content) 使用本帧锚点位置,锚点可在主树或先声明的浮层中。Placement 的方向为 Bottom / Top / Left / Right,对齐为 Start / Center / End,默认 Bottom / Start;Offset 默认 4dp。指定方向放不下、对侧放得下时翻转,再将位置平移到 root 内;超出部分按 root 裁剪。MatchAnchorWidth 让浮层与锚点等宽(下拉框与触发器同宽),内容按这个宽度换行或截断。锚点不存在或隐藏时不绘制,并调用一次 OnDismiss。

非模态浮层之外、且不在锚点上的按下事件会请求关闭,并继续传给下面的元素。.Modal() 使锚定浮层拦截外部点击;el.Modal(content) 创建默认居中的模态浮层,自带遮罩和焦点约束,遮罩在绘制时读取 theme.Scrim,随运行时主题切换更新;.Scrim(false) 只隐藏遮罩颜色,仍拦截输入。模态期间背景不响应悬停和点击,Agent 快照也不列出被遮挡的主树及下层浮层。

layer.Owner(id) 把浮层生命周期绑定到本帧树中的启用元素。可用于模态组件:返回一个带 ID 的零尺寸 Absolute 元素作为所属标记,再给 Modal 设置 Owner;祖先禁用、隐藏或移除标记时会请求关闭。Owner 不改变定位,也不会把浮层自身的模态遮挡当成禁用。

.TrapFocus() 将 Tab / Shift+Tab 限制在浮层内,出现时聚焦第一个可聚焦元素;同帧 cx.Focus(id) 可指定浮层内的目标。关闭后恢复先前焦点,原目标已经移除时清除焦点。未开启焦点约束的非模态浮层不移动焦点。OnDismiss 在帧锁内执行,只通知调用方更新打开状态,不会替调用方保存 open。

el.Modal(content).Placement(side, align) 把模态内容贴在 root 的某条边上,而不是居中,用于侧边抽屉:Placement(el.Right, el.Start) 贴右边、顶端对齐。

Esc 交给最上层设置了 OnDismiss 的浮层。没有 OnDismiss 的浮层(例如通知栈)不会吞掉 Esc,下面的对话框照常关闭。

cx.FocusWithin(id) 查询该元素或它的任一子孙是否在上一帧获得焦点,Tooltip 用它在键盘聚焦时显示提示。

cx.FocusVisibleWithin(id) 是用于焦点框的 FocusWithin:和 cx.FocusVisible 一样,只统计来自键盘或程序的焦点。鼠标点进输入框只显示闪烁光标;用 Tab 键、或在非鼠标回调里调用 cx.Focus 聚焦时,才显示焦点框并应用 FocusStyle。字段外框用它判断,所以鼠标点击或用鼠标选完不会留下蓝框。

cx.Hovered(id) 查询最近处理的指针位置是否位于元素内,禁用或被模态层遮挡的元素返回 false。普通带 ID 的元素也可查询,不必添加点击回调。HoverCard 可组合锚点和卡片的 Hovered 结果。

挂到窗口根部

cx.Mount(key, view) 把一个视图挂到当前 root 上:之后每帧先渲染根视图,再按挂载顺序渲染这些视图,返回的元素放进根元素,不参与它的排版(应返回浮层声明、Absolute 或隐藏元素)。同一个 key 再次挂载会替换原视图,cx.Unmount(key) 取下,cx.Mounted(key) / cx.MountedView(key) 查询。根元素是文字、输入框这类叶子时会自动包一层容器。kit 的 Dialog.Show、Sheet.Show 和 kit.WindowNotifier 就建立在它上面,对应 GPUI 根视图自带的对话框、抽屉和通知层。

Hover 和焦点查询在本轮渲染首次使用时,为上一份声明建立索引,避免每查一个 ID 都重新遍历全部状态或元素树。输入分发和重新渲染时会使索引失效;禁用、模态遮挡及鼠标与键盘焦点的行为保持不变。

完整浮层能力要求 el.Root。el.Embed 使用嵌入时的最大约束,通过 op.Defer 延后绘制,属于尽力支持;其可用空间不一定等于窗口大小。浮层不跨窗口。无输入源的帧统一按只读帧处理,包括测量和父组件禁用。它们复用真实的 store/cache,保留输入内容和滚动位置;不分发事件、不触发关闭回调、不增减浮层生命周期、不推进定时器,也不清理状态或覆盖焦点恢复记录。

验证:go run ./examples/components -section overlay,加 -theme dark 检查深色;切换浮层、打开模态、编辑输入框,并用 Tab / Shift+Tab / Esc 检查焦点。

做成可复用的组件

组件就是返回 el.Element 的函数,参数是它需要的数据和回调:

func button(label string, onClick func()) el.Element {
    return el.Div().ID(label).Px(16).Pt(10).Pb(6).Rounded(6).
        Bg(theme.Primary).TextColor(theme.OnColor).TextSize(14).
        CursorPointer().Hover(func(s *el.Style) { s.Bg(theme.PrimaryHover) }).
        OnClick(onClick).Child(el.Text(label))
}

需要自己的状态、而且状态要跨帧保存的组件,写成视图(struct + Render)。

局部主题

cx.Themed(palette, view) 用另一套调色板渲染一个视图:它渲染和绘制时都换用这套颜色,所以里面的 kit 组件和自己画的内容都跟着变,窗口其余部分仍用全局主题。适合浅色窗口里的深色侧栏、主题预览。返回的盒子会拉伸子元素,要铺满颜色就给它设背景。

nord, _ := theme.Named("nord")
cx.Themed(nord, sidebar).Bg(nord.Bg)

用 cx.Cache 缓存的元素按全局主题版本失效,局部主题里的内容不要跨主题复用缓存。

放进窗口和嵌入 Gio

  • 整个窗口用 el:window.Options{Content: el.Root(view)}。Root 占满窗口,窗口不再加边距和外层滚动;页面要滚动时,给根 Div 加 ScrollY()。浮层(对话框、菜单)用 cx.Overlay 声明,不需要 window.Options.Overlay。
  • 在 el 里放 Gio 代码:el.Widget(w) 嵌入任意 core.Widget,比如用 core.Func 包起来的一段 Gio 布局。
  • 把 el 放进 Gio 布局:el.Embed(view) 得到一个按内容定尺寸的 core.Widget。

el.Root 和 el.Embed 实现 core.ViewportWidget:el 容器以组件本地像素坐标传递父级滚动裁剪区,长内容只绘制可见子节点,完整自然高度保持不变。包装时用 core.ViewportFunc,将矩形传给 root.LayoutViewport(gtx, visible)。普通 core.Func 包装保留原有行为。空矩形表示只测量、不绘制,不会缩小布局约束或内容尺寸。

在另一个 el 树中用 widget 包装嵌入 root 时,调用 root.LayoutIn(gtx, visible, cx),传入构建该 widget 的 Context。它会把外层滚动容器和 widget 的内容原点传给嵌入 root。Markdown 选区随外层滚动更新,拖到视口边缘时也能滚动父容器;widget 带内边距时坐标仍保持一致。嵌入 root 应保存在视图状态中,避免每帧重建:

// nested 是保存在视图状态中的 el.Embed(view)。
return el.Widget(core.ViewportFunc(func(gtx core.C, visible image.Rectangle) core.D {
    return nested.LayoutIn(gtx, visible, cx)
}))

cx.ScrollViewport() 在 Decorate 中返回最近一层纵向滚动容器的可见边界,坐标相对于外层根。它不会像 PaintGeometry 那样收窄到局部可见的子元素。使用 LayoutIn 的嵌入根会继承这个边界,拖选到边缘时可据此滚动,避免消息进出视口导致速度变化。

直接嵌入原生 Gio、没有父级 el Context 时使用 LayoutViewport。布局和 Markdown 测量缓存包含显示度量,字号缩放或像素密度变化后会重新计算换行和选区尺寸。

Agent 能看到什么

不用额外写代码:

元素 Agent 看到的
Text text,名字就是文字
带 OnClick 的 Div button,名字是里面的文字
Input textbox,名字是 Name 或占位文字,值是当前内容
.Role("tab").Selected(true) tab,选中
.Role("progressbar").Name("导入").Value("40%") progressbar,值 40%

滚动容器外面的内容不会出现在元素列表里。

已知限制

  • 布局是 flexbox 与 grid 的实用子集:支持 Wrap、Self(align-self)、Grid / GridCols(Dp/Sp/Frac/Auto/Fr)、ColSpan、RowSpan 与 ColGap/RowGap;尚无内容尺寸最小值(min-content)和命名区域。收缩按内容宽度比例分配。
  • ScrollY 里的子元素每帧都布局(看不见的不绘制)。内容不变的局部可用 cx.Cache(手动可比较 key)或 cx.Memo 配合 el.NewSignal / el.NewComputed(自动依赖追踪与嵌套原地局部更新)跳过重建和重排;几百行以上用 kit.VirtualList 或 kit.Table,只布局可见行。
  • 过渡动画实验位于 ui/motion,API 尚不稳定;自定义效果仍可直接使用 Now / Animating。
  • 浮层只在 el.Root 中完整支持,el.Embed 按嵌入约束尽力支持。
  • 浮层不支持跨窗口。

在 Decorate 内可用 cx.LayoutSize(element) 读取同一棵树中元素的最终宽高(dp),包括被裁剪的行。布局前不可读取。虚拟列表可用 cx.ScrollTo(id, offset) 在下次绘制时设置纵向偏移,按新的内容尺寸裁剪,用于内容变化后保持锚点;首次绘制前和只读布局时不生效。

cx.AfterEnabled(id, key, delay, fn) 把定时器绑定到指定元素:元素可见且未禁用时才运行;元素或祖先禁用、隐藏或被模态层遮挡后暂停,恢复时重新等待完整 delay。与 After 一样每帧声明,省略声明会取消。

cx.Enabled(id) 查询最近声明的元素是否可接收输入,包含祖先禁用和模态层阻挡;找不到 ID 时返回 false。在 Render 中查询的是上一轮声明,与焦点查询的时机一致。

Wrap() 从左到右排布,宽度不足时另起一行。Gap 同时作用于行和行内元素;Grow/Flex 在各自行内分配剩余宽度,Justify 对齐每行,Items 对齐同一行内的不同高度元素。无宽度约束时不会换行。

Grid(columns) 按行填充等宽列,GridCols(tracks...) 可显式声明列轨道(Dp、Sp、Frac、Auto、Fr)。Gap 同时设置行列间距,ColGap/RowGap 可分别覆盖。列先满足子元素的固定宽度及最小宽度;若最小宽度之和超过可用空间,保留最小宽度并溢出。每行按最高元素确定高度,自动高度的元素默认拉伸到行高(子元素可用 Self(Start/Center/End/Stretch) 覆盖)。ColSpan(n) 与 RowSpan(n) 支持二维自动排布的跨列与跨行,跨度不足的宽/高会分配到所覆盖的轨道。隐藏和绝对定位元素不占网格单元。尚不支持命名区域。Row、Col、Wrap、Grid、GridCols 会切换布局模式。

验证:go run ./examples/components -section layout,调整窗口宽度检查换行和网格。

PinLeft(offset) / PinRight(offset) 将元素绘制在最近 ScrollX 视口对应边缘的 offset dp 处,保留布局占位。固定元素最后绘制;普通兄弟元素裁剪到两侧固定元素之间,裁剪同时约束点击和语义区域。两侧宽度超过视口时左侧优先。没有横向滚动祖先时保持普通布局,用于表格冻结列等场景。

cx.ClickModifiers() 仅在指针点击/双击回调中返回该事件的 Shift、Ctrl、Command 等修饰键;回调外为零。键盘事件直接使用 KeyEvent.Modifiers。

OnContextMenu(fn) 在次键按下时调用,不吞掉主键操作;回调可用 ClickModifiers。触屏上单指按住约 500ms、移动不超过 8dp 也会触发它,松手不再算一次点击;手指移动、第二根手指按下或被滚动等手势接管时取消。Input、TextArea、Table、Sidebar 的菜单因此都能长按打开。键盘入口通过 OnKey 声明,例如 Shift+F10。锚定浮层在锚点或其祖先禁用、隐藏后关闭,不把浮层自身对背景的输入阻挡视作禁用。

拖动结束时 DragEvent.Canceled 区分取消与正常释放。需要在松手后提交变更的组件应在取消时丢弃暂存结果。

DragAccept(func(dx, dy float32) bool) 与 OnDrag 配合,在初始移动达到 3dp 时决定是否接管。参数是指针相对按下位置的 dp 位移,不是滚动增量;函数应只判断、不修改状态。返回 false 时报告一次 Canceled 的 DragEnd,并让外层手势处理器有机会接管;返回 true 后,本次拖动不再重新判断方向。从可点击、可拖动、输入、滚动容器或嵌入 Widget 子树的可见区域按下时,优先留给子组件,不启动本层拖动。传 nil 恢复普通拖动。适合轮播在起始边界或跨轴拖动时让出手势;外层 ScrollX/ScrollY 的原生拖动滚动按 Gio 规则主要接收触摸,桌面鼠标仍使用滚轮或滚动条。

cx.ViewportSize() 在 Render 阶段返回根视口可用宽高(dp),用于限制命令面板等窗口内浮层的高度,避免键盘滚动目标位于窗口之外。

cx.Countdown(id, key, duration, paused, fn) 声明保留剩余时间的一次性倒计时。显式 paused、所属元素不可见/禁用/被模态遮挡时暂停,恢复后继续剩余时间;改 duration 重启,省略声明取消。与 AfterEnabled 恢复后重新等待完整延迟的语义不同,通知倒计时用 Countdown,悬停提示延迟继续用 AfterEnabled。

element.Reveal(fraction) 按 0–1 比例揭示自然高度,保留子元素完整排版,同时裁剪绘制与输入区域;0 时不占高度且不能获得焦点。用于折叠动画,动画时间仍由组件根据 cx.Now() 驱动。NaN 按 0,越界值限制到 0–1。

鼠标按下监听

OnMousePress(button, fn) 观察左键、右键或中键按下,使用 pointer.ButtonPrimary/Secondary/Tertiary。监听覆盖交互子元素,但不阻止它们接收事件,也不增加 Tab 停靠点;禁用容器会禁用监听。0 清除监听,非法按键值忽略,多键同时按下不触发。它与 OnContextMenu(fn) 共用一个处理器,后者等同于选择右键,最后设置者生效。键盘操作继续使用 OnKey 或子组件回调。

锚定浮层可用 el.Anchored(...).Arrow(true) 绘制 6dp 指示箭头,跟随实际弹出方向;Offset 测量到箭头尖端。箭头取面板纯色背景,未设置时使用主题 Surface,渐变、边框和阴影不延伸到箭头。Modal 不显示箭头。

显式 Tab 顺序

TabStop(false) 跳过顺序遍历,保留鼠标/程序聚焦;TabIndex(n) 按升序排列,相同值保持树顺序,负值跳过,默认 0。显式配置出现时,el root 处理 Tab/Shift+Tab,在当前模态或 TrapFocus 浮层内循环;否则使用 Gio 原生顺序。输入框也参与排序。禁用、隐藏和未绘制的节点跳过。

范围限单个 el root,不跨独立 Embed 或原生 Gio 控件。直接调用 Router.MoveFocus 绕过此规则,应使用正常 Tab 事件;控件显式消费 Tab 时保留其操作行为。

WrapFit() 与 Wrap 一样支持换行;自动宽度时按每行内容收紧,适合按钮胶囊等需要贴合内容的容器。显式或拉伸宽度仍使用常规行对齐及 Grow 分配。调用 Wrap() 恢复填满可用行宽的默认行为。

受控滚动与上一帧尺寸

ScrollX/ScrollY 可配合 ScrollOffset(x, y) 使用绝对 dp 偏移;绘制时按内容边界限制,禁用时仍显示指定位置。指定偏移时停用默认滚动手势并隐藏滚动条,容器可自行使用 OnDrag;省略即可恢复普通滚动;非有限值忽略。应由应用状态持续提供目标位置。

cx.LastSize(id) 在 Render 中读取同 root 上次绘制的元素尺寸(dp),首次或被裁掉时返回零;包含禁用帧的几何更新。cx.LayoutSize(element) 用于 Decorate 中读取当前布局尺寸。窗口尺寸变化后,依赖 LastSize 的布局通常需再绘制一帧收敛。

cx.PixelScale() 返回当前每 dp 的物理像素数,可在 Render 中用于与布局一致的像素舍入,未设置时为 1。

自定义滚动事件

OnScroll(xRange, yRange, fn) 接收 dp 单位的 ScrollEvent,范围使用 el.ScrollRange{Min: ..., Max: ...}。零范围不接收该轴,超出范围的位移由 Gio 路由给外层;子滚动区域优先。nil 移除回调,禁用/隐藏祖先阻止事件。范围按像素尺度换算,非有限端点按 0 处理,端点限制在 ±1,000,000dp。

此事件不暴露滚轮/触控板类型或手势结束相位。可用于受控 ScrollOffset 容器;处理时更新应用状态,再由下一帧应用偏移。

指定内容底边对齐

横向容器使用 Items(el.ContentBottom),可把子项对齐到指定后代的底边。子项用 .ContentBottom(target) 指定当前渲染树中的正常流后代;不指定、目标被隐藏或不在子树中时,回退到子项自身底边。这是几何对齐,不是字体基线。

body := el.Div().Child(header, content, footer).ContentBottom(content)
row := el.Div().Row().Items(el.ContentBottom).Child(avatar, body)

布局使用当前帧尺寸计算对齐线以上和以下所需空间,支持 Row 和 Wrap 的每一行。目标不接受绝对定位节点;容器显式限高时仍遵守限高。此模式不用于纵向容器或 Grid。

el.Input().SelectOnFocus(true) 在获得焦点时选中全部内容。CaptureKeys(names...) 让 OnKey 先于编辑器接收指定的无修饰键,单行输入和 TextArea 都适用;这些键由回调完全负责,返回 false 也不会交还编辑器。带修饰键的按键不受影响,因此捕获 ⏎ 发送的 TextArea 仍可用 Shift+Enter 换行;输入法组字时 Enter 由输入法自己处理。cx.SelectInput(id, start, end) 在下一次 Bind 同步后设置 rune 选区,不改变焦点或文字;端点由编辑器限制到有效范围,缺失或禁用输入忽略。上述接口用于 TimeField 的快速分段编辑,已验证中文 rune 选区、范围限制及带修饰键的编辑行为。

el.Input().TransformEdit(func(before, after el.InputEdit) el.InputEdit) 在编辑归一化时同时提供编辑前后的文本及 rune 选区,适合格式掩码判断删除方向。它与 Transform 互斥,后配置者生效;撤销重做保存归一化后的文本与选区,程序 Bind 更新仍清空历史。已通过掩码删除和撤销重做回归。

cx.InputSelection(id) 返回最近的编辑器文本和 rune 选区。cx.InputAction(id, el.InputCopy / InputCut / InputPaste / InputSelectAll) 将编辑命令排入该输入下一次绘制;缺失/禁用输入忽略,只读拒绝剪切/粘贴,密码输入拒绝命令复制/剪切。Paste 走异步系统文本剪贴板,继续由编辑器完成过滤和 Transform;命令本身不改变焦点,菜单调用方可用 cx.Focus 恢复输入焦点。已通过菜单剪切、焦点恢复和受限输入回归。

ContainerContentSize(element) 可在 Decorate 中读取容器布局后的内容像素尺寸,数值在该容器自身的最小/最大尺寸限制及 Reveal 之前计算;文本、输入和 widget 叶子返回零。

ElementBounds(root, target) 在布局后返回目标相对根元素的边框位置,包含离屏元素,不叠加滚动偏移;隐藏或不属于该树的目标返回 false。可在 Decorate 中结合 ScrollTo 实现离屏定位。

普通容器焦点循环

el.Div().FocusTrap(true) 在焦点进入该子树后,将 Tab / Shift+Tab 限制在其中;FocusTrap(false) 解除。嵌套时当前焦点最近的 trap 祖先生效,多个并列区域各自循环。顺序遵循 TabIndex/TabStop,跳过禁用、隐藏及未绘制节点;输入框参与循环。模态浮层优先,背景区域不会截获浮层 Tab。

它只约束顺序导航,鼠标点击和 cx.Focus 可以切换区域;挂载不会抢焦点,移除不会自动恢复。需要进入时聚焦或退出时返回时,应用调用 cx.Focus(id);浮层继续使用 Layer.TrapFocus 的自动聚焦/恢复。范围限于同一 el root 内的元素,独立嵌入的 core.Widget 自行管理焦点。

组件库 focus 页提供开启、输入和退出演示。自动测试覆盖并列/嵌套区域、双向循环、输入框、TabIndex/TabStop、动态禁用/解除/移除、鼠标退出及模态浮层优先与返回;原生键盘验收仍待完成。

Translate(x, y) 按 dp 移动元素及子树的绘制、点击区域和浮层锚点,不改变原来的布局占位或滚动内容长度。可用于轮播轨道复用同一项目;移位后的可见范围决定是否绘制,父容器裁剪仍生效。

独立字体缩放

cx.TextScale() 返回当前 sp 与 dp 的比例。普通控件应按内容测量并使用 最小高度;固定行高的虚拟列表可使用该比例,使行高计算和绘制保持一致。 显示密度和无障碍字体缩放是独立的。

元素姿态动画

AnimatePose 声明视觉目标。元素保留布局尺寸和位置,绘制、指针区域、语义边界和锚定浮层跟随动画变换。首次声明直接显示目标;后续修改从当前值开始过渡,中途反向时保留弹簧速度。

pose := el.Pose{}
if v.expanded {
    pose = el.Pose{X: 160, Scale: 1.05, Rotate: 8, Fade: 0.1}
}
card := el.Div().ID("card").W(el.Dp(160)).H(el.Dp(90)).
    AnimatePose(pose, el.Snappy).
    OnClick(func() { v.expanded = !v.expanded })

X、Y 的单位是 dp;XPercent、YPercent 是自身尺寸的百分比;Rotate 是绕中心旋转的角度;Scale 默认为一。Fade 从零(不透明)到一(透明)。可使用 Smooth、Snappy、Bouncy、Spring(stiffness, damping) 或 Tween(duration, ease);动画类型与 ui/motion.Transition 共用。

会重排的同级元素需要稳定 ID。只有声明动画的元素才分配动画通道,省略声明即释放通道,移除元素时释放其状态。减少动态效果开启时直接到达目标。静止后不再请求帧;静止时只修改缓动配置也不会启动动画。

窗口持有的根可以在姿态动画期间只重绘已有元素树和布局。输入、状态变化、窗口缩放、待执行计时器或 Render 中读取 Context.Now 仍要求完整构建。姿态动画跟随显示帧,不套用循环指示器的 30 Hz 节奏。这减少符合条件帧的工作量,不代表已经证实总内存下降或端到端帧率提高。

AnimatePose 与 Translate、Opacity、Decorate 组合使用,不覆盖装饰回调。用户在 Decorate 内自行加入的变换仍有原有几何限制。姿态内文字使用矢量或原生绘制,不使用可选的数字图片图集,以保留缩放、旋转时的文字质量。

运行 go run ./examples/components -section motion_pose -lang zh-CN 可操作卡片和跟随浮层。本节描述当前开发分支,不属于 v0.4.2。进退场、布局过渡和拖拽能力见下文。

布局过渡

给带稳定 ID 的兄弟元素声明 .AnimateLayout(el.Snappy),即可平滑过渡重排和 尺寸变化。布局立即使用最终尺寸,绘制时将最终内容从先前的矩形缩放、移动到新位置。 文字和子元素会随矩形缩放,不会逐帧重新排版。可与 AnimatePose 组合,点击、 光标和锚定浮层使用同一个变换。支持有限的弹簧和补间,不接受循环布局动画。

位置相对于同一父元素,滚动不会触发布局过渡;换父元素意味着新身份。首次布局、 像素密度变化和零尺寸轴直接到达目标。省略声明或移除元素时释放状态。能否只重绘 仍取决于视图其余部分是否允许保留布局。这些代码位于工作分支,尚未包含在 v0.4.2 中。

跨父容器的共享元素

缩略图和详情图位于不同父容器时,用 .SharedLayout(identity, el.Snappy) 连接它们。两处使用相同的业务标识,每帧只声明其中一个:

type photoMatch struct{ ID int }
photo := el.Div().ID("thumbnail").Size(el.Dp(80))
if v.open {
    photo = el.Div().ID("detail").Size(el.Dp(240))
}
photo.SharedLayout(photoMatch{v.photoID}, el.Snappy)

新元素从旧元素已显示的位置、尺寸和旋转角度开始,包括父容器的嵌套变换。 旋转走短路径;中途改变弹簧目标会保留速度。内容随盒子缩放,点击区域、 输入光标和锚定浮层使用相同变换。Components 的 Motion 页面提供图片演示, 可以点击移动中的图片,让它反向返回。

标识限定在一个 Root 内,必须非 nil 且可比较。同一绘制帧出现重复标识会报错。 元素身份不变时,滚动直接带动元素,不启动新动画。首次出现、间隔一帧未显示、 窗口尺寸或像素密度变化,以及减少动态效果模式,都直接显示目标状态。 省略声明或移除元素后释放几何状态,不保留旧元素树。

不加 Fly 时,接口沿用目标父容器的裁剪、透明度和绘制顺序。加上 .Fly(), 衔接期间的元素会绘制在所在 Root 或所在浮层的其他内容上方,越过祖先容器的 裁剪和透明度;后面的浮层仍可遮住它。元素保留自身透明度和目标子树的主题, 点击区域与锚定浮层跟随可见位置。停止后回到目标父容器正常的绘制顺序和裁剪。 对话框中的子元素即使飞出面板范围,点击它也不会被误判为外部点击而关闭对话框。

photo.SharedLayout(photoMatch{v.photoID}, el.Snappy).Fly()

祖先处于 Inert 退场状态时,飞行中的子元素仍不可点击、不向辅助功能暴露, 并跟随祖先的退场淡出。动画继续到停止或声明被移除。绘制队列在当帧清空, 不会保存离场元素树。Fly 必须与 SharedLayout 一起使用。

共享元素切换时,纯色背景、边框色、文字色、边框宽度、圆角和自身透明度也会插值。 悬停、焦点和禁用样式仍立即覆盖这些基础样式。圆角与边框宽度按短边归一化; 宽高比变化时,圆角随盒子一起缩放。线性渐变会插值颜色和方向,按盒子归一化的 端点保持切换首帧的渐变;相反方向的渐变旋转过渡,不会在中点缩成一个点。 Elevation 阴影插值偏移、模糊和主题阴影颜色,新增或移除时从透明淡入或淡出。 自定义 Decorate 仍使用目标声明。

不同父容器中的文字需要在两个 Text 上同时声明 SharedLayout 和 ContentTransition,共享同一个匹配身份:

el.Text(title).TextSize(size).
    ContentTransition(el.ContentTransition{Morph: true, Animation: el.Snappy}).
    SharedLayout(titleMatch{id}, el.Snappy).Fly()

新文字从上一帧已显示的字形开始,支持不同宽高比和中途反向。相同整形簇移动到 新位置,字体轮廓变化时交叉淡入淡出。辅助功能只读取新文字;结束或移除后释放旧字形。 容器内的文字若不想逐个声明共享身份,可在共享容器上加 MatchText():

el.Div().SharedLayout(cardMatch{id}, el.Snappy).MatchText().Fly().Child(
    el.Text(title).ID("title"),
    el.Text(subtitle).ID("subtitle"),
)

标签按相对路径配对,优先用 ID,否则用兄弟位置;重排文字时应设置稳定 ID。 不会按字符串猜测配对,层级改变就是新路径。未声明 ContentTransition 的标签 自动使用 Morph;显式声明 SharedLayout 的子孙节点建立独立范围。 省略 MatchText 后释放自动匹配,包括缓存子节点上的自动声明。

AnimateLayout 处理同一父容器内的变化, SharedLayout 处理元素身份之间的衔接;两者都立即使用最终布局,动画期间缩放内容, 不会按每个中间尺寸重新折行。

进入、退出与列表生命周期

Context.Presence 按根视图内的键保存少量动画数值。每次 Render 都要声明, 逻辑状态变为 false 后仍然声明,直到退场完成:

p := cx.Presence("details", v.show, el.PresenceOptions{
    Enter: el.Pose{Y: 12, Fade: 1},
    Exit: el.Pose{Y: -12, Fade: 1},
    Animation: el.Snappy,
})
if p.Visible {
    body.Child(el.Div().ID("details").Presence(p).Child(el.Text("详情")))
}

element.Presence(p) 应用已经采样的姿态,并让退场子树进入 inert 状态: 保留外观,停止指针输入和键盘焦点,关闭它拥有的浮层,从自动化及平台辅助功能树 中移除。也可单独使用 Inert(true)。layer.Presence(p) 将同一生命周期应用于 浮层及遮罩。逻辑关闭时立即解除模态并恢复原焦点,余下的退场画面不再接收输入。 退场中重新打开会从当前姿态反向,弹簧保留速度;减少动态效果时立即完成。 首次出现也会播放进入动画。省略 presence 声明会取消生命周期,不会留下隐藏的树。

列表使用 el.PresentItems(cx, groupKey, items, id, options),返回包含退场项的 PresentItem[T]。每项含 Value、Key 和 Frame,用 element.Presence(item.Frame) 应用。组键和项键必须可比较且不重复,元素仍须 使用稳定 ID。返回的切片在下次调用时复用;退场期间保留原有顺序,其他时候跟随 源数据顺序。PresenceListOptions 内嵌 PresenceOptions,开启 ExitBeforeEnter 后,新项等到离开项退场完成再进入;重新加入的旧项直接反向。 空列表也要继续声明才能完成退场。省略整个组会释放保留的值,包括回调引用。 这两个 API 都不快照或保留元素树。

运动期间 presence 在 Render 中采样;静止后不再请求帧,也不会阻止其他动画复用 已经稳定的布局。这些 API 位于当前工作分支,尚未包含在 v0.4.2 中。

拖拽与松手动画

Div().Draggable(options) 沿父元素的坐标轴移动盒子,不改变布局。拖拽位移叠加在 位姿和布局过渡之外,点击区域、光标和锚定浮层随之移动。内部按钮、输入框和滚动区域 继续处理自己的输入。

card.Draggable(el.DragOptions{
    Axis: el.DragHorizontal,
    Bounds: &el.DragBounds{MaxX: 240},
    Snap: []el.DragPoint{{}, {X: 240}},
    Elastic: .4,
    Momentum: true,
    Animation: el.Snappy,
})

Bounds 限制以 dp 为单位的位移,不是元素矩形。Elastic 取 0–1:零会在拖动时 直接限制位置,正值允许越界后逐渐增加阻力。松手后,Momentum 根据实测速度预测 200ms 后的位置,再选择最近吸附点并限制最终目标。弹簧保留松手速度,补间遵循缓动 曲线。即使拖动阶段限制越界,弹簧回落时仍可能越过边界。没有惯性和吸附点时,元素 停在松手位置或最近边界。取消手势会返回本次拖动的起点。

Initial 设置初始位移;递增 Reset 会立即返回 Initial 并取消手势,单独改变 Initial 不会重置现有元素。OnMove 报告直接拖动,包括松手时的最后一次位置变化; OnRelease 在拖动结束或取消时报告回落目标。单击不会触发这两个回调。回落动画帧 不调用它们。不要与 OnDrag 或 DragAccept 同用;声明有效期间不要修改边界或 吸附点切片。

稳定 ID 保留位移,省略声明会释放拖拽状态。禁用元素或将子树设为 inert 会停止手势, 不触发回调。减少动态效果时仍可直接拖动,松手立即到达目标。满足条件的回落帧只重绘; 输入后的首个安静帧仍会重建视图。静止后不再请求帧。Components 的 Motion 页面可 直接操作。这些 API 位于工作分支,尚未包含在 v0.4.2 中。

弹簧回弹到达弹性边界时会停止向外的速度,最多超出边界 100*Elastic dp。快速松手也不会把元素甩出这段范围。

文字内容变化

Text(value).ContentTransition(options) 为字符串或颜色范围变化添加动画。默认淡入 淡出;Numeric 让单行中变化的字符滚动,Down 反转方向;Morph 将相同字符移动 到新位置,支持换行后的重排。Numeric 和 Morph 不能同时开启。

el.Text(fmt.Sprintf("%04d", count)).ID("count").TextSize(32).
    ContentTransition(el.ContentTransition{Numeric: true, Down: decreased, Animation: el.Snappy})
el.Text(title).ID("title").ContentTransition(el.ContentTransition{Morph: true})

塑形仍以完整字符串为单位,组合音标、连字、emoji 序列和从右向左书写的字符簇不会 被拆开,颜色范围也覆盖完整字符簇。多行或 RTL 内容的 Numeric 使用淡入淡出,不滚动。 Morph 先保持公共序列的顺序,再匹配其余相同字符;长文本使用线性空间匹配,避免 最长公共子序列矩阵无限增长。字体轮廓变化会在移动、缩放时交叉淡化,颜色按预乘透明度 混合。Shimmer 优先于内容过渡。

首次声明立即显示。之后的变化从当前画面的字形位置、颜色、透明度和裁剪范围接续, 中途再次改字也如此。旧文字只负责绘制,不接收输入,也不进入辅助功能树;布局和语义 使用当前字符串。普通 Text 仍不可选中,输入框和可选择文字组件保持原有行为。

动画可以复用已构建的树。静止时只保存当前文字声明,不缓存旧字形或路径。完成、省略 声明或离开可见区域后释放过渡字形,重新进入视口时直接显示当前文字。连续改字会保留旧字符原有的透明度时钟, 不会重新启动其退出动画,也不会给慢速弹簧另加时限。减少动态效果或像素密度 变化时直接到达目标;仅宽度或字体样式变化时直接跟随布局。这些 API 位于工作分支, 尚未包含在 v0.4.2 中。Components 的 Motion 页面提供计数器和文字重排演示。

cx.MeasureText(value, size, weight) 按当前主题和帧缩放测量无宽度限制的单行文本,返回 dp 宽高,复用布局测量缓存。可用于普通文本的溢出判断;自定义字体与继承样式需单独测量。

指针移动

OnPointerMove(func(x, y float32)) 观察指针进入和移动,坐标是包含元素变换的本地 dp。它不会拦截子元素的点击。禁用元素和模态浮层背后的元素不接收回调。适合实现距离感应效果,不轮询,也不报告元素外的移动。

AnimatedFloat 保存影响布局的数值动画。使用 Set 初始化,在 Render 中调用 Sample(cx, target, transition)。它使用帧时钟,改变目标时保留弹簧速度,遵循减少动态效果设置,稳定后停止请求帧。仅影响绘制的变换优先使用 AnimatePose。