Merge branch 'main' into worktree-agent-ae66cd6d621c16060
This commit is contained in:
151 files changed
+2401
-670
No files matched your search
@@ -29,7 +29,7 @@ view := func(c *ui.Context) {
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Width`, `Height` | `float32` | `0` | 盒子尺寸（DIP）。为 0 时使用 `src` 的尺寸（只给一边时按比例补齐），在占位、加载、错误状态下也保持这个尺寸；`src` 为 nil 时为 160×120。负数 panic。 |
|
||||
| `Width`, `Height` | `float32` | `0` | 盒子尺寸（DIP）。为 0 时使用 `src` 的尺寸（只给一边时按比例补齐）；`src` 为 nil 时为 160×120。占位、加载、错误状态与已加载图片使用相同的宽高比和伸缩规则，父容器变窄时一起按比例缩小，所以各状态的盒子完全相同。负数 panic。 |
|
||||
| `Crop` | `bool` | `false` | `true` 覆盖并裁切（`ui.Cover`）；`false` 完整放入（`ui.Contain`）。 |
|
||||
| `Alt` | `string` | `""` | 替代说明，供辅助技术读取；在其他状态下作为描述。 |
|
||||
| `Loading` | `bool` | `false` | 调用方正在加载。 |
|
||||
@@ -43,7 +43,7 @@ view := func(c *ui.Context) {
|
||||
|
||||
- 占位：浅色框内显示图片图标，名称“暂无图片”。
|
||||
- 加载中：框内显示 Spinner，名称“正在加载图片”。
|
||||
- 错误：显示错误图标、“图片加载失败”和“重试”按钮，`Err.Error()` 作为无障碍错误说明。
|
||||
- 错误：盒子中央是 28×28 DIP 的仅图标“重试”按钮（`refresh-cw`），`Err.Error()` 作为按钮的悬停提示和描述，也是盒子的无障碍错误说明。盒子足够宽时，按钮旁边还会显示“图片加载失败”文字。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -55,6 +55,9 @@ view := func(c *ui.Context) {
|
||||
|
||||
## 限制
|
||||
|
||||
- 盒子高度至少 28 DIP 时，“重试”按钮才能完整显示。更矮的盒子会裁掉按钮的上下边缘，但按钮中心仍然可以点击，键盘也可以操作。
|
||||
- “图片加载失败”文字只在盒子宽度足够时显示。宽度按上一帧的布局判断，盒子尺寸变化时组件会多布局一帧来修正。
|
||||
|
||||
- 组件不读取文件，也不访问网络。解码（`ui.DecodeBitmap`、`ui.ParseSVG`）和异步加载由调用方完成，结果通过 `Window.Update` 回到界面线程，再设置 `Loading` 与 `Err`。
|
||||
- SVG 的绘制范围以 MyGo 支持的部分为准：不支持文本、嵌入图片、pattern、marker 和 filter。
|
||||
- 接口里装着 nil 指针（如 `(*ui.Bitmap)(nil)`）时不算 `nil`，不会显示占位。
|
||||
@@ -29,7 +29,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `FormOptions.Horizontal` | `bool` | false | 标签放在控件左侧一列，右对齐（MyGo `ui.Form` 布局）。 |
|
||||
| `FormOptions.Horizontal` | `bool` | false | 标签放在控件左侧一列，右对齐。 |
|
||||
| `FormOptions.SubmitLabel` | `string` | 内置“Submit/提交” | 提交按钮文字。 |
|
||||
| `FormOptions.ResetLabel` | `string` | 内置“Reset/重置” | 重置按钮文字。 |
|
||||
| `FormItemOptions[T].Label` | `string` | 必填 | 字段标签；空值 panic。 |
|
||||
@@ -56,4 +56,4 @@ Tab / Shift+Tab 在字段间移动，离开字段即校验。提交失败后焦
|
||||
- 控件由调用方构建，`FormItem` 的 control 回调必须返回可获取焦点的元素，用于错误定位。
|
||||
- 校验在失焦与提交时触发；已触碰字段在值变化时重新同步校验，异步校验只在下一次失焦或提交时重跑。
|
||||
- 异步结果以版本号对齐：值变化后旧版本的 `Resolve` 返回 false 并被丢弃。`FormState` 的方法只能在界面线程调用，后台任务需经 `Window.Update` 回到界面线程。
|
||||
- 必填标记以“ *”附在标签文字后，屏幕阅读器会一起读出；MyGo 的 Field 标签不支持富文本，无法单独着色。
|
||||
- 必填标记“*”只作视觉显示，辅助技术通过说明“必填”获知。
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 用途
|
||||
|
||||
为单个控件提供标签、必填标记、说明与错误文字。标签通过 MyGo `ui.Field` 关联控件：屏幕阅读器以标签命名控件，并读出说明与错误；点击标签聚焦控件。
|
||||
为单个控件提供标签、必填标记、说明与错误文字。标签、说明与错误显式关联到 control 返回的元素：屏幕阅读器以标签命名该元素并读出说明、必填与错误；点击标签聚焦该元素。
|
||||
|
||||
## 最小示例
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
email := ""
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.FormField(c, "Email", mujica.FormFieldOptions{Required: true, Description: "For receipts."}, func() {
|
||||
mujica.InputGroup(c, &email, mujica.InputGroupOptions{})
|
||||
mujica.FormField(c, "Email", mujica.FormFieldOptions{Required: true, Description: "For receipts."}, func() *ui.Element {
|
||||
return mujica.InputGroup(c, &email, mujica.InputGroupOptions{}).Input
|
||||
})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
@@ -24,11 +24,11 @@ ui.Render(view, 400, 300, 1)
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `label` | `string` | 必填 | 标签文字；空值 panic。 |
|
||||
| `FormFieldOptions.Required` | `bool` | false | 在标签后加“ *”。 |
|
||||
| `FormFieldOptions.Required` | `bool` | false | 在标签后显示危险色“*”，并向辅助技术说明“必填”。 |
|
||||
| `FormFieldOptions.Description` | `string` | "" | 控件下方的说明。 |
|
||||
| `FormFieldOptions.Error` | `string` | "" | 控件下方的错误，并把控件标记为无效。 |
|
||||
| `FormFieldOptions.Horizontal` | `bool` | false | 标签在左、控件在右。 |
|
||||
| `control` | `func()` | 必填 | 构建控件；其中第一个可获取焦点的元素即被关联的控件。 |
|
||||
| `control` | `func() *ui.Element` | 必填 | 构建控件并返回要关联的可聚焦元素（如 `InputGroupParts.Input`）；返回 nil 时 panic。 |
|
||||
|
||||
## 状态
|
||||
|
||||
@@ -44,6 +44,6 @@ Tab 直接到达控件；点击标签聚焦控件，或切换复选框、开关
|
||||
|
||||
## 限制
|
||||
|
||||
- 标签、说明与错误文字由 MyGo `ui.Field` 绘制，使用主题颜色（文字、TextMuted、Danger）；字号与间距跟随 MyGo。
|
||||
- 错误只把边框染红的效果对 MyGo 自带输入框生效；MujicaUI 的 InputGroup 等需同时传入 `Invalid: true`。
|
||||
- 左右布局时多个字段需放在同一个 `ui.Form` 或 MujicaUI `Form(Horizontal)` 中才能对齐标签宽度；单独使用时只按自身标签宽度排列。
|
||||
- control 返回的元素的 Label 会被字段标签覆盖。
|
||||
- Error 只把元素标记为无效；InputGroup 等的红色边框需同时传入 `Invalid: true`。
|
||||
- 左右布局时多个字段需放在 MujicaUI `Form(Horizontal)` 中才能对齐标签宽度；单独使用时只按自身标签宽度排列。
|
||||
@@ -53,3 +53,4 @@ ui.Render(view, 400, 300, 1)
|
||||
- MyGo 的 `ui.Calendar` 固定周一起始、只有英文且不支持禁用日期（ui/date.go:85-160），因此本组件基于 `RadioBase` 自绘网格，不复用 `ui.Calendar`。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -33,12 +33,13 @@ ui.Render(view, 400, 300, 1)
|
||||
| `Today` | `Date` | 零值（系统时钟） | 弹层日历中的今日标记；空值时弹层打开到此月份。 |
|
||||
| `Clearable` | `bool` | false | 显示清空按钮；清空输入后提交表示“无日期”。 |
|
||||
| `Placeholder` | `string` | 内置“选择日期” | 空输入框的占位文字。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用输入与弹层。 |
|
||||
| `Label` | `string` | 占位文字 | 辅助技术名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停（边框加深）、聚焦（焦点色边框）、错误（危险色边框 + 下方说明，输入保留）、禁用。弹层内日历状态同 Calendar。
|
||||
默认、悬停（边框加深）、聚焦（焦点色边框）、只读（背景与边框减弱，可选择复制）、错误（危险色边框 + 下方说明，输入保留）、禁用。弹层内日历状态同 Calendar。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -54,6 +55,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
- 无效或越界的输入（如 2026-02-30）显示具体错误并保留原文，不会被修正为相邻日期。
|
||||
- MyGo 的 `ui.DateInput` 固定格式且不可键入（ui/date.go:13），因此本组件组合 `TextInputBase` 与自绘日历弹层（`PopoverBase`）。
|
||||
- 暂不提供只读模式：MyGo v0.2.10 未公开 TextInputBase 的只读开关。
|
||||
- 只读模式沿用 TextInput 的做法：编辑副本并在每帧恢复，文本仍可选择与复制。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -30,6 +30,7 @@ ui.Render(view, 400, 300, 1)
|
||||
| `DisableDate` | `func(Date) bool` | nil | 不可选日期；范围内包含此类日期时拒绝并提示。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 今日标记与空值时的起始月份。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用。 |
|
||||
| `Label` | `string` | 内置“日期范围” | 辅助技术名称。 |
|
||||
|
||||
@@ -55,3 +56,4 @@ ui.Render(view, 400, 300, 1)
|
||||
- `DateRange` 为闭区间，`Days()` 计入两端。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -30,12 +30,13 @@ ui.Render(view, 400, 300, 1)
|
||||
| `SecondStep` | `int` | 0（即 1） | 秒步长，必须整除 60。 |
|
||||
| `Min` | `TimeOfDay` | 00:00:00 | 最早时间。 |
|
||||
| `Max` | `TimeOfDay` | 零值（即 23:59:59） | 最晚时间。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用。 |
|
||||
| `Label` | `string` | 空 | 组名；各段名称为“Label: 时/分/秒”。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、聚焦段（酒红填充）、错误（危险色边框 + 说明，草稿保留）、禁用。弹层列表中超出范围的项禁用。
|
||||
默认、悬停、聚焦段（酒红填充 + 键盘焦点环）、只读、错误（危险色边框 + 说明，草稿保留）、禁用。弹层列表中超出范围的项禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -52,8 +53,9 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 限制
|
||||
|
||||
- 超出范围或不符合步长的时间会提示，不会被自动夹取或取整。
|
||||
- 超出范围或不符合步长的时间会提示，不会被自动夹取或取整；键入超出段范围的数字（如小时 29）会保留显示并报错。
|
||||
- 段顺序固定为“时:分:秒 上午/下午”，zh-CN 下上午/下午也位于末尾。
|
||||
- MyGo 的 `ui.TimeInput` 只有时分且无 12 小时制、步长和范围（ui/timeinput.go:18），因此本组件自绘分段。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -31,6 +31,7 @@ ui.Render(view, 400, 300, 1)
|
||||
| `Min` | `TimeOfDay` | 00:00:00 | 两端最早时间。 |
|
||||
| `Max` | `TimeOfDay` | 零值（即 23:59:59） | 两端最晚时间。 |
|
||||
| `AllowOvernight` | `bool` | false | 允许结束早于开始，表示次日结束，并显示“次日”。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用。 |
|
||||
| `Label` | `string` | 空 | 整组名称。 |
|
||||
|
||||
@@ -53,3 +54,4 @@ ui.Render(view, 400, 300, 1)
|
||||
- `TimeRange.Overnight()` 报告是否跨午夜。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -29,6 +29,7 @@ ui.Render(view, 400, 300, 1)
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 用户编辑所用时区；为 nil 时 panic。 |
|
||||
| `Layout` | `string` | `2006-01-02` | 日期部分的 Go 时间布局，用于显示与错误说明。 |
|
||||
| `Min` | `time.Time` | 零值 | 最早时刻。 |
|
||||
| `Max` | `time.Time` | 零值 | 最晚时刻。 |
|
||||
| `Seconds` | `bool` | false | 显示秒。 |
|
||||
@@ -36,6 +37,7 @@ ui.Render(view, 400, 300, 1)
|
||||
| `MinuteStep` | `int` | 0（即 1） | 分钟步长。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 今日标记与空值时的默认日期。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用。 |
|
||||
| `Label` | `string` | 内置占位文字 | 辅助技术名称。 |
|
||||
|
||||
@@ -60,3 +62,4 @@ ui.Render(view, 400, 300, 1)
|
||||
- 空值（零 `time.Time`）打开时默认今天 00:00。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -29,6 +29,7 @@ ui.Render(view, 400, 300, 1)
|
||||
| `DisableMonth` | `func(YearMonth) bool` | nil | 不可选月份。 |
|
||||
| `Clearable` | `bool` | false | 有值时显示清空按钮。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记当前月份。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用。 |
|
||||
| `Label` | `string` | 内置“选择月份” | 辅助技术名称。 |
|
||||
|
||||
@@ -53,3 +54,4 @@ ui.Render(view, 400, 300, 1)
|
||||
- 键盘移到不可选月份时焦点保持在原处，可继续移动。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -29,6 +29,7 @@ ui.Render(view, 400, 300, 1)
|
||||
| `DisableYear` | `func(int) bool` | nil | 不可选年份。 |
|
||||
| `Clearable` | `bool` | false | 有值时显示清空按钮。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记当前年份。 |
|
||||
| `ReadOnly` | `bool` | false | 只读：可聚焦、可复制（Cmd/Ctrl+C），不能修改，不打开弹层。 |
|
||||
| `Disabled` | `bool` | false | 禁用。 |
|
||||
| `Label` | `string` | 内置“选择年份” | 辅助技术名称。 |
|
||||
|
||||
@@ -53,3 +54,4 @@ ui.Render(view, 400, 300, 1)
|
||||
- 只支持公元 1 年及以后；值为负数时 panic。
|
||||
- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
|
||||
- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。
|
||||
- 无障碍：MyGo v0.2.10 没有公开设置弹出按钮展开状态（`expanded`）、数值范围（`hasRange`/`accRange`）与值（`accValue`）的接口，这些字段只在 MyGo 内部组件中赋值（ui/element.go:286-295，例如 ui/base.go:297、ui/indicators.go:61）。因此触发器只能声明为 `RolePopUpButton` 而无法报告展开状态；时间段以 `Description` 读出当前值与范围，错误通过 `Error()` 关联。
|
||||
@@ -41,7 +41,7 @@ mujica.Tabs(c, &tab, []mujica.Tab{
|
||||
## 状态
|
||||
|
||||
- 选中：Selection 背景、2 DIP AccentText 边线（横向在底边，纵向在右边）、600 字重，三者同时标记。
|
||||
- 悬停：SurfaceHover 背景；按下：Selection 背景。
|
||||
- 悬停：SurfaceHover 背景；按下：Selection 背景。背景与文字颜色在 120 ms 内过渡，减少动画时直接切换。
|
||||
- 焦点：2 DIP Focus 焦点环，外留 2 DIP。
|
||||
- 禁用：MyGo 统一降低不透明度，不响应指针与键盘。
|
||||
- 溢出：标签条横向（纵向时竖向）滚动；键盘或点击切换后，选中标签滚入视野。
|
||||
|
||||
@@ -62,10 +62,10 @@ mujica.Sidebar(c, &selected, []mujica.SidebarSection{
|
||||
|
||||
- Tab：进入侧边栏（一个停靠点）。
|
||||
- ↑/↓：上一项/下一项；Home / End：首项/末项；输入名称开头字母跳到匹配项。
|
||||
- 分组与嵌套组标题用指针点击展开折叠。
|
||||
- 分组与嵌套组标题各是一个 Tab 停靠点（辅助技术看到 disclosure，含展开状态）；Enter 或 Space 展开折叠，箭头在 120 ms 内转动。
|
||||
|
||||
## 限制
|
||||
|
||||
- 复用 MyGo `ui.SidebarItem`，它用主题 Accent 绘制图标（`ui/sidebar.go:182`）；深色主题 Accent 对比度不足，本组件在构建侧边栏时临时把 MyGo 主题的 Accent 换成 AccentText。
|
||||
- MyGo `SidebarItem` 总是追加名称文字（`ui/sidebar.go:212`）；紧凑模式传入空名称，名称改由 `Label` 与提示提供，因此紧凑模式下首字母跳转不可用。
|
||||
- 嵌套组用 MyGo `SidebarSection` 实现，组标题本身不能被选中，且只能用指针展开折叠（MyGo 不给标题注册按键）。
|
||||
- 组标题基于 MyGo `CollapsibleBase` 的触发器，而不是 `SidebarSection`（后者只能用指针展开，箭头固定 150 ms，`ui/sidebar.go:115`）。组标题本身不能被选中。展开状态按完整父路径保存，同名组互不影响。
|
||||
@@ -52,7 +52,7 @@ if id, ok := res.Chosen(); ok && id == "wrap" {
|
||||
- 打开的菜单标题：Selection 背景；高亮项：Selection 背景。
|
||||
- 勾选项：AccentText 勾号；单选项：AccentText 菱形标记；名称附“已勾选”。
|
||||
- 禁用项：降低不透明度，指针与键盘均跳过。
|
||||
- 弹层：6 DIP 圆角、Border 边框；靠近窗口边缘时左移，子菜单放不下时翻到父菜单左侧，过高时上移。
|
||||
- 弹层：6 DIP 圆角、Border 边框；靠近窗口边缘时左移，子菜单放不下时翻到父菜单左侧，过高时限高并在菜单内滚动，键盘高亮项自动滚入视野。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -71,4 +71,4 @@ if id, ok := res.Chosen(); ok && id == "wrap" {
|
||||
- 快捷键只做提示，不注册；用 `c.Shortcut` 处理。
|
||||
- MyGo 没有 menu / menuitem 角色（`ui/access.go:25-79`），项以按钮呈现；勾选状态无法通过公开接口写入（`ui/base.go:56` 的 checked 为内部字段），因此写入名称。
|
||||
- 指针点击非可聚焦元素会清除焦点（`ui/input.go:238`）；选择后组件把焦点还给对应标题。
|
||||
- 菜单打开期间，焦点保持在标题上，高亮项由组件管理（与 MyGo `SelectBase` 相同的方式）。
|
||||
- 菜单打开期间，焦点保持在标题上，高亮项由组件管理。驱动菜单的按键注册在标题上，而 MyGo 的 active descendant 不公开，因此高亮变化时用 `c.Announce` 朗读当前项，并把它写入标题的 `Description`。
|
||||
@@ -63,3 +63,4 @@ if id, ok := res.Chosen(); ok {
|
||||
|
||||
- MyGo `TextInputBase` 没有占位文字（`ui/editor.go:734`）；为避免与输入法组合文字重叠，说明放在底部提示栏，搜索框以无障碍名称“搜索命令”标识。
|
||||
- 搜索是子串匹配，不做模糊匹配或排序打分。
|
||||
- 焦点留在搜索框以便继续输入；方向键移动高亮时用 `c.Announce` 朗读当前命令，并写入搜索框的 `Description`（MyGo 的 active descendant 不公开）。
|
||||
@@ -41,7 +41,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停（SurfaceHover）、选中（Accent 填充 + OnAccent 文字 + 勾选标记）、聚焦（列表外 2 DIP 焦点环）、网格选中（AccentText 边框 + 勾选）、加载、追加加载、失败、空。
|
||||
默认、悬停（SurfaceHover）、选中（Selection 背景 + Text 文字 + AccentText 勾选标记）、聚焦（列表外 2 DIP 焦点环）、网格选中（Selection 背景 + AccentText 边框与勾选）、加载、追加加载、失败、空。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -57,6 +57,6 @@ ui.Render(view, 400, 300, 1)
|
||||
## 限制
|
||||
|
||||
- 虚拟化由 MyGo `ui.List`/`ui.GridView` 提供：每帧构建的元素数由可见区域和预取范围决定；程序跳转（`ScrollTo`）时目标两侧各构建一屏。测试以 10 万条记录统计“最后一帧调用条目构建函数的次数”验证上限（list_test.go）。
|
||||
- MyGo 单选跟随键时只在原位置附近 1000 行内查找（ui/list.go:30 `listSearch`）；插入或删除大量上方行后，单选可能被清除。
|
||||
- 单选按键保存：每帧先检查原位置的键，不符时扫描全部条目重新定位（MyGo 自身只在附近 1000 行内查找，ui/list.go:30），所以反转、排序或在网格前端插入后选择仍指向同一条目；条目被删除时选择清除。
|
||||
- Shift 连选的锚点由 MyGo 决定（ui/list.go `extend`），与平台习惯一致。
|
||||
- 网格模式没有 `ListState.Visible` 等滚动位置读取接口。
|
||||
@@ -34,7 +34,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 参数
|
||||
|
||||
`func DataTable[R any, K comparable](c *ui.Context, s *DataTableState[K], rows []R, opts DataTableOptions[R, K]) DataTableView`。另有 `DataTableColumnPicker(c, s, cols)`（“列”按钮与勾选弹层，控制显隐）和纯函数 `DataTableRows(rows, cols, sort, filter) []int`（本地排序筛选辅助，返回行下标）。
|
||||
`func DataTable[R any, K comparable](c *ui.Context, s *DataTableState[K], rows []R, opts DataTableOptions[R, K]) DataTableView`。表格上方有“列”按钮，弹层中每列提供显隐勾选框、升序/降序排序、左移/右移与减小/增大列宽（每次 16 DIP），这是排序、列顺序与列宽的键盘入口。另有纯函数 `DataTableRows(rows, cols, sort, filter) []int`（本地排序筛选辅助，返回行下标）。
|
||||
|
||||
`DataTableState` 字段：`Sort ui.SortOrder`、`Filter string`（不区分大小写包含匹配全部列的 `Text`）、`Hidden map[string]bool`（按列 ID 隐藏）、`Layout ui.TableLayout`（用户拖动得到的列顺序与列宽，可保存恢复）、`Selection ui.Selection[K]`（多选）。方法：`Selected()`、`Rows()`（筛选后行数）。
|
||||
|
||||
@@ -51,23 +51,25 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 状态
|
||||
|
||||
默认、表头悬停、排序箭头（升/降）、行悬停、选中行（Accent 填充 + OnAccent 文字；单选首列菱形，多选首列勾选框）、聚焦（表格外焦点环）、加载、追加加载、失败、空、无匹配。数据行高度不低于当前密度的数据行高（28/36/44 DIP）。
|
||||
默认、表头悬停、排序箭头（升/降）、行悬停、选中行（Selection 背景 + Text 文字；单选首列 AccentText 菱形，多选首列勾选框）、聚焦（表格外焦点环）、加载、追加加载、失败、空、无匹配。数据行高度不低于当前密度的数据行高（28/36/44 DIP）。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()`：选择变化；`Submitted()`：Enter 或双击；`SortChanged()`：点击表头改变了 `State.Sort`；`Retried()`：点击“重试”。
|
||||
`Changed()`：选择变化（含勾选框）；`Submitted()`：Enter 或双击；`SortChanged()`：点击表头或列菜单改变了 `State.Sort`；`Retried()`：点击“重试”。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- ↑/↓、Home/End：移动选择；Enter：提交；输入字母按首个可见列定位。
|
||||
- 多选：Shift/Cmd(Ctrl) 配合点击或方向键；Cmd/Ctrl+A 全选。
|
||||
- 表头：点击排序、再次点击反向；拖动表头边缘调整列宽，双击适配内容；拖动表头移动列。
|
||||
- 列选择器：Tab 进入勾选项，Space 切换；Escape 关闭。
|
||||
- 列菜单：Tab 到“列”按钮，Enter 打开；Tab 在各列的勾选框与排序、移动、列宽按钮间移动，Enter/Space 执行；Escape 关闭。
|
||||
- 多选勾选框可用 Tab 到达，Space 切换。
|
||||
|
||||
## 限制
|
||||
|
||||
- MyGo `ui.Table` 只按调用方给出的顺序显示（docs/ui/table.md “Sorting”），因此本组件在本地完成排序，或在受控模式下交给调用方。
|
||||
- 表头内容只能是 `Title` 文字（ui/table.go `table` 构建表头），无法放置全选勾选框；全选使用 Cmd/Ctrl+A。
|
||||
- 表头内容只能是 `Title` 文字且只响应指针（ui/table.go `tableHeader`），因此全选使用 Cmd/Ctrl+A，键盘排序与调整列通过列菜单。
|
||||
- 共享列宽的列在列菜单中从 max(MinWidth, 120) DIP 开始调整。
|
||||
- 单选的跟随由组件按键重新定位，跨越任意距离都有效；多选的键盘锚点在大规模重排后由 MyGo 重置（ui/list.go:30）。
|
||||
- 删除的数据行对应的选择会在数据变化时清除；被筛选隐藏的行保留选择。
|
||||
- 10 万行 × 10 列：测试统计“最后一帧构建过单元格的行数”不超过 16，并断言重复帧不再调用比较函数（data_table_test.go）。
|
||||
@@ -38,7 +38,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、选中（Accent 填充 + 勾选标记）、聚焦、展开/折叠（箭头旋转）、子项加载中、子项加载失败、空、首次加载与失败。
|
||||
默认、悬停、选中（Selection 背景 + AccentText 勾选标记）、聚焦、展开/折叠（箭头旋转）、子项加载中、子项加载失败、空、首次加载与失败。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -53,5 +53,5 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
- 基于 MyGo `ui.Outline` 而不是 `ui.Tree`：`ui.Tree` 会构建全部已展开节点（docs/ui/tree.md “A tree builds every item it shows”），不满足大量节点虚拟化要求。
|
||||
- `Outline` 每帧遍历已展开的节点以计算行（ui/outline.go `flatten`），元素数受可见区域限制，但遍历成本随展开节点数增长。
|
||||
- 单选跟随节点的搜索范围为 1000 行（ui/list.go:30）。
|
||||
- 单选按节点保存：行移动超过 MyGo 的 1000 行搜索范围（ui/list.go:30）时，组件扫描可见行重新定位并立即重建一帧；所选节点被折叠隐藏或删除时选择清除。
|
||||
- 异步加载由调用方在后台完成并通过 `Window.Update` 回到界面线程。
|
||||
@@ -29,7 +29,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 参数
|
||||
|
||||
`func TreeTable[K comparable](c *ui.Context, s *TreeTableState[K], opts TreeTableOptions[K]) DataTableView`。`TreeTableState` 字段：`Sort`、`Layout`、`Selection`；方法：`Selected()`、`SetOpen`、`IsOpen`。
|
||||
`func TreeTable[K comparable](c *ui.Context, s *TreeTableState[K], opts TreeTableOptions[K]) DataTableView`。`TreeTableState` 字段：`Sort`、`Layout`、`Selection`；方法：`Selected()`、`SetOpen`、`IsOpen`。表格上方的“列”按钮弹层提供每列的排序、左移/右移与列宽调整，是这些操作的键盘入口。
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -45,7 +45,7 @@ ui.Render(view, 400, 300, 1)
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、选中（Accent 填充 + 勾选标记）、聚焦、展开/折叠、排序箭头、子项加载中/失败、空。
|
||||
默认、悬停、选中（Selection 背景 + AccentText 勾选标记）、聚焦、展开/折叠、排序箭头、子项加载中/失败、空。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -54,6 +54,7 @@ ui.Render(view, 400, 300, 1)
|
||||
## 键盘操作
|
||||
|
||||
- 与 Tree 相同的方向键与展开键；点击表头排序同级节点，再次点击反向；拖动表头边缘或表头调整列宽与顺序。
|
||||
- 列菜单：Tab 到“列”按钮，Enter 打开，Tab 到排序、移动与列宽按钮，Enter 执行，Escape 关闭。
|
||||
|
||||
## 限制
|
||||
|
||||
|
||||
@@ -44,4 +44,4 @@ ui.Render(view, 400, 300, 1)
|
||||
## 限制
|
||||
|
||||
- 基于 MyGo `ui.CollapsibleBase`；MyGo 的 `ui.Accordion` 外观固定且用内部状态移动焦点（ui/collapsible.go `accordionKeys`），因此键盘移动在组件内重新实现：向上移动时焦点在下一帧到达。
|
||||
- 关闭动画进行的 120 ms 内内容仍在界面树中。
|
||||
- 关闭动画进行的 120 ms 内内容仍在界面树中，但已禁用：不接收点击，也不进入 Tab 序列。
|
||||
@@ -38,7 +38,7 @@ ui.Render(view, 400, 300, 1)
|
||||
## 键盘操作
|
||||
|
||||
- Enter/Space：展开或关闭。
|
||||
- 关闭后内容不在 Tab 序列中。
|
||||
- 关闭（包括关闭动画期间）的内容不在 Tab 序列中。
|
||||
|
||||
## 限制
|
||||
|
||||
|
||||
@@ -27,18 +27,18 @@ mujica.Meter(c, 93, mujica.MeterOptions{
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `value` | `float64` | 必填 | 0 到 1；超出或 NaN 时 panic（不确定模式忽略）。 |
|
||||
| `Shape` | `ProgressShape` | `ProgressLinear` | `ProgressLinear` 或 `ProgressRing`。 |
|
||||
| `Shape` | `ProgressShape` | `ProgressLinear` | `ProgressLinear` 或 `ProgressRing`；其他值 panic。 |
|
||||
| `Indeterminate` | `bool` | `false` | 未知长度的进度。 |
|
||||
| `Label` | `string` | `""` | 显示在旁边并作为无障碍名称；为空时名称为“Loading”。 |
|
||||
| `ShowValue` | `bool` | `false` | 显示百分比。 |
|
||||
| `Size` | `float32` | 环形 48、线形填满 | 环形直径或线形宽度；负数 panic。 |
|
||||
| `Size` | `float32` | 环形 48、线形填满 | 环形直径或线形宽度；负数、NaN 或无穷 panic。 |
|
||||
|
||||
`MeterOptions`：
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `value` | `float64` | 必填 | 须在范围内，否则 panic。 |
|
||||
| `Min`, `Max` | `float64` | 0, 1（两者都为 0 时） | 范围；`Max <= Min` panic。 |
|
||||
| `Min`, `Max` | `float64` | 0, 1（两者都为 0 时） | 范围；非有限值或 `Max <= Min` panic。 |
|
||||
| `Levels` | `*ui.MeterLevels` | `nil` | 阈值：达到 `Warning` 为偏高、达到 `Critical` 为严重；`Critical < Warning` 时低值为坏（如电量）。须在范围内。 |
|
||||
| `Label` | `string` | `""` | 名称。 |
|
||||
| `ShowValue` | `bool` | `false` | 显示“值 / 最大值”。 |
|
||||
@@ -47,7 +47,7 @@ mujica.Meter(c, 93, mujica.MeterOptions{
|
||||
## 状态
|
||||
|
||||
- 确定进度变化时以 120 ms 过渡，减少动画时直接跳到新值。
|
||||
- 不确定进度只在绘制时移动（只重绘、不重建视图）；减少动画时显示静态填充和“In progress”文字。
|
||||
- 不确定进度只在绘制时移动（只重绘、不重建视图）；减少动画时显示满格静态填充（对比度不低于 3:1）和“In progress”文字；切换到减少动画时进行中的过渡直接跳到目标值。
|
||||
- 计量条按级别使用 Success / Warning / Danger 颜色，同时显示“Normal / High / Critical / Low”文字与阈值刻度，并把级别写入无障碍名称。
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -16,7 +16,7 @@ mujica.Spinner(c, mujica.SpinnerOptions{Size: 20, Label: "Syncing", ShowLabel: t
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Size` | `float32` | 16 | 标记边长（DIP）。 |
|
||||
| `Size` | `float32` | 16 | 标记边长（DIP）；负数、NaN 或无穷 panic。 |
|
||||
| `Label` | `string` | 内置“Loading / 加载中” | 无障碍名称；`ShowLabel` 时也显示在旁边。 |
|
||||
| `ShowLabel` | `bool` | `false` | 在标记旁显示说明。 |
|
||||
| `Color` | `ui.Color` | `AccentText` | 标记颜色。 |
|
||||
|
||||
@@ -26,7 +26,7 @@ ui.Row(c).Gap(12).Children(func() {
|
||||
| `Height` | `float32` | 当前密度控件高度 | 矩形高度；文字形状由行数决定（每行 21 DIP）。 |
|
||||
| `Lines` | `int` | 1 | 文字行数，多行时最后一行为 60% 宽。 |
|
||||
|
||||
负值 panic。
|
||||
负值、NaN、无穷或未知形状 panic。文字行高随系统文本缩放。
|
||||
|
||||
## 状态
|
||||
|
||||
|
||||
Reference in new issue
Block a user