Inputs: review r1 fixes

2026-10-05 12:33:01 -04:00
1 parent 2a232930dd
commit ab8d9318c3
@@ -18,12 +18,12 @@ if mujica.Button(c, "Save", mujica.ButtonOptions{Icon: icons.Must("check")}).Cli

 | 字段 | 类型 | 默认值 | 含义 |
 | --- | --- | --- | --- |
-| `label` | `string` | 必填（仅图标时可为空） | 按钮文字。 |
+| `label` | `string` | 必填（仅图标时可为空） | 按钮文字；为空时必须提供 `Label`，否则 panic。 |
 | `Variant` | `ButtonVariant` | `Primary` | `Primary`、`Secondary`、`Outline`、`Ghost`、`Danger`。 |
 | `Icon` | `*ui.SVG` | `nil` | 文字前的 16 DIP 图标。 |
-| `Loading` | `bool` | `false` | 以菱形加载标记替换图标，保留尺寸与文字，阻止点击。 |
+| `Loading` | `bool` | `false` | 有图标时加载标记占用图标位置；纯文字时标记居中覆盖在隐藏的文字上，宽度不变；阻止点击。 |
 | `Disabled` | `bool` | `false` | 不可点击、不进入 Tab 序列。 |
-| `Label` | `string` | `""` | 无文字按钮的无障碍名称。 |
+| `Label` | `string` | `""` | 无障碍名称；`label` 为空时必填。 |

 ## 状态

@@ -23,7 +23,7 @@ if i := mujica.ButtonGroup(c, items, mujica.ButtonGroupOptions{Label: "Range"}).
 | --- | --- | --- | --- |
 | `Label` | `string` | `""` | 文字；与 `Icon` 至少给一个，否则 panic。 |
 | `Icon` | `*ui.SVG` | `nil` | 图标。 |
-| `Name` | `string` | `""` | 仅图标项的无障碍名称。 |
+| `Name` | `string` | `""` | 仅图标项的无障碍名称；仅图标且为空时 panic。 |
 | `Disabled` | `bool` | `false` | 单项禁用；方向键跳过该项。 |

 `ButtonGroupOptions`
@@ -32,7 +32,7 @@ if r.Submitted() {

 ## 状态

-默认（Surface 底、ControlBorder 边）、悬停（边框加深）、聚焦（边框 Focus 色；键盘聚焦另加焦点环）、只读（Background 底、Border 边）、错误、禁用。颜色变化 120 毫秒过渡，减少动画时直接切换。
+默认（Surface 底、ControlBorder 边）、悬停（边框加深）、聚焦（边框 Focus 色；键盘聚焦另加焦点环）、只读（Background 底、Border 边）、错误、禁用。聚焦时被禁用会放弃焦点，已排队的按键不再修改值、不触发事件。颜色变化 120 毫秒过渡，减少动画时直接切换。

 ## 事件

@@ -25,14 +25,14 @@ if r.Submitted() {
 | `MinHeight` | `float32` | `0`（三行） | 编辑区最小高度，DIP。 |
 | `MaxHeight` | `float32` | `0`（随内容增长） | 编辑区最大高度，超出后滚动；小于 `MinHeight` 时 panic。 |
 | `MaxLength` | `int` | `0`（不显示） | 显示“当前 / 上限”字数（按 Unicode 字符计）；超出时变红并提示超出数量。 |
-| `SubmitKey` / `SubmitMods` | `ui.Key` / `ui.Modifiers` | Cmd+Enter（非 macOS 为 Ctrl+Enter） | 提交快捷键；`SubmitKey` 为零时使用默认值。 |
+| `SubmitKey` / `SubmitMods` | `ui.Key` / `ui.Modifiers` | Cmd+Enter（非 macOS 为 Ctrl+Enter） | 提交快捷键；`SubmitKey` 为零时使用默认值。可设为不带修饰键的 Enter，此时 Shift+Enter 换行。 |
 | `Disabled` | `bool` | `false` | 禁用。 |
 | `ReadOnly` | `bool` | `false` | 只读，可选择复制。 |
 | `Error` | `string` | `""` | 错误文字；为空且超出 `MaxLength` 时自动显示超出提示。 |

 ## 状态

-默认、悬停、聚焦、只读、错误、禁用，表现同 TextInput。
+默认、悬停、聚焦、只读、错误、禁用，表现同 TextInput；聚焦时被禁用会放弃焦点，之后的输入与提交都不生效。

 ## 事件

@@ -40,10 +40,10 @@ if r.Submitted() {

 ## 键盘操作

-Enter 与 Shift+Enter 换行；提交快捷键提交；方向键、PageUp/PageDown 移动光标并滚动；撤销、剪贴板与输入法同 TextInput。
+未配置为提交键时 Enter 与 Shift+Enter 换行；提交快捷键在编辑器处理前被截获并提交，不插入换行；方向键、PageUp/PageDown 移动光标并滚动；撤销、剪贴板与输入法同 TextInput。

 ## 限制

 - `MaxLength` 只提示，不截断输入，以免打断输入法组合与粘贴。
- 提交快捷键不能是不带修饰键的 Enter：MyGo 编辑器先接收 Enter 并插入换行（`editor.go:161`）。
+- 输入法组合期间无法阻止提交快捷键：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。各平台输入法在组合时通常自己消费 Enter；只有未被输入法消费的按键会触发提交。
 - 只读实现方式同 TextInput。
@@ -21,7 +21,7 @@ if mujica.NumberInput(c, &copies, mujica.NumberInputOptions{Min: 1, Max: 99, Lab
 | `value` | `*float64` | 必填 | 数值；空值用 `math.NaN()` 表示，仅在 `AllowEmpty` 时允许。 |
 | `Min` / `Max` | `float64` | 都为 0 | 范围；相等（含零值）表示不限范围；`Min > Max` 时 panic。 |
 | `Step` | `float64` | `1` | 方向键与按钮的步长；负数 panic。 |
-| `Precision` | `int` | 取 `Step` 的小数位 | 保留与显示的小数位。 |
+| `Precision` | `int` | 取 `Step` 的小数位 | 保留与显示的小数位。范围边界向内取到该精度上（如 [0.11, 0.29] 精度 1 时有效值只有 0.2）；范围内没有任何该精度的值时 panic。 |
 | `AllowEmpty` | `bool` | `false` | 允许清空，值变为 NaN；从空值步进时从 0（夹在范围内）开始。 |
 | `StepperOnly` | `bool` | `false` | 只显示数值与上下箭头，不可输入；必须给出 `Min < Max`，且不能与 `AllowEmpty` 同用。 |
 | `Placeholder` | `string` | `""` | 空值时的占位。 |
@@ -31,7 +31,7 @@ if mujica.NumberInput(c, &copies, mujica.NumberInputOptions{Min: 1, Max: 99, Lab

 ## 状态

-输入模式同 TextInput；输入非数字或超出范围时显示内置错误（“请输入数字”“请输入 a 到 b 之间的数字”），值保持上一次有效值；失去焦点后文本恢复为当前值并清除该错误。到达边界时对应按钮禁用。
+输入模式同 TextInput；输入非数字或超出范围时显示内置错误（“请输入数字”“请输入 a 到 b 之间的数字”），值保持上一次有效值；失去焦点后错误文本与提示保留，直到用户改正，或调用方从外部改变了值。值在聚焦期间被外部修改时，输入框立即显示新值。到达边界时对应按钮禁用。

 ## 事件

@@ -48,4 +48,5 @@ if r.Moved() {
 ## 限制

 - MyGo 单行编辑器把 Shift+Enter 当作普通提交且不公开修饰键（`editor.go:489`，`submitMods` 未导出），组件用 `HandleInput` 先截获 Shift+Enter。
+- 输入法组合期间无法阻止提交与匹配跳转：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。各平台输入法在组合时通常自己消费 Enter；只有未被输入法消费的按键会触发提交或跳转。
 - 没有“完成/关闭”按钮；是否显示查找栏由调用方决定。
@@ -33,7 +33,7 @@ func CheckboxGroup(c *ui.Context, label string, items []CheckboxItem, opts Check

 ## 状态

-未选（Surface 底、ControlBorder 边）、悬停与按下（AccentText 边）、选中（酒红底、象牙白勾）、半选（酒红底、象牙白横线）、键盘聚焦（方框外焦点环）、禁用。行高不低于密度控件高度。
+未选（Surface 底、ControlBorder 边）、悬停与按下（AccentText 边）、选中（酒红底、象牙白勾；悬停与按下时底色加深、边框变为正文色）、半选（酒红底、象牙白横线）、键盘聚焦（方框外焦点环）、禁用。行高不低于密度控件高度。

 全选框：全部选中为选中，部分选中为半选，全不选为未选。点击时若可用项未全选则全部勾选，否则全部清除；禁用项保持不变。

@@ -37,7 +37,7 @@ if mujica.RadioGroup(c, &size, items, mujica.RadioGroupOptions{Label: "Size"}).C

 ## 状态

-未选（空心圆）、悬停与按下（AccentText 边）、选中（酒红实心圆与象牙白圆点）、键盘聚焦、禁用。
+未选（空心圆）、悬停与按下（AccentText 边）、选中（酒红实心圆与象牙白圆点；悬停与按下时底色加深、边框变为正文色）、键盘聚焦、禁用。

 ## 事件

@@ -49,4 +49,6 @@ Tab 进入组并落在已选项；Up/Down/Left/Right 移动并直接选择，循

 ## 限制

+- 每个选项以 `Value` 为键，选项重新排序后焦点仍跟随原来的值。
+
 - 方向键对横向与纵向组都同时响应上下左右（MyGo `RadioGroup` 固定使用 `Horizontal|Vertical`）。