指南、概念和参考,以及每个组件的页面和它的实时示例。
01开始
- 01.1介绍
amenui 是一个自己画每一个像素的界面框架,用 Rust 和 wgpu 写成,同一份代码跑在原生窗口和网页里。屏幕上的每一样东西——字形、形状、图片、三维的网格——都是一个带真实轮廓的实例,能按自己的轮廓松开、变形、再合上;它看起来怎样,是一种可以换的材质。
- 01.2安装
先选界面放在哪里。三种宿主画出来的像素一样:所有东西都由框架自己画,宿主只给它一块画面、输入和时间。
- 01.3第一个视图
视图是从状态到元素树的函数,更新是从状态和消息到新状态的函数。消息是普通的值。
- 01.4项目结构
amenui 仓库里各部分在哪。这个 crate 是一个库加几个命令行工具;这个网站、组件展示和实验室在另一个仓库 amenui-dev/website 里,它像普通应用一样依赖 amenui。
02指南
- 02.1表单
表单和别的一样,是状态和消息:状态里存着每一个值,每个控件每改一次发一条消息, update 是唯一改值的地方。文字字段在状态里存一个 TextEdit ;数字控件键入时发 Edit::Draft ,回车或步进时发 Edit::Set ,Esc 时发 Edit::Cancel ,所以状态把草稿和值分开存;开关和复选框发新的值。
- 02.2主题与深色模式
主题是一组颜色,加上显示、正文、等宽三种用途的字体( style::THEMES )。颜色在视图里写成名字而不是数值: Paint::INK 、 TEXT 、 DIM 、 FAINT 、 GROUND 、 ACCENT ,以及色相 Paint::hue(i) ,所以同一个视图在每个主题里都对。深色和浅色是同一个视图的两个主题:用顶栏的“主题”菜单、…
- 02.3多语言
屏幕上的每段文字都来自消息目录,一种语言一个,所以应用换成任何语言都不用改视图。
- 02.4从右到左
一行的方向是从右到左时,它从右边开始排:在这一行(或任何祖先)上写 El::rtl(true) ,或者用一种从右往左读的语言。布局由 taffy 的 Direction::Rtl 完成;文字由 parley 按各自的方向排版,所以一段里混排拉丁字母和从右到左的文字时,逻辑顺序不乱。
- 02.5无障碍
画面由框架自己画,而不是用系统控件,所以运行时为辅助技术另外维护一份看不见的界面副本:无障碍镜像。每次重建时它和画面从同一棵树生成,两者不会对不上。
- 02.6用 render 和树测试
每个示例都能不开窗口、从外部驱动: render 在离屏画布上打开它,在从 0 开始的固定 60 Hz 时钟上、用固定的随机种子播放一串输入事件,把最后一帧写成 PNG、把排好的树写成 JSON。同样的参数给出逐字节相同的结果,所以图和树都能在测试或评审里直接比较。
- 02.7性能
只在有变化时画;只画变了的部分(两个框);滚动只移动、不重新布局;长列表只造看得见的行;材质可以在一半分辨率上画松开的像素。
- 02.8开发
The architecture reference maps what each module owns. This guide covers building, testing and the tools in this repository.
配方
- 02.9子树上的标注层
- 02.10一章:一个场景,角色依次流入
- 02.11点阵图表
- 02.12带重组和局部涟漪的计数器
- 02.13对话框
- 02.14带共享部件的换页
- 02.15表单
- 02.16形体上的文字
- 02.17手势:底部面板和浮动框
- 02.18可选择的列表
- 02.19逐步载入的列表
- 02.20单个元素上的自定义材质
- 02.21卡片里的三维物体
- 02.22把 A 变形为 B
- 02.23自定义预设
- 02.24可扇形展开的卡片堆
- 02.25带子菜单和安全区的菜单
03概念
- 03.1概览
每个消息之后,运行时调一次 view(&state) ,得到一棵新的 El 树,按 key 和上一棵比较,只重算变了的布局。状态是唯一的来源;组件从不自己动。
- 03.2文字
文字由 parley 排版、swash 栅格化,图集里每个像素存覆盖率和到笔画的带符号距离,所以每种材质都按字的真实轮廓画它。段落可以绕开任意形状排( .around )。滚动时字按整设备像素移动,不会重新取样。
- 03.3材质与松开
材质是第二遍的画法:plain、dottr、halftonr、charr、smudgr、carvr、glitchr、near、scribblr。静止时它们和 plain 一样(除了自己有静止样子的几种);松开时各有各的样子。 El::material(id) 给一棵子树另一种材质。快速滚动时每种材质留下自己的痕迹(见 DESIGN §1.8.3 )。
- 03.4标注
第三遍是标注层:按真实的排版结果画框、编号、尺寸、引线、刻度尺,从不松开。 El::annotate(text) 写一条说明, {xy} 换成元素中心的坐标。
设计
- 03.5设计
- 03.61. 管线
- 03.71.2 布局
- 03.81.3 场景(
scene.rs) - 03.91.4 两个 G-buffer 目标
- 03.101.5 波场
- 03.111.6 材质
- 03.121.6.1 图像如何变成记号
- 03.131.6.2 各种材质
- 03.141.6.3 像素字
- 03.151.6.4 以源码提供的材质
- 03.161.6.5 Faces that come later
- 03.171.6.6 Glyph outlines, between letters
- 03.181.7 标注层
- 03.191.8 输入
- 03.201.8.1 文字输入
- 03.211.8.2 指针、触摸和滚轮
- 03.221.8.3 滚动的外观
- 03.231.8.4 手势物理(
src/gesture.rs) - 03.241.8.5 嵌套菜单和安全区
- 03.251.9 平台
- 03.261.10 变换
- 03.271.11 只在有变化时绘制
- 03.281.12 帧时间读数和分辨率预算
- 03.291.13 增量更新和长列表
- 03.301.14 无障碍镜像
- 03.311.15 涟漪规则
- 03.321.16 重组
- 03.331.17 面向模型的接口
- 03.341.18 三维
- 03.351.19 只绘制变化的部分
- 03.361.20 语言
- 03.371.21 收尾处理:后期效果、抖动和调色板
- 03.381.22 自行运动的记号:脱落和流场
- 03.391.23 载入时的外观
- 03.401.24 卡片堆
- 03.411.25 点阵图表
- 03.421.26 场、绘图和字形姿态
- 03.431.27 记号的帧预算
- 03.441.28 解码过渡
- 03.451.29 场图和轨迹
- 03.461.30 线材质
scribblr和长路径 - 03.471.31 检查
- 03.481.32 The beat
- 03.491.33 Plates
- 03.501.34 Effects that can be turned off
- 03.511.35 The stage
- 03.521.36 Drawn once: cached subtrees and round clips
- 03.533. 组件
- 03.544. 风格 = 主题 × 材质 × 材质参数 × 标注 × 字体
- 03.555. 展厅
- 03.566. 场景
- 03.577. 已完成的部分和验收
- 03.588. 布局
- 03.599. 实现与设计的差异
04组件
- 输入
- 04.1按钮
- 04.2数字
- 04.3输入框
- 04.4开关
- 04.5滑块
- 04.6选项
- 04.7复选框
- 04.8单选组
- 04.9选择框
- 04.10切换按钮
- 展示
- 04.11图片
- 04.12三维视图
- 04.13徽标
- 04.14头像
- 04.15骨架
- 04.16公式注
- 04.17卡片叠
- 反馈
- 04.18对话框
- 04.19提示
- 04.20浮层
- 04.21通知
- 04.22进度
- 04.23抽屉
- 04.24底部面板
- 导航
- 04.25标签页
- 04.26菜单
- 04.27面包屑
- 04.28跳到正文
- 04.29分页
- 04.30右键菜单
- 04.31命令面板
- 04.32多级菜单
- 布局
- 04.33卡片
- 04.34分隔线
- 04.35滚动区
- 04.36折叠面板
- 04.37浮动窗口
- 数据
- 04.38列表
- 04.39表格
- 04.40点阵图表
05参考
- 05.1命令行
组件像 shadcn/ui 那样以源码分发:把组件的文件拷进你的项目,在那里改。 amenui add 负责拷。
- 05.2注册表结构
registry.json 把每个组件列成可以拷贝的源码,和 shadcn/ui 的注册表一样。 amenui add 读它;文档里的组件页也由它生成。
- 05.3组件清单
组件以源码分发: amenui add <名字> 把一个组件和它依赖的文件拷进你的项目。
- 05.4
AGENTS.mdamenui is a self-drawn interface framework in Rust (wgpu; the same code runs natively and on the web). Everything on screen — glyphs, shapes, pictures — is an instance with a…
- 05.5
llms.txtA self-drawn interface framework in Rust (wgpu, native and web). Views are plain trees of values; every glyph, shape and picture has a true outline that can loosen, morph and…
- 05.6架构
amenui is one Cargo package: a library, the amenui command line and two tools. Everything except render.rs and the shaders runs without a GPU, so the runtime can be driven and…
- 05.7字体
The fonts in assets/ are all under the SIL Open Font License 1.1. Their licenses are in assets/licenses/ . text::embedded() returns them compiled into the binary (about 14 MB,…
06更新记录
- 06.1更新记录
Newest first. The acceptance checks for each part are in DESIGN.md §7 .