Keel v0.5.1 English GitHub

Carousel

在线示例:这是真实的 Keel 程序编译成 WebAssembly,可以直接操作。首次加载约 10 MB。全屏打开
示例代码Go · 可复制

这是上方组件库展示案例的完整源码。examples/components/carousel.go

在脚手架项目中复用组件构造和 Render 写法;示例的 registerSection 与共享辅助函数由组件库提供。

package main

import (
	"time"

	"github.com/dyike/keel/ui/core"
	"github.com/dyike/keel/ui/el"
	"github.com/dyike/keel/ui/kit"
	"github.com/dyike/keel/ui/theme"
)

func init() {
	registerSection("carousel", "display", func() core.Widget {
		slide := func(title, body string) el.View {
			return el.ViewFunc(func(*el.Context) el.Element {
				return el.Div().ScrollY().P(24).Gap(8).Child(el.Text(title).TextSize(20).Bold(), el.Text(body).TextColor(theme.Muted))
			})
		}
		car := kit.Carousel(
			slide(demoText("Welcome to Keel", "欢迎使用 Keel"), demoText("Build desktop UIs in Go without HTML.", "用 Go 写桌面界面,不需要 HTML。")),
			slide(demoText("Components", "组件"), demoText("80+ kit components with dark mode and localization.", "80 多个 kit 组件,支持深色和多语言。")),
			slide(demoText("Agent testing", "Agent 测试"), demoText("keel-mcp lets agents interact with the UI like users.", "keel-mcp 让 Agent 像用户一样操作界面。")),
		).Autoplay(4*time.Second).Height(180).Loop(false).Basis(2.0/3).ItemBasis(1, 0.5).ItemSize(0, 260).ItemSize(2, 640)
		content := car.Content()
		previous := car.PreviousControl(kit.Button(demoText("Previous item", "上一项"), nil).Variant(kit.ButtonSecondary))
		next := car.NextControl(kit.Button(demoText("Next item", "下一项"), nil).Variant(kit.ButtonSecondary))
		pages := []el.View{car.PaginationItem(0, nil), car.PaginationItem(1, nil), car.PaginationItem(2, nil)}
		disabled := false
		vertical := false
		wheelStep := false
		return el.Root(el.ViewFunc(func(cx *el.Context) el.Element {
			car.Height(180 * max(float32(1), cx.TextScale()))
			return el.Div().ScrollY().P(24).Gap(12).Items(el.Start).Child(el.Div().W(el.Dp(480)).MaxW(el.Full).Gap(theme.SpaceMd).Child(content.Render(cx), el.Div().Row().Wrap().Items(el.Center).Gap(theme.SpaceSm).Child(previous.Render(cx), pages[0].Render(cx), pages[1].Render(cx), pages[2].Render(cx), next.Render(cx))), kit.Button(demoText("Toggle horizontal / vertical", "切换横向 / 竖向"), func() { vertical = !vertical; car.Vertical(vertical) }).Variant(kit.ButtonSecondary).Render(cx), kit.Button(demoText("Toggle continuous / item scrolling", "切换连续 / 逐项滚动"), func() { wheelStep = !wheelStep; car.WheelStep(wheelStep) }).Variant(kit.ButtonSecondary).Render(cx), kit.Button(demoText("Enable / disable carousel", "启用 / 禁用轮播"), func() { disabled = !disabled; car.SetDisabled(disabled) }).Variant(kit.ButtonSecondary).Render(cx))
		}))
	})
}

轮播:一次显示一张,带上一张、下一张按钮和指示点。

car := kit.Carousel(slide1, slide2, slide3).Height(200).Autoplay(4 * time.Second)
  • 点击按钮或指示点切换;轮播获得焦点后,横向用 ← →、竖向用 ↑ ↓ 切换,默认首尾循环;Home/End 选择第一张/最后一张。
  • Autoplay(d) 每隔 d 切到下一张。指针悬停在轮播上时暂停;开启减少动画时不自动播放。
  • SetDisabled(true) 禁止按钮、指示点和按键切换,同时停止自动播放并移除焦点;父容器禁用、内容离开视口或被模态层遮挡时也暂停自动播放,恢复后重新计时。
  • Value() / SetValue(i)(不触发回调),OnChange(fn)。
  • "上一张""下一张"的名称来自 locale。

Agent:容器角色 group,名字是"当前/总数"(如 2/3);按钮名为"上一张""下一张",指示点的名字是序号。

验证:go run ./examples/components -section carousel,加 -theme dark 检查深色。

Vertical(true) 把导航放到内容右侧:上箭头、纵向指示点和下箭头。Vertical(false) 恢复内容下方的水平导航。Height 仍控制内容高度(默认 200dp),导航至少保留 72dp;非正或非有限高度忽略。指示点区域可竖向滚动,以容纳较多项目。切换方向保留当前索引及已有键盘焦点,不触发 OnChange;自动播放、悬停暂停、禁用和减少动画规则保持不变。

默认是单项切换,ItemsPerView 可开启等尺寸多项视口;已支持指针拖动吸附,连续滚动在停顿后吸附,见下文。前后控件和分页项可独立组合,见下文。

Loop(false) 关闭循环:到第一项时禁用上一项,到最后一项时禁用下一项,键盘越界保持原选择。Loop(true) 恢复默认循环;切换模式不改变索引,也不触发 OnChange。空列表和单项列表的前后按钮始终禁用,空列表的 Agent 计数为 0/0。

Previous() / Next() 与内置按钮共用导航逻辑,只在索引实际变化时调用 OnChange,并遵守自身禁用状态。CanPrevious() / CanNext() 返回结合列表数量、循环模式、边界和自身禁用状态的可用性。它们不读取父容器继承的禁用状态;外部控件应放在相同的禁用容器中,或由应用另行禁用。SetValue 仍用于无回调的程序设置,即使禁用也可调用。

非循环自动播放到最后一项后停止;程序或用户返回前面的项后,从下一帧重新计时。其他悬停、减少动画和可见性暂停规则不变。

car.Loop(false)
previous := kit.Button("上一项", car.Previous)
previous.SetDisabled(!car.CanPrevious()) // 渲染前按当前状态更新

独立组合

保留返回的控件实例,在每帧渲染它们:

content := car.Content()
previous := car.PreviousControl(nil)
next := car.NextControl(kit.Button("下一项", nil).Variant(kit.ButtonSecondary).Size(40))
first := car.PaginationItem(0, nil)
second := car.PaginationItem(1, nil)
// 在自己的布局中分别调用 content/previous/next/first/second.Render(cx)。

Content() 只显示内容区,保留方向键、Home/End、焦点和自动播放。同一个 CarouselView 只挂载一次 Content 或完整 Carousel;独立控件可创建多份。传入 nil 时,前后控件按当前轴显示箭头,分页项显示从 1 开始的数字并突出当前页;分页索引从 0 开始,无效索引禁用。

传入 Button 时继承尺寸、文字、图标、富内容、名称、外观、加载和自身禁用配置。组件接管 ID 和点击回调,不执行原按钮回调,也不修改原实例。每帧读取配置,因此加载/禁用和外观可动态更新;自定义分页外观自行配置,选中状态仍以 toggle/selected 语义公开。点击当前页不重复回调,程序 SetValue 不触发回调。

轮播自身禁用会同步到所有关联控件;父容器禁用只沿实际布局树继承,组合时应把内容和控件放在同一禁用容器内。自动播放暂停检测范围仍是内容区,外部控件的悬停不自动暂停。控制按钮的 Space/Enter 执行操作;方向导航由内容区焦点处理。

同屏多项

ItemsPerView(2) 将当前轴分成两个等尺寸槽位;Gap(8) 设置项目间距(默认 SpaceMd)。横向按可用宽度分配,竖向按 Height 分配;窗口尺寸变化后重新测量。正整数生效,1 恢复原单项模式;间距只接受有限非负值,在极窄视口中会压缩。项目少于槽位数时保留空余空间。

按钮、分页、方向键、自动播放仍按一个项目移动。有限轨道中,选中项尽量对齐开头,末尾限制偏移以填满视口,因此最后几项可能共享同一个偏移;Value 和回调仍区分每个索引。循环轨道中每项有独立吸附点,末项后接首项。SetValue 在禁用时仍可更新显示。

默认所有项目使用稳定的轨道身份,超出视口的内容被裁剪,不做虚拟化。轨道偏移由选择或指针拖动控制;连续滚动可在停顿后同步选中。

分数比例与混合尺寸

Basis(2.0/3) 让每个槽位约占视口的三分之二,露出后面项目的一部分;ItemBasis(1, 0.5) 将第二项单独设为半个视口。比例范围为 (0,1],比例不超过视口,超视口项目可用 ItemSize;0 清除对应覆盖,非法比例或索引忽略。横向比例对应宽度,竖向对应高度。

car.Basis(2.0/3).ItemBasis(1, 0.5).Gap(8)
car.ItemBasis(1, 0) // 恢复默认比例
car.ItemsPerView(2) // 清除全局 Basis,逐项覆盖仍保留

比例包含间距份额:项目主轴尺寸为 (视口尺寸 + 间距) × 比例 − 间距;例如 240dp 视口、8dp 间距、1/2 比例得到 116dp 项目。有效间距按最小比例收敛以适应窄视口。导航按每项及间距实际舍入后的像素尺寸累加,不假定项目等宽/等高;末端偏移仍受视口边界限制。

调整比例不改变当前索引、不触发 OnChange;轨道模式内部保留输入状态与焦点。关闭 Draggable 和 Scrollable、清除所有逐项覆盖且 ItemsPerView 为 1、Basis 为 0 时恢复旧单项模式,会重建项目层级。固定 dp 尺寸通过 ItemSize 配置。

固定尺寸项目

ItemSize(index, dp) 为指定项目设置主轴尺寸,不包含间距。横向对应宽度,竖向对应高度;窗口缩放或方向切换时 dp 数值保持不变。固定尺寸优先于 ItemBasis 和全局比例,ItemSize(index, 0) 清除固定值并恢复原比例。无效索引、负数及非有限值忽略;修改不改变选择,也不触发 OnChange。

car.Basis(0.5).ItemSize(0, 180).ItemSize(2, 640)
car.ItemSize(0, 0) // 恢复半个视口

固定尺寸可以超过视口。选中超大项目时显示它的开头,其余部分被裁剪;导航到下一项时按超大项目的完整尺寸加间距计算偏移。此批没有增加项目内部的自由滚动,超大内容需要应用自己提供内层滚动容器;连续滚动在停顿后吸附,见下文。关闭 Draggable 和 Scrollable、清除所有逐项比例/固定尺寸且 ItemsPerView 为 1、Basis 为 0 时,才恢复旧单项模式。

指针拖动吸附

Draggable(true) 默认开启。可从内容区的非交互区域开始鼠标或触摸拖动;滑块、输入框、可点击子项和内嵌 Widget 的操作区域留给子组件。沿当前轴移动至少 4dp 后,轨道跟随指针,释放时选择距离最近的吸附点。在有限轨道首尾向外开始拖动,或初始方向更接近另一轴时,轮播取消自身拖动并允许外层接管;已经沿轮播轴接管的拖动会保留到释放,不在中途到达边界时转交。循环轨道沿轴拖动仍由轮播接管。移动期间不改变 Value,也不调用 OnChange;释放后索引实际变化才回调一次。重合吸附点优先保留当前项,否则选第一个最近项。吸附使用 180ms 过渡,没有速度惯性;开启减少动画时立即完成。

取消拖动、程序 SetValue、改变轴/尺寸配置或禁用会恢复当前选中的定位,不提交旧拖动。拖动期间暂停自动播放,结束后重新计时。Draggable(false) 禁用拖动;仍可使用按钮、分页和键盘。子按钮、输入框及其他交互控件优先处理自己的事件,不从这些控件上启动轮播拖动。

有限轨道(Loop(false),或轨道不够长、无法循环)拖到首尾会限制偏移;循环轨道可以拖过首尾,条件见下文“循环轨道”。滚动事件的边界路由见下文。

滚轮与连续滚动

Scrollable(true) 默认开启。水平轮播接收水平滚动,竖向轮播接收竖向滚动,另一轴交给外层。连续位移实时更新轨道,手势结束后选择最近吸附点,索引实际变化才触发一次回调。滚动期间暂停自动播放,结束后重新计时。程序切换、配置改变或禁用取消旧滚动,不允许其延迟回调覆盖新选择。

手势结束和设备由平台判断(core.CurrentScrollGesture):

  • macOS:Keel 在 Gio 之前读取原生滚动事件。触控板在手指抬起时立即吸附,手指停住不动时不会提前吸附,抬起后的系统惯性被忽略。鼠标滚轮沿轮播方向每格切换一项。
  • Linux Wayland:Keel 在窗口自己的连接上另开一个指针对象,读取滚动来源(滚轮/手指)和手指抬起事件,行为与 macOS 相同;Wayland 不发系统惯性,所以没有惯性需要忽略。合成器的 wl_seat 低于版本 5 时拿不到这些信息,退回下一条。这一部分只在 macOS 上用真实头文件做了编译检查,尚未在 Wayland 桌面运行。
  • Windows、X11 等其他平台:系统的滚轮消息不带设备和手势阶段,连续 140ms 没有新事件就视为结束。

WheelStep(true) 对任何设备都按事件逐项切换,水平轮播也接收竖向滚动;不开时,只有检测到鼠标滚轮才逐项切换,并且只响应轮播自身方向,不抢外层页面的竖向滚动。

有限轨道的连续模式从首尾向外开始滚动时把事件交给外层;已在内部开始的滚动保留到停顿,防止到达边界时外层突然移动。逐项模式沿用 Loop;非循环边界交给外层,循环时在首尾换页。交互子项里的滚动容器优先接收自己的滚动。Scrollable(false) 关闭这一路输入,不关闭指针拖动。

Loop(true) 在轨道足够长时允许拖动和连续滚动跨越首尾。每个项目只挂载一次,按当前位置移动原项目到相邻周期;输入状态、点击区域和浮层锚点随项目保留。循环条件为“包含末尾间距的周期长度 − 最大项目长度 ≥ 视口长度”,否则退回有限轨道,导航仍按索引循环。这个限制避免同一个交互项目必须同时出现在视口两端。改变 Loop、方向或尺寸配置会取消当前手势。

从滚动中开始拖动时接续当前显示偏移。原生触控板手感、系统惯性与不同设备的事件合并仍需真机验收。

切换与吸附动画

按钮、分页、键盘及自动播放使用 180ms 缓出过渡;Value 和 OnChange 在选择变化时立即更新,不等待动画结束。循环轨道的下一项始终向前、上一项始终向后,越过首尾后重置到等价的轨道坐标,不闪回另一端。

拖动释放、取消或滚动停顿后,从当前偏移过渡到吸附点;回到原索引也会吸附,但不重复回调。动画期间再次导航,从最后显示的位置开始新过渡;开始拖动或连续滚动则立即接管该位置。

首次显示、SetValue(包括重复设置同一值)、尺寸或方向变化、禁用和减少动画均直接定位到选中项。关闭拖动和滚动仍保留导航动画。