主题
ui/theme 管颜色、尺寸刻度和字体。组件每次 Render 都从 theme 读取,所以切换主题后所有窗口下一帧就换成新样子,不用重建视图。
切换主题
theme.Use("nord") // 按名字应用已注册的主题,并记住名字
theme.CurrentName() // "nord"
theme.Names() // 已注册的全部名字,可以直接给主题选择框用
theme.Apply(myPalette) // 应用一个没有名字的调色板
Use 和 Apply 要在打开窗口前调用,或者在界面回调里调用(持有帧锁)。其他 goroutine 用 core.Update(func() { theme.Use("dark") })。
内置主题:light、dark、nord、paper、solarized-dark、high-contrast,以及带渐变的 aurora。
调色板与缓存
组件默认使用柔和的半透明 Palette.Outline 作为轻描边,保证卡片、输入框与浮层在任意主题和嵌套底色下都有清晰边界;Border 用于对比度稍高的分隔线和显式边框。如需关闭默认外框,可将 p.Outline = color.NRGBA{} 后应用主题,或用 cx.Themed(p, view) 只作用于局部。组件的 Bordered(true)、Outline 外观以及样式回调中的 .Border(1, theme.Border) 仍可显式覆盖。输入框在 Outline 可见时用 Primary 描边提示键盘焦点;将 Outline 设为透明后自动回退为浅底色提示。校验错误保留状态提示。
设置 Palette.Frameless 可去掉元素外框,包括焦点边框。键盘和输入框焦点改用背景填充,单边分隔线保留。该选项默认关闭,并随局部调色板生效。
Light()、Dark()、Current() 返回调色板副本。自定义时修改副本,再用 Apply 替换全部颜色;零值字段也会应用。
p := theme.Light()
p.Primary = theme.RGB(0x15803d)
theme.Apply(p)
Apply 递增 theme.Revision(),使 cx.Cache 失效并请求重绘。自己的渲染缓存也要把版本号纳入键。颜色应在 Render 时读取;已经构造好的静态元素、自定义固定色和 Markdown 独立配色需要应用自行更新。直接修改包级颜色变量不会同步 Material、刷新缓存或请求重绘。
| 颜色 | 浅色默认值 | 用在哪里 |
|---|---|---|
Bg |
#f5f6f8 |
窗口背景 |
Surface |
#ffffff |
卡片、输入框底色 |
Outline |
#0f172a17 |
柔和的默认组件外框 |
Border |
#0f172a1f |
显式边框、分隔线 |
Text / Muted |
#1f2328 / #6b7280 |
正文 / 次要文字、占位文字 |
Primary / PrimaryHover / PrimaryText |
#2563eb / #1d4ed8 / #1d4ed8 |
主按钮、焦点边框 / 悬停 / 链接等蓝色文字 |
Danger / DangerHover / DangerText |
#dc2626 / #b91c1c / #b91c1c |
危险按钮 / 悬停 / 错误文字 |
Success / Warning / Info |
#15803d / #a16207 / #0369a1 |
状态正文、图标 |
Subtle / SubtleHover |
#eceef1 / #e2e5e9 |
次要按钮、悬停底色 |
OnColor |
#ffffff |
实心主色、危险色背景上的文字 |
Highlight |
#dbeafe |
选中行、选中项 |
Scrim |
40% 黑 | 模态浮层后面的遮罩 |
CodeBg / CodeText |
#f0f1f3 / #1f2328 |
代码块 |
Chart |
8 个分类色 | 图表系列颜色,按顺序使用;浅色和深色各一套,均通过色觉缺陷校验 |
OnColor 用于 Primary / Danger 实心背景,不保证适合所有状态色背景。成功、警告和提示颜色可以用于正文和图标。
主题文件
主题文件是 JSON:选一个基础主题,只写要改的颜色。颜色名就是 Palette 的字段名,不区分大小写,值可以写成 #rgb、#rgba、#rrggbb 或 #rrggbbaa。
{
"name": "forest",
"base": "light",
"colors": {
"bg": "#e8f3ea",
"primary": "#2f7d4a",
"primaryHover": "#26693d",
"chart": ["#2f7d4a", "#c2410c"]
}
}
name, palette, err := theme.ParseTheme(data)
theme.Register(name, palette)
chart 最多 8 个颜色,没写的沿用基础主题。写错颜色名或颜色值时 ParseTheme 返回错误。
渐变
bgGradient 给窗口背景,primaryGradient 给主按钮、进度条和用户的聊天气泡:
"bgGradient": {"from": "#10142b", "to": "#1f1843", "angle": 120},
"primaryGradient": {"from": "#7c5cff", "to": "#2fb8ff", "angle": 0}
angle 的单位是度:0 从左到右,90 从上到下。主按钮悬停和按下时整体压暗,渐变不消失。
渐变只是外观,Bg 和 Primary 仍然是这两处的纯色,选中边框、焦点框、链接等其他地方都用纯色。所以要把 bg、primary 设成渐变里的某个颜色,看起来才协调。没设渐变(零值)时完全不影响原来的纯色。
自己画的元素也能用:el.Div().BgGradient(theme.Gradient{From: a, To: b, Angle: 90})。传零值什么都不改,所以可以直接传 theme.PrimaryGradient,没配渐变的主题下它就是纯色。之后再调 Bg 会替换掉渐变。
监听主题目录
设计师改主题文件时,不用重启程序就能看到效果:
w, err := theme.WatchThemes("./themes", time.Second, func(names []string, err error) {
if err != nil {
log.Print(err) // 某个文件写错了;其他文件照常加载
}
})
defer w.Stop()
theme.Use("forest")
- 启动时立刻注册目录里所有的
*.json,所以紧接着就能Use它们。 - 之后按间隔检查文件的修改时间。有变化的文件在下一帧(持有帧锁时)重新注册;正在使用的主题(
CurrentName)变了,会立刻重新应用。 - 用轮询而不是文件系统事件,不需要额外依赖,各平台行为一致。
- 删掉文件不会注销已注册的主题。
- 组件库示例可以这样试:
go run ./examples/components -themes ./mythemes -theme forest。
尺寸刻度
组件从刻度里取值,不自己写数字,同一种用途在各处看起来一样,要改设计也只改一处。
| 刻度 | 常量 |
|---|---|
| 间距(dp) | SpaceXxs 2、SpaceXs 4、SpaceSm 6、SpaceMd 8、SpaceLg 12、SpaceXl 16、Space2xl 24、Space3xl 32 |
| 圆角(dp) | RadiusSm 4、RadiusMd 6、RadiusLg 8、RadiusXl 12、RadiusFull |
| 字号(sp) | TextXs 11、TextSm 12、TextMd 13、TextControl 14、TextBody 15、TextLg 17、TextXl 20、TextHeading 22 |
| 阴影 | ElevationSm、ElevationMd、ElevationLg,颜色是 theme.Shadow |
间距的用法:图标和文字之间用 SpaceSm,一行里的控件之间用 SpaceMd,控件内边距和表单字段之间用 SpaceLg,卡片内边距用 SpaceXl,对话框和页面内边距用 Space2xl。
el.Div().Row().Gap(theme.SpaceMd).P(theme.SpaceXl).Rounded(theme.RadiusLg)
kit 的间距都已改用这套刻度;剩下的 10、14、20dp 是刻意的视觉微调,比如让输入框文字和按钮文字对齐。
局部主题
一个窗口里的某一块想换颜色(比如浅色窗口里的深色侧栏),用 cx.Themed,见元素与视图 · 局部主题。
自己写 Gio 绘制代码时,可以用 theme.Scope(p) 临时替换调色板,调用返回的函数恢复;Scope 不触发重绘或改变版本号。局部主题不会自动跟随系统外观。
字体
theme.Face 指定正文的字体优先级,逐字形回退;theme.MonoFace 指定等宽字体优先级。桌面版优先使用系统字体,兜底字体只在系统没有对应字体时使用。
MonoFace 优先尝试等宽字体,缺失的中文等字形复用完整的 Face 回退列表,终端中文因此和正文使用同一款中文字体,不会落到 Arial Unicode MS 等任意汉字回退字体;拉丁文字保留等宽字体。在 macOS 上,Keel 的 go-text 副本还会索引系统字体资源目录(/System/Library/AssetsV2),苹方就在其中;使用上游 go-text 时中文回退到冬青黑(Hiragino Sans GB)。
theme.LoadFonts(data...) 接收 TTF、OTF、TTC 文件的字节内容,加载后重绘所有窗口。浏览器通过 theme.FetchFonts("font.ttf") 下载并加载;中文字体准备见 在浏览器里运行。
BodySize / SmallSize / HeadingSize 分别为 15 / 13 / 22sp,标准单行字段高 ControlHeight(36dp)。直接使用 Gio 绘制时可复用 theme.Material 的字形排版器。
平台文字渲染(macOS)
使用 Keel 的 Gio 和 go-text 副本时(见 third_party/README.zh-CN.md),macOS 上纯色文字由 CoreText 绘制,与原生应用和 WebKit 一致:同样的抗锯齿、笔画加粗和 gamma。此前 Gio 的矢量轮廓在线性光空间混合,看起来偏细、发灰。字形排版、布局和度量仍由 Gio 负责,只改变字形像素。标签、输入框、富文本区间、Markdown、代码编辑器、闪光文字和 GlyphRenderer 都会使用它。CoreText 画不了的文字(内存中构建的字体、彩色表情、超过 160 px 的字号)仍用矢量轮廓。字形缓存最多 128 页 256×256(32 MiB)。路径裁剪或透明度图层需要独立着色纹理时,小页面将每份颜色副本限制在 256 KiB。
自定义绘制可用 theme.PaintGlyphs(ops, shaper, glyphs, color, origin) 以同样方式绘制一行已排版的字形;theme.PlatformText(shaper) 报告某个排版器是否使用它。theme.UsePlatformText(false) 或环境变量 KEEL_TEXT=vector 可切回矢量轮廓做对比。使用上游 Gio 时没有这些挂钩,文字保持矢量轮廓。
系统减少动画
macOS 运行 window.Main() 后默认跟随系统“减少动态效果”,包括运行时变化。应用可以覆盖或恢复这个偏好:
theme.SetReducedMotion(true) // 显式关闭动画
theme.FollowSystemMotion() // 恢复跟随最近的系统值
在 UI 回调或 core.Update 内调用。自动化模式使用显式覆盖,保持截图稳定;其他平台默认允许动画,应用仍可关闭。
字形图片缓存
自定义终端绘制器可以按需启用 theme.GlyphAtlas。每帧先调用 BeginFrame(shaper),为所有文字段调用 Prepare(params, glyphs, color),再调用 Commit() 和 Paint(ops, params, glyphs, color)。只准备当前帧,不预计算后续画面。发生变化的页面每帧生成一个不可变的 ImageOp;绘制器关闭时调用 Release()。
调用方应使用整数像素平移,字号已换算为物理像素,并且不额外缩放或旋转。其他变换使用 GlyphPainter。复杂文字段、半透明颜色、GPU 不可用或缓存超限时回退到矢量绘制;彩色位图字形保留 Gio 的位图绘制。
页面上限为八张 512×512 RGBA 图片(8 MiB),掩码上限为 2 MiB、4096 个条目,每个掩码最多缓存八种颜色。旧页面快照和 GPU 副本还会占用额外内存;Stats() 提供当前 CPU 缓存占用、绘制次数和成功的掩码批次数。新掩码每批最多 64 个,在 512×512 临时画布的独立 64×64 区域内生成,共用一次 GPU 提交和读回;临时 RGBA 读回缓冲在释放前额外占用 1 MiB。第一帧同步准备所需掩码;后续每帧最多准备 32 个新掩码,首帧生成完成后释放临时 GPU 和读回缓冲;后续字形重建临时资源后,连续 60 帧没有新掩码再释放。静止的自定义绘制器也可在 Commit() 后串行调用 ReleaseScratch();已缓存的掩码和图片页保留,新字形会按需重建临时资源。SubpixelPhases 是可选的位置取整,与 GlyphPainter 有相同的文字质量取舍。
自定义字形绘制入口
GlyphRenderer 统一管理现有图集和矢量缓存。每个视图保留一个实例;文字排版并确定字形位置后,在准备和绘制阶段使用同一份 GlyphRun:
renderer.BeginFrame(shaper)
run := theme.GlyphRun{Params: params, Glyphs: glyphs, Color: color, Position: baseline}
renderer.Prepare(run) // 先准备所有可见文字段,再 Commit
renderer.Commit()
renderer.Paint(ops, run)
Position 是物理像素单位的基线原点。水平小数位置按四种像素相位写入掩码,垂直小数位置以 1/64 像素精度按相位缓存,避免平移图片时再次插值,边缘可能比旧矢量覆盖纹理的小数平移更清晰。复杂文字、半透明颜色、GPU 不可用和预算耗尽时沿用已有回退。排版、裁剪和语义文字由调用方负责;额外缩放或旋转应直接使用 GlyphPainter。字形切片必须保留到绘制结束。
自定义绘制器按需分配最多 32 张图片页(32 MiB),每个掩码最多缓存 32 种颜色,掩码仍受 2 MiB、4096 条目限制;独立 GlyphAtlas 保留八页、八种颜色的默认预算。待生成的掩码按垂直相位分批提交;相位改变时重建临时 GPU 覆盖缓存,避免 Gio 在不同小数平移之间错误复用覆盖。
视图关闭或替换时调用 Release();空闲时可以在 Commit() 后调用 ReleaseScratch(),释放临时栅格化资源。字体变化会自动清理两套缓存。Stats() 提供图集预算和绘制计数;BenchmarkGlyphRendererScrolling 对比变化的文字网格与整段矢量绘制,在 Keel 中复现下游性能回归。
CoreText 按所选 sfnt 字体的 PostScript 名称匹配,不按描述符数组下标取字体。可变字体会在该数组中展开为多个命名实例,因此 TTC 字体编号可能错指另一地区或字重。无法精确匹配时回退到轮廓绘制。系统字体扫描会收录其他轴保持默认值的命名字重实例。排版器应用对应的变体坐标,并把实例身份传给 CoreText,因此 Regular 请求可以选中苹方简体 Regular,而不是字体文件默认的 Medium。缺少精确 PostScript 身份的实例仍用轮廓绘制;此接口不支持任意变体轴选择。