ZacharyZhang-NY/MujicaUI
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP components (as built)

Browse Source
This commit is contained in:
ZacharyZhang-NY committed 2026-10-05 15:51:57 -04:00
1 parent 299e5fe720
commit 4b8fdf8df7
71 files changed
+3241 -468
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/components/281-interrupt-button.md
+51
View File
@@ -0,0 +1,51 @@
# 281 InterruptButton 中断按钮
## 用途
中断正在运行的智能体：可选确认，中断进行中显示“正在停止”直到运行结束。
## 最小示例
```go
running, stopping := true, false
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
r := mujica.InterruptButton(c, running, mujica.InterruptButtonOptions{Confirm: true, Interrupting: stopping})
if r.Changed() {
stopping = true // cancel the run, then clear running and stopping
}
}
ui.Render(view, 400, 300, 1)
```
签名：`func InterruptButton(c *ui.Context, running bool, opts InterruptButtonOptions) ChoiceResult`
## 参数
`InterruptButtonOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Confirm | bool | false | 点击后先弹出确认，确认后才报告中断。 |
| Interrupting | bool | false | 中断进行中：按钮保留尺寸并显示加载；running 为 false 时设为 true 会 panic。 |
| Label | string | 内置“停止” | 按钮文字，也是确认按钮的文字。 |
`running` 为 false 时按钮禁用。
## 状态
- 危险按钮外观：DangerFill 底与 OnDanger 文字，图标为叉号。
- 中断中：显示加载标记与“正在停止”，不再响应点击。
- 确认弹层默认聚焦“继续运行”，Enter 不会误触中断。
## 事件
- `Changed()`：用户要求中断（需要确认时在确认后）。
## 键盘操作
- Tab 聚焦，Enter 或 Space 按下；确认弹层中 Tab 到“停止”再 Enter，Escape 取消。
## 限制
- 只报告中断请求，取消运行由调用方完成。
docs/components/282-token-usage-chart.md
+54
View File
@@ -0,0 +1,54 @@
# 282 TokenUsageChart Token 用量图
## 用途
按会话或步骤显示输入与输出 token 用量：默认堆叠柱状图，也可切换为折线。
## 最小示例
```go
usage := []mujica.TokenUsage{{Label: "Plan", Input: 1200, Output: 300}, {Label: "Write", Input: 2100, Output: 2900}}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.TokenUsageChart(c, usage, mujica.TokenUsageChartOptions{})
}
ui.Render(view, 400, 300, 1)
```
签名：`func TokenUsageChart(c *ui.Context, usage []TokenUsage, opts TokenUsageChartOptions) ChartResult`
## 参数
`TokenUsage`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Label | string | "" | 会话或步骤名，作为柱的类别。 |
| Input, Output | int | 0 | 输入、输出 token 数；为负 panic。 |
`TokenUsageChartOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Frame | ChartFrame | 零值 | 图表名称、高度、加载/失败/空状态；Label 为空时用内置“Token 用量”。 |
| Line | bool | false | 折线代替堆叠柱。 |
| Version | int | 0 | 原地修改数据时递增；新切片或长度变化自动刷新。 |
返回 `ChartResult`。序列在 usage 切片、长度或 Version 变化时重建。超过 256 项时，相邻项目汇总为最多 256 组，保留输入输出总数；柱类别显示首尾名称。
## 状态
- 输入、输出分色（取自图表调色板，对 Surface 至少 3:1），图例同时用形状区分。
- 加载、失败、无数据状态与图表同尺寸。
## 事件
- `Changed()`：读数移到另一个标记；`Toggled()`：图例开关某个序列。
## 键盘操作
- Tab 聚焦图表，←/→ 在柱或点之间移动，读数显示并朗读。
## 限制
- 折线模式的横轴为序号，类别名只在柱状模式显示。
docs/components/283-cost-breakdown.md
+60
View File
@@ -0,0 +1,60 @@
# 283 CostBreakdown 费用分解
## 用途
按模型、工具或步骤汇总调用次数、token 与费用，表格可排序，底部显示合计。
## 最小示例
```go
var state mujica.CostBreakdownState
items := []mujica.CostItem{
{Model: "opus", Tool: "search", InputTokens: 1000, OutputTokens: 200, Cost: 0.30},
{Model: "haiku", Tool: "search", InputTokens: 4000, OutputTokens: 500, Cost: 0.05},
}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.CostBreakdown(c, &state, items, mujica.CostBreakdownOptions{GroupBy: mujica.CostByModel}).Element.Height(260)
}
ui.Render(view, 400, 300, 1)
```
签名：`func CostBreakdown(c *ui.Context, s *CostBreakdownState, items []CostItem, opts CostBreakdownOptions) DataTableView`
## 参数
`CostItem`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Model, Tool, Step | string | "" | 分组依据；为空归入“（未命名）”。 |
| InputTokens, OutputTokens | int | 0 | token 数；为负 panic。 |
| Cost | float64 | 0 | 费用；为负或非有限值 panic。 |
`CostBreakdownOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| GroupBy | CostGroup | CostByModel | CostByModel、CostByTool、CostByStep。 |
| Currency | string | "$" | 金额前缀。 |
| Decimals | int | 0（即 2） | 金额小数位；为负 panic。 |
| Version | int | 0 | 原地修改数据时递增；新切片或长度变化自动刷新。 |
`CostBreakdownState.Table` 保存排序与选择。汇总只在 items 或分组方式变化时计算。给返回的 `Element` 一个高度。
## 状态
- 费用列含占比条与百分比，数字为等宽数字。
- 合计行为衬线“合计”、token 总数与加粗金额，朗读完整合计。
## 事件
- 同 DataTable：`Changed()`、`SortChanged()`。
## 键盘操作
- 同 DataTable：↑/↓ 选择行，列标题可用键盘排序。
## 限制
- 金额以浮点汇总并按小数位显示，不做货币舍入规则。
docs/components/284-trace-viewer.md
+64
View File
@@ -0,0 +1,64 @@
# 284 TraceViewer 调用链查看器
## 用途
以树显示调用链跨度，每行带耗时与时间轴条；选中跨度在下方查看属性。
## 最小示例
```go
var state mujica.TraceViewerState
spans := []mujica.TraceSpan{
{ID: "run", Name: "agent.run", End: 900 * time.Millisecond},
{ID: "plan", Parent: "run", Name: "llm.plan", Start: 10 * time.Millisecond, End: 210 * time.Millisecond,
Attrs: []mujica.TraceAttr{{Key: "model", Value: "opus"}}},
}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.TraceViewer(c, &state, spans, mujica.TraceViewerOptions{}).Element.Height(260)
}
ui.Render(view, 400, 300, 1)
```
签名：`func TraceViewer(c *ui.Context, s *TraceViewerState, spans []TraceSpan, opts TraceViewerOptions) DataTableView`
## 参数
`TraceSpan`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| ID | string | 必填 | 唯一标识；重复 panic。 |
| Parent | string | "" | 父跨度；不存在时作为根。 |
| Name | string | "" | 名称。 |
| Start, End | time.Duration | 0 | 相对调用链开始的偏移；需 0 ≤ Start ≤ End。 |
| Failed | bool | false | 失败。 |
| Attrs | []TraceAttr | nil | 属性键值。 |
`TraceViewerOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Status | DataStatus | DataReady | 加载、失败状态。 |
| Error | string | "" | 失败说明。 |
| Version | int | 0 | 原地修改数据时递增；新切片或长度变化自动刷新。 |
`TraceViewerState.Tree` 保存展开、排序与选择。索引只在 spans 变化时重建；父链成环时 panic。给返回的 `Element` 一个高度。
## 状态
- 时间轴条按整条调用链的跨度缩放，位置吸附像素。
- 失败跨度：叉号图标、Danger 文字与空心时间条，不只靠颜色。
- 属性面板显示开始、耗时与全部属性。
## 事件
- 同 TreeTable：`Changed()` 选择变化。
## 键盘操作
- ↑/↓ 选择，→ 展开，← 收起；输入名称开头字母跳转。
## 限制
- 只构建可见行（TreeTable 虚拟化）；属性面板也按可见行虚拟化，独立滚动。
docs/components/285-eval-result-table.md
+63
View File
@@ -0,0 +1,63 @@
# 285 EvalResultTable 评测结果表
## 用途
列出评测用例、得分与通过/失败，顶部显示通过数，每行可查看差异。
## 最小示例
```go
var state mujica.DataTableState[string]
cases := []mujica.EvalCase{{ID: "c1", Name: "Greets by title", Score: 0.98, Passed: true}, {ID: "c2", Name: "Refuses forgery", Score: 0.41}}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
r := mujica.EvalResultTable(c, &state, cases, mujica.EvalResultTableOptions{})
r.Table.Element.Height(260)
if id, ok := r.Diff(); ok {
_ = id // open expected and actual output side by side
}
}
ui.Render(view, 400, 300, 1)
```
签名：`func EvalResultTable(c *ui.Context, s *DataTableState[string], cases []EvalCase, opts EvalResultTableOptions) EvalResultTableResult`
## 参数
`EvalCase`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| ID | string | 必填 | 唯一标识。 |
| Name | string | "" | 用例名。 |
| Score | float64 | 0 | 得分；非有限值 panic。 |
| Passed | bool | false | 是否通过。 |
`EvalResultTableOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Decimals | int | 0（即 2） | 得分小数位；为负 panic。 |
| Status | DataStatus | DataReady | 加载、失败状态。 |
| Error | string | "" | 失败说明。 |
| Version | int | 0 | 原地修改数据时递增；新切片或长度变化自动刷新。 |
返回 `EvalResultTableResult`，含命名字段 `Element` 与 `Table`（DataTableView）。给 `Element` 一个高度。通过数与数据校验按数据版本缓存。
## 状态
- 结果列为图标加“通过/失败”文字与颜色。
- 顶部“通过 n / m”与比例条。
## 事件
- `Diff()`：要查看差异的用例 ID。
- `Table` 的 `Changed()`、`SortChanged()`。
## 键盘操作
- ↑/↓ 选择行；差异按钮用 Tab 到达，Enter 或 Space 触发。
## 限制
- 差异内容由调用方显示，例如用 DiffViewer。
docs/components/286-tool-registry-panel.md
+62
View File
@@ -0,0 +1,62 @@
# 286 ToolRegistryPanel 工具注册面板
## 用途
列出智能体可用的工具与启停开关，并预览所选工具的参数模式。
## 最小示例
```go
var state mujica.ListState[string]
tools := []mujica.AgentTool{{Name: "web_search", Description: "Search the web", Enabled: true,
Params: []mujica.ToolParam{{Name: "query", Type: "string", Required: true}}}}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
r := mujica.ToolRegistryPanel(c, &state, tools, mujica.ToolRegistryPanelOptions{})
r.Element.Height(260)
if name, on, ok := r.Toggled(); ok && name == tools[0].Name {
tools[0].Enabled = on
}
}
ui.Render(view, 400, 300, 1)
```
签名：`func ToolRegistryPanel(c *ui.Context, s *ListState[string], tools []AgentTool, opts ToolRegistryPanelOptions) ToolRegistryResult`
## 参数
`AgentTool`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Name | string | 必填 | 唯一名称；重复 panic。 |
| Description | string | "" | 说明。 |
| Enabled | bool | false | 是否启用，由调用方持有。 |
| Params | []ToolParam | nil | 参数：名称、类型、必填、说明。 |
`ToolRegistryPanelOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Disabled | bool | false | 禁用开关。 |
| Version | int | 0 | 原地修改数据时递增；新切片或长度变化自动刷新。 |
给返回的 `Element` 一个高度；`List.Changed()` 报告工具选择。名称索引按数据版本缓存，参数预览独立滚动，按可见行虚拟化。
## 状态
- 开关使用 Switch，名称为“启用 工具名”。
- 参数以等宽名称、Info 色类型与“必填”描边标签显示。
## 事件
- `Toggled()`：被切换的工具与新状态。
- 列表选择变化时右侧预览随之更新。
## 键盘操作
- 列表 ↑/↓ 选择工具；开关用 Tab 到达，Space 切换。
## 限制
- 参数只做平铺预览，不展开嵌套对象。
docs/components/287-dots-loader.md
+48
View File
@@ -0,0 +1,48 @@
# 287 DotsLoader 三点加载
## 用途
三个圆点依次变亮的加载标记，只在加载期间显示。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.DotsLoader(c, mujica.LoaderOptions{Label: "Thinking", ShowLabel: true})
}
ui.Render(view, 400, 300, 1)
```
签名：`func DotsLoader(c *ui.Context, opts LoaderOptions) *ui.Element`
## 参数
`LoaderOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Size | float32 | 0（即 16） | 标记高度；为负或无穷 panic。 |
| Label | string | 内置“加载中” | 朗读文字。 |
| ShowLabel | bool | false | 在标记旁显示文字。 |
| Color | ui.Color | AccentText | 标记颜色。 |
五个加载器共用 `LoaderOptions`。
## 状态
- 只在绘制时请求下一帧：不再构建或被隐藏后停止重绘。
- 减少动画：标记静止，并始终显示文字说明。
- 无弹跳、无发光。
## 事件
- 无。
## 键盘操作
- 无：不获取焦点，以进度角色朗读。
## 限制
- 无。
docs/components/288-bars-loader.md
+47
View File
@@ -0,0 +1,47 @@
# 288 BarsLoader 条形加载
## 用途
四根竖条依次升降的加载标记。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.BarsLoader(c, mujica.LoaderOptions{Size: 20, Label: "Indexing"})
}
ui.Render(view, 400, 300, 1)
```
签名：`func BarsLoader(c *ui.Context, opts LoaderOptions) *ui.Element`
## 参数
`LoaderOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Size | float32 | 0（即 16） | 标记高度。 |
| Label | string | 内置“加载中” | 朗读文字。 |
| ShowLabel | bool | false | 显示文字。 |
| Color | ui.Color | AccentText | 颜色。 |
见 DotsLoader。
## 状态
- 条高吸附像素；只在绘制时动画。
- 减少动画：静止并显示文字。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 无。
docs/components/289-pulse-loader.md
+47
View File
@@ -0,0 +1,47 @@
# 289 PulseLoader 呼吸加载
## 用途
单个圆点在 60% 到 100% 之间缓慢呼吸的加载标记，强度受限，不发光。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.PulseLoader(c, mujica.LoaderOptions{Label: "Listening", ShowLabel: true})
}
ui.Render(view, 400, 300, 1)
```
签名：`func PulseLoader(c *ui.Context, opts LoaderOptions) *ui.Element`
## 参数
`LoaderOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Size | float32 | 0（即 16） | 标记高度。 |
| Label | string | 内置“加载中” | 朗读文字。 |
| ShowLabel | bool | false | 显示文字。 |
| Color | ui.Color | AccentText | 颜色。 |
见 DotsLoader。
## 状态
- 透明度 0.55–1、尺寸 0.6–1，无光晕。
- 减少动画：静止并显示文字。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 无。
docs/components/290-orbit-loader.md
+47
View File
@@ -0,0 +1,47 @@
# 290 OrbitLoader 环绕加载
## 用途
一枚菱形沿一圈小菱形环绕，与 Spinner 同一视觉语言。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.OrbitLoader(c, mujica.LoaderOptions{Size: 24, Label: "Connecting"})
}
ui.Render(view, 400, 300, 1)
```
签名：`func OrbitLoader(c *ui.Context, opts LoaderOptions) *ui.Element`
## 参数
`LoaderOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Size | float32 | 0（即 16） | 标记高度。 |
| Label | string | 内置“加载中” | 朗读文字。 |
| ShowLabel | bool | false | 显示文字。 |
| Color | ui.Color | AccentText | 颜色。 |
见 DotsLoader。
## 状态
- 移动的菱形坐标吸附像素。
- 减少动画：菱形停在顶端并显示文字。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 无。
docs/components/291-wave-loader.md
+47
View File
@@ -0,0 +1,47 @@
# 291 WaveLoader 波形加载
## 用途
一条向右流动的正弦线加载标记。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.WaveLoader(c, mujica.LoaderOptions{Label: "Speaking", ShowLabel: true})
}
ui.Render(view, 400, 300, 1)
```
签名：`func WaveLoader(c *ui.Context, opts LoaderOptions) *ui.Element`
## 参数
`LoaderOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Size | float32 | 0（即 16） | 标记高度，宽为 2.5 倍。 |
| Label | string | 内置“加载中” | 朗读文字。 |
| ShowLabel | bool | false | 显示文字。 |
| Color | ui.Color | AccentText | 颜色。 |
见 DotsLoader。
## 状态
- 路径点吸附像素。
- 减少动画：静止的波形并显示文字。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 无。
docs/components/292-shimmer.md
+50
View File
@@ -0,0 +1,50 @@
# 292 Shimmer 占位扫光
## 用途
加载中显示带扫光的占位块，加载完成后构建内容。
## 最小示例
```go
loading := true
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.Shimmer(c, loading, mujica.ShimmerOptions{Height: 48}, func() {
ui.Text(c, "Report ready")
})
}
ui.Render(view, 400, 300, 1)
```
签名：`func Shimmer(c *ui.Context, loading bool, opts ShimmerOptions, content func()) *ui.Element`
## 参数
`ShimmerOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Width | float32 | 0（填满） | 宽度；为负 panic。 |
| Height | float32 | 0（即 ControlHeight） | 高度。 |
| Label | string | 内置“加载中” | 加载时朗读的文字。 |
`loading` 为 false 时只构建 content。
## 状态
- 扫光为一条半透明 Surface 色带，位置吸附像素，只在绘制时动画。
- 减少动画：静态填充。
- 加载结束后不再重绘。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 只用于加载中，不作装饰。
docs/components/293-count-up.md
+47
View File
@@ -0,0 +1,47 @@
# 293 CountUp 数字过渡
## 用途
数值变化时从旧值过渡到新值。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.CountUp(c, 12840, mujica.CountUpOptions{Duration: 800 * time.Millisecond})
}
ui.Render(view, 400, 300, 1)
```
签名：`func CountUp(c *ui.Context, value float64, opts CountUpOptions) *ui.Element`
## 参数
`CountUpOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Duration | time.Duration | 0（即 120 ms） | 过渡时长；为负 panic。 |
| Decimals | int | 0 | 小数位；为负 panic。 |
| Format | func(float64) string | nil | 自定义显示，优先于 Decimals。 |
value 须为有限值。首次显示直接为目标值。
## 状态
- 缓出过渡，过渡中途再变化时从当前显示值继续。
- 等宽数字防止抖动；朗读最终值。
- 减少动画：直接显示新值。过渡结束或屏外隐藏后停止重绘；恢复动画设置时保持已显示的最终值。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 无。
docs/components/294-typewriter.md
+49
View File
@@ -0,0 +1,49 @@
# 294 Typewriter 打字机
## 用途
逐字显示文本，可调速度、可跳过、完成时通知；文本增长时从当前位置继续。
## 最小示例
```go
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
r := mujica.Typewriter(c, "The court assembles at dusk.", mujica.TypewriterOptions{Speed: 30, Skippable: true})
if r.Changed() {
// show the next message
}
}
ui.Render(view, 400, 300, 1)
```
签名：`func Typewriter(c *ui.Context, text string, opts TypewriterOptions) ChoiceResult`
## 参数
`TypewriterOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Speed | float64 | 0（即每秒 40 字） | 速度；须为有限值，并产生 1 ns 到 time.Duration 上限之间的正间隔。非法值 panic。 |
| Skippable | bool | false | 显示“跳过”按钮。 |
返回 `ChoiceResult`，含 `Element`。
## 状态
- 按定时请求帧，不连续重绘。
- 整段文本作为名称朗读，不逐字朗读。
- 减少动画：直接显示全文。
## 事件
- `Changed()`：全文显示完的那一帧（含跳过）。
## 键盘操作
- “跳过”按钮用 Tab 到达，Enter 或 Space 跳过。
## 限制
- 文本被替换为不以旧文本开头的内容时从头开始。
docs/components/295-shimmer-text.md
+46
View File
@@ -0,0 +1,46 @@
# 295 ShimmerText 文字扫光
## 用途
处理中的状态文字（如“思考中”）上有光扫过。
## 最小示例
```go
thinking := true
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.ShimmerText(c, "Thinking…", mujica.ShimmerTextOptions{Active: thinking})
}
ui.Render(view, 400, 300, 1)
```
签名：`func ShimmerText(c *ui.Context, text string, opts ShimmerTextOptions) *ui.Element`
## 参数
`ShimmerTextOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Active | bool | false | 扫光；否则为静态 TextMuted 文字。 |
text 为空时 panic。
## 状态
- 逐字由 TextMuted 渐亮到 Text，再回落；只在绘制时动画。
- 以状态角色朗读文字。
- 减少动画或未激活：静态文字。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 扫光时文字保持单行。
docs/components/296-stagger.md
+50
View File
@@ -0,0 +1,50 @@
# 296 Stagger 依次进场
## 用途
子项按间隔依次进场，只在首次出现时执行一次。
## 最小示例
```go
guests := []string{"Sakiko", "Uika", "Mutsumi"}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.Stagger(c, len(guests), mujica.StaggerOptions{}, func(i int) {
ui.Text(c, guests[i])
})
}
ui.Render(view, 400, 300, 1)
```
签名：`func Stagger(c *ui.Context, n int, opts StaggerOptions, item func(i int)) *ui.Element`
## 参数
`StaggerOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Interval | time.Duration | 0（即 60 ms） | 相邻子项间隔。 |
| Duration | time.Duration | 0（即 PopupDuration） | 每项进场时长。 |
| Horizontal | bool | false | 横向排列。 |
n、Interval、Duration 为负时 panic。基于 MyGo `Transition` 的 Enter。
## 状态
- 每项从 8 DIP 外淡入。
- 序列结束后新增的项照常进场，不再等待。
- 减少动画：一次全部显示。按定时请求帧。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 尚未出现的项不占位，容器随之增长。
docs/components/297-reorder-transition.md
+47
View File
@@ -0,0 +1,47 @@
# 297 ReorderTransition 重排过渡
## 用途
按稳定键排列子项，顺序变化时子项平滑移动到新位置；新增淡入，移除淡出。
## 最小示例
```go
order := []string{"Sakiko", "Uika", "Mutsumi"}
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.ReorderTransition(c, order, mujica.ReorderTransitionOptions{Gap: 4}, func(name string) {
ui.Text(c, name)
})
}
ui.Render(view, 400, 300, 1)
```
签名：`func ReorderTransition[K comparable](c *ui.Context, keys []K, opts ReorderTransitionOptions, item func(key K)) *ui.Element`
## 参数
`ReorderTransitionOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Duration | time.Duration | 0（即 120 ms） | 移动时长；为负 panic。 |
| Gap | float32 | 0 | 子项间距。 |
键重复时 panic。基于 MyGo `Transition` 的 Position、Enter 与 Exit。
## 状态
- 减少动画：直接到位。动画结束后停止重绘。
## 事件
- 无。
## 键盘操作
- 焦点随键跟随子项移动。
## 限制
- 只做纵向列；虚拟化列表（List）的行不支持此过渡（MyGo 文档 transitions.md）。
docs/components/298-layout-transition.md
+52
View File
@@ -0,0 +1,52 @@
# 298 LayoutTransition 布局过渡
## 用途
内容的尺寸与位置变化时从旧布局过渡到新布局（FLIP）。
## 最小示例
```go
open := false
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.LayoutTransition(c, mujica.LayoutTransitionOptions{Clip: true}, func() {
ui.Text(c, "Program")
if open {
ui.Text(c, "Overture · Masquerade · Finale")
}
})
}
ui.Render(view, 400, 300, 1)
```
签名：`func LayoutTransition(c *ui.Context, opts LayoutTransitionOptions, content func()) *ui.Element`
## 参数
`LayoutTransitionOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Duration | time.Duration | 0（即 120 ms） | 时长；为负 panic。 |
| Row | bool | false | 横向排列内容。 |
| Clip | bool | false | 尺寸变化时裁剪溢出内容。 |
基于 MyGo `Transition` 的 Position 与 Size。
## 状态
- 尺寸过渡中内容按每一帧的尺寸重新布局。
- 窗口缩放引起的变化不动画；减少动画时直接到位。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 被同一变化推动的兄弟元素需要各自的 LayoutTransition 才会同步移动。
docs/components/299-presence.md
+48
View File
@@ -0,0 +1,48 @@
# 299 Presence 进出场
## 用途
内容随 show 进出场：淡入淡出、滑动或折叠，退出完成后移除。
## 最小示例
```go
show := true
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.Presence(c, show, mujica.PresenceOptions{Kind: mujica.PresenceSlide}, func() {
ui.Text(c, "Saved")
})
}
ui.Render(view, 400, 300, 1)
```
签名：`func Presence(c *ui.Context, show bool, opts PresenceOptions, content func()) *ui.Element`
## 参数
`PresenceOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Kind | PresenceKind | PresenceFade | PresenceFade、PresenceSlide、PresenceCollapse；未知值 panic。 |
| Duration | time.Duration | 0（即 PopupDuration） | 时长；为负 panic。 |
基于 MyGo `Transition` 的 Enter 与 Exit：退出时保留上一帧的副本直到动画结束，不占布局、不接收指针与焦点。
## 状态
- 减少动画：直接出现与消失。动画结束后停止重绘。
## 事件
- 无。
## 键盘操作
- 退出中的内容不接收焦点。
## 限制
- 不提供缩放：MyGo `ui.Motion` 只有位移、透明度与折叠（ui/transition.go:40）。
- 父元素在上一帧不存在时，内容随父元素一起出现而不进场。
docs/components/300-blink-highlight.md
+47
View File
@@ -0,0 +1,47 @@
# 300 BlinkHighlight 变化高亮
## 用途
数值变化时单次高亮：上升 Success、下降 Danger，并留下方向箭头。
## 最小示例
```go
price := 101.5
view := func(c *ui.Context) {
mujica.Use(c, mujica.Settings{})
mujica.BlinkHighlight(c, price, mujica.BlinkHighlightOptions{})
}
ui.Render(view, 400, 300, 1)
```
签名：`func BlinkHighlight(c *ui.Context, value float64, opts BlinkHighlightOptions) *ui.Element`
## 参数
`BlinkHighlightOptions`
| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| Format | func(float64) string | 两位小数 | 显示格式。 |
| Duration | time.Duration | 0（即 120 ms） | 高亮淡出时长；为负 panic。 |
value 须为有限值；首次显示不高亮。
## 状态
- 背景从 22% 透明度淡出一次，结束后停止重绘。
- 方向箭头与朗读的“上升/下降”在变化后一直保留，不只靠颜色。
- 减少动画：不闪烁，只显示静态箭头。
## 事件
- 无。
## 键盘操作
- 无。
## 限制
- 开启减少动画会结束当前高亮；恢复动画时保持静态方向标记。