Merge branch 'worktree-agent-ad7403b5194d75449'
This commit is contained in:
110 files changed
+7707
-1
No files matched your search
@@ -0,0 +1,57 @@
|
||||
# 421 CalendarMonthView · 月视图
|
||||
|
||||
## 用途
|
||||
|
||||
按月显示事件格。每天最多显示若干行事件，其余折叠为“+N”，点击后在浮层中列出；事件可拖到其他日期改期。同一天时间重叠的事件并排放在同一行。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
events := exampleEvents(loc)
|
||||
month := mujica.YearMonth{Year: 2026, Month: time.October}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.CalendarMonthView(c, &month, events, mujica.CalendarMonthViewOptions{Location: loc})
|
||||
if ch, ok := r.Changed(); ok {
|
||||
fmt.Println("move", ch.ID, "to", ch.Start)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func CalendarMonthView(c *ui.Context, month *YearMonth, events []CalendarEvent, opts CalendarMonthViewOptions) CalendarViewResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Version` | `int` | 0 | 事件在原切片内被修改时须改变；换新切片会被自动发现。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日：跟随语言或周日、周一、周六。 |
|
||||
| `MaxPerDay` | `int` | 0（即 3） | 每天显示的事件行数，超出部分折叠为“+N”。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、聚焦（焦点环）、今日（圆形底色 + 加粗）、非本月（弱化）、拖动经过的日期（选中底色 + 内嵌框）、禁用；改期失败时下方显示错误。
|
||||
|
||||
## 事件
|
||||
|
||||
`Opened()` 返回被激活的事件 ID；`DayChosen()` 返回点击的日期；`Changed()` 返回 `CalendarMove` 变更（保持墙上时间与时长）。上一月/下一月直接修改 `*month`。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到达日期数字与事件块，方向键在其间移动。
|
||||
- Enter 或 Space 打开事件或选择日期。
|
||||
- 事件块上 Alt+←/→ 移动一天，Alt+↑/↓ 移动一周。
|
||||
- Escape 关闭“+N”浮层。
|
||||
|
||||
## 限制
|
||||
|
||||
- 拖动改期使用 MyGo 的 `Drag`/`Drop`；拖动预览是 MyGo 绘制的元素副本。
|
||||
- 时间按调用方给定的 `Location` 计算与显示；夏令时跳过或重复的墙上时间会报告，不自动移动。
|
||||
- 事件由调用方持有：视图只报告移动、调整与新建（`Changed()`），由调用方写回数据。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 422 CalendarWeekView · 周视图
|
||||
|
||||
## 用途
|
||||
|
||||
一周的时间网格，顶部为全天行。在空白处拖动新建事件，拖动事件块移动，拖动底边调整时长；重叠事件按列并排。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
events := exampleEvents(loc)
|
||||
week := mujica.Date{Year: 2026, Month: time.October, Day: 14}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.CalendarWeekView(c, &week, events, mujica.CalendarWeekViewOptions{Location: loc, SlotMinutes: 15})
|
||||
if ch, ok := r.Changed(); ok && ch.Kind == mujica.CalendarCreate {
|
||||
fmt.Println("new event", ch.Start, ch.End)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func CalendarWeekView(c *ui.Context, week *Date, events []CalendarEvent, opts CalendarWeekViewOptions) CalendarViewResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Version` | `int` | 0 | 事件在原切片内被修改时须改变；换新切片会被自动发现。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日：跟随语言或周日、周一、周六。 |
|
||||
| `SlotMinutes` | `int` | 0（即 30） | 拖动与键盘的时间格长度，须整除一小时。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 当前时间线的位置。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、聚焦列（时间格光标：选中底色 + 内嵌框）、拖动中（新建区域虚线框、被拖事件内嵌框）、今日表头、当前时间线、禁用；无法表示的时间显示错误。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 返回 `CalendarCreate`、`CalendarMove` 或 `CalendarResize`；`Opened()` 返回点击的事件；`DayChosen()` 返回点击的表头日期。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 聚焦某一天的列，↑/↓ 移动时间格光标，Enter 新建一格长的事件。
|
||||
- 事件块上 Alt+↑/↓ 按格移动，Alt+←/→ 移动一天，Alt+Shift+↑/↓ 调整结束时间。
|
||||
|
||||
## 限制
|
||||
|
||||
- 调整时长的底边手柄只有 6 DIP 高，低于 28 DIP 命中区域要求；同样的操作可用事件块上的 Alt+Shift+↑/↓ 完成。
|
||||
- 网格高 24 小时，默认滚动到 8:00；跨越 24 小时以上的事件放在全天行。
|
||||
- 时间按墙上时间排布，夏令时当天的重复或缺失小时不改变格高。
|
||||
- 时间按调用方给定的 `Location` 计算与显示；夏令时跳过或重复的墙上时间会报告，不自动移动。
|
||||
- 事件由调用方持有：视图只报告移动、调整与新建（`Changed()`），由调用方写回数据。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 423 CalendarDayView · 日视图
|
||||
|
||||
## 用途
|
||||
|
||||
单日时间网格；重叠事件按列并排，交互与周视图相同。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
events := exampleEvents(loc)
|
||||
day := mujica.Date{Year: 2026, Month: time.October, Day: 14}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if id, ok := mujica.CalendarDayView(c, &day, events, mujica.CalendarDayViewOptions{Location: loc}).Opened(); ok {
|
||||
fmt.Println("open", id)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func CalendarDayView(c *ui.Context, day *Date, events []CalendarEvent, opts CalendarDayViewOptions) CalendarViewResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Version` | `int` | 0 | 事件在原切片内被修改时须改变；换新切片会被自动发现。 |
|
||||
| `SlotMinutes` | `int` | 0（即 30） | 拖动与键盘的时间格长度，须整除一小时。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 当前时间线的位置。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
同周视图。
|
||||
|
||||
## 事件
|
||||
|
||||
同周视图：`Changed()`、`Opened()`、`DayChosen()`；前一天/后一天修改 `*day`。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 同周视图。
|
||||
|
||||
## 限制
|
||||
|
||||
- 与周视图共用网格实现。
|
||||
- 时间按调用方给定的 `Location` 计算与显示；夏令时跳过或重复的墙上时间会报告，不自动移动。
|
||||
- 事件由调用方持有：视图只报告移动、调整与新建（`Changed()`），由调用方写回数据。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 424 AgendaView · 日程列表
|
||||
|
||||
## 用途
|
||||
|
||||
按日分组的日程列表，日期标题在滚动时固定在顶部；只构建可见行，适合大量事件。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
events := exampleEvents(loc)
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
opts := mujica.AgendaViewOptions{Location: loc, From: mujica.Date{Year: 2026, Month: time.October, Day: 12}, Days: 14}
|
||||
if id, ok := mujica.AgendaView(c, events, opts).Opened(); ok {
|
||||
fmt.Println("open", id)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func AgendaView(c *ui.Context, events []CalendarEvent, opts AgendaViewOptions) CalendarViewResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Version` | `int` | 0 | 事件在原切片内被修改时须改变；换新切片会被自动发现。 |
|
||||
| `From` | `Date` | 零值（今天） | 列表的第一天。 |
|
||||
| `Days` | `int` | 0（即 30） | 列出的天数。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、聚焦、今日标题（强调色 + “今天”）、空状态、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Opened()` 返回被激活事件的 ID。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入列表，↑/↓ 在事件间移动，Enter 打开。
|
||||
|
||||
## 限制
|
||||
|
||||
- 跨越多天的事件在每一天下各列一次。
|
||||
- 时间按调用方给定的 `Location` 计算与显示；夏令时跳过或重复的墙上时间会报告，不自动移动。
|
||||
- 事件由调用方持有：视图只报告移动、调整与新建（`Changed()`），由调用方写回数据。
|
||||
@@ -0,0 +1,52 @@
|
||||
# 425 YearView · 年视图
|
||||
|
||||
## 用途
|
||||
|
||||
十二个月的小日历，每天下方用 1～3 个点表示事件密度，读屏会读出事件数量。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
events := exampleEvents(loc)
|
||||
year := 2026
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if day, ok := mujica.YearView(c, &year, events, mujica.YearViewOptions{Location: loc}).DayChosen(); ok {
|
||||
fmt.Println("go to", day)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func YearView(c *ui.Context, year *int, events []CalendarEvent, opts YearViewOptions) CalendarViewResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Version` | `int` | 0 | 事件在原切片内被修改时须改变；换新切片会被自动发现。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日：跟随语言或周日、周一、周六。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停、聚焦、今日（底色 + 加粗）、密度点（1～2 项一点、3～5 项两点、6 项以上三点）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`DayChosen()` 返回被激活的日期；上一年/下一年及跨年移动修改 `*year`。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入日期，←/→ 移动一天，↑/↓ 移动一周，PageUp/PageDown 移动一月，可跨年。
|
||||
- Enter 选择。
|
||||
|
||||
## 限制
|
||||
|
||||
- 密度不只靠颜色：用点数区分，并写入标签。
|
||||
- 时间按调用方给定的 `Location` 计算与显示；夏令时跳过或重复的墙上时间会报告，不自动移动。
|
||||
- 事件由调用方持有：视图只报告移动、调整与新建（`Changed()`），由调用方写回数据。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 426 EventChip · 事件块
|
||||
|
||||
## 用途
|
||||
|
||||
显示单个事件：左侧色条、标题与时间，超出时截断为省略号。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
ev := exampleEvents(loc)[0]
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.EventChip(c, ev, mujica.EventChipOptions{Location: loc}).Clicked() {
|
||||
fmt.Println("open", ev.ID)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func EventChip(c *ui.Context, ev CalendarEvent, opts EventChipOptions) *ui.Element`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Inline` | `bool` | false | 开始时间与标题放在一行。 |
|
||||
| `Selected` | `bool` | false | 选中：选中底色 + 内嵌框。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、悬停与按下（色调加深）、聚焦、选中、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
返回的元素可用 `.Clicked()` 判断激活。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 聚焦，Enter 或 Space 激活。
|
||||
|
||||
## 限制
|
||||
|
||||
- 事件颜色来自主题：AccentText、Info、Success、Warning、Danger、TextMuted，均在两套主题下对 Surface 达到 3:1；Ornament 在浅色主题下仅 2.8:1，不纳入。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 427 EventEditor · 事件编辑器
|
||||
|
||||
## 用途
|
||||
|
||||
编辑事件的标题、时间、地点、参与者、提醒与重复规则。编辑的是副本，点击保存并校验通过后才写回。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
ev := exampleEvents(loc)[0]
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.EventEditor(c, &ev, mujica.EventEditorOptions{Location: loc})
|
||||
if r.Saved() {
|
||||
fmt.Println("saved", ev.Title, ev.Start)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func EventEditor(c *ui.Context, ev *CalendarEvent, opts EventEditorOptions) EventEditorResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日：跟随语言或周日、周一、周六。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、字段错误（保存后显示：缺少标题、结束早于开始、重复规则问题）、全天模式（只选日期）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Saved()`：校验通过并写回 `*ev`；`Canceled()`：丢弃草稿。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 在字段间移动，各字段保留自身按键；保存与取消为按钮。
|
||||
|
||||
## 限制
|
||||
|
||||
- 全天事件保存时规整为当天零点到次日零点。
|
||||
- 参与者按姓名添加，新参与者状态为“未回复”。
|
||||
@@ -0,0 +1,52 @@
|
||||
# 428 EventPopover · 事件浮层
|
||||
|
||||
## 用途
|
||||
|
||||
在锚点旁显示事件摘要：时间、地点、重复、参与者与提醒，并提供编辑与删除入口。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
loc := time.Local
|
||||
ev := exampleEvents(loc)[0]
|
||||
open := false
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
chip := mujica.EventChip(c, ev, mujica.EventChipOptions{Location: loc})
|
||||
if chip.Clicked() {
|
||||
open = true
|
||||
}
|
||||
r := mujica.EventPopover(c, chip, &open, ev, mujica.EventPopoverOptions{Location: loc})
|
||||
if r.Delete() {
|
||||
fmt.Println("delete", ev.ID)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func EventPopover(c *ui.Context, anchor *ui.Element, open *bool, ev CalendarEvent, opts EventPopoverOptions) EventPopoverResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `ReadOnly` | `bool` | false | 隐藏编辑与删除。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
|
||||
## 状态
|
||||
|
||||
打开（160 ms 淡入，减少动画时直接显示）、只读、禁用（自动关闭）。
|
||||
|
||||
## 事件
|
||||
|
||||
`Edit()`、`Delete()` 报告点击并关闭浮层；删除只报告，确认由调用方决定。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到达关闭、删除与编辑；Escape 或点击外部关闭。
|
||||
|
||||
## 限制
|
||||
|
||||
- 浮层尺寸受窗口限制，内容超出时滚动。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 429 CurrentTimeIndicator · 当前时间线
|
||||
|
||||
## 用途
|
||||
|
||||
填满父元素，按当前时间在当天中的比例画一条横线，用于时间网格。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
ui.Box(c).Size(200, 240).Children(func() {
|
||||
mujica.CurrentTimeIndicator(c, mujica.CurrentTimeIndicatorOptions{Location: time.Local})
|
||||
})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func CurrentTimeIndicator(c *ui.Context, opts CurrentTimeIndicatorOptions) *ui.Element`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Day` | `Date` | 零值（今天） | 父元素自上而下代表的日期；不是今天时不显示。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 当前时间；固定后不再定时刷新，便于测试。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
|
||||
## 状态
|
||||
|
||||
显示（Danger 色线与菱形）、不在当天时隐藏。
|
||||
|
||||
## 事件
|
||||
|
||||
无事件；读屏通过标签读出当前时间。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 不可聚焦。
|
||||
|
||||
## 限制
|
||||
|
||||
- 仅在被构建（可见）时用 `c.After` 预约下一分钟的重绘；隐藏后不再预约，自动停止。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 430 RecurrenceEditor · 重复规则编辑器
|
||||
|
||||
## 用途
|
||||
|
||||
选择每天、每周、每月、每年或自定义间隔，每周可选星期，并设置结束条件（永不、次数、日期）。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
rule := mujica.Recurrence{Unit: mujica.RepeatWeekly, Interval: 1, Weekdays: []time.Weekday{time.Monday}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.RecurrenceEditor(c, &rule, mujica.RecurrenceEditorOptions{Start: mujica.Date{Year: 2026, Month: time.October, Day: 5}})
|
||||
if r.Changed() && r.Problem() == "" {
|
||||
fmt.Println(mujica.RecurrenceSummary(c, rule))
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func RecurrenceEditor(c *ui.Context, rule *Recurrence, opts RecurrenceEditorOptions) RecurrenceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Start` | `Date` | 零值 | 首次发生日期；结束日期不能早于它，每周规则默认取其星期。 |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日：跟随语言或周日、周一、周六。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、自定义（显示间隔与单位）、每周（星期按钮）、结束条件、问题提示（无星期、次数小于 1、结束日期过早）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告规则变化；`Problem()` 返回当前不可保存的原因；`RecurrenceSummary` 生成本地化描述。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 在重复选择、间隔、星期与结束条件之间移动，各控件保留自身按键。
|
||||
|
||||
## 限制
|
||||
|
||||
- 只描述规则，不展开具体日期。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 431 AvailabilityPicker · 空闲时段选择
|
||||
|
||||
## 用途
|
||||
|
||||
按天与时间的网格，拖动涂抹自己的空闲时段，并显示其他人在每个时段的空闲人数。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
days := []mujica.Date{{Year: 2026, Month: time.October, Day: 12}, {Year: 2026, Month: time.October, Day: 13}}
|
||||
mine := [][]bool{make([]bool, 18), make([]bool, 18)}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.AvailabilityPicker(c, &mine, mujica.AvailabilityPickerOptions{Days: days}).Changed() {
|
||||
fmt.Println("availability changed")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func AvailabilityPicker(c *ui.Context, mine *[][]bool, opts AvailabilityPickerOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Days` | `[]Date` | 必填 | 网格的列。 |
|
||||
| `From / To` | `int` | 9 / 18 | 起止小时，0 ≤ From < To ≤ 24。 |
|
||||
| `SlotMinutes` | `int` | 0（即 30） | 时段长度。 |
|
||||
| `Others` | `[]AvailabilityPerson` | nil | 其他人的空闲表，维度须与值一致。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、自己空闲（选中底色 + 勾）、他人空闲（数量 + 条形）、全员可行（加粗强调）、键盘光标（内嵌框）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告自己的空闲表变化。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 聚焦网格，方向键移动光标，Space 或 Enter 切换。
|
||||
|
||||
## 限制
|
||||
|
||||
- 值的维度为 [天][时段]，与选项不符时 panic。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 432 TimezoneSelect · 时区选择
|
||||
|
||||
## 用途
|
||||
|
||||
按城市名或偏移搜索 IANA 时区，常用时区置顶，显示当前偏移。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
zone := "Asia/Shanghai"
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.TimezoneSelect(c, &zone, mujica.TimezoneSelectOptions{}).Changed() {
|
||||
fmt.Println("zone", zone)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func TimezoneSelect(c *ui.Context, zone *string, opts TimezoneSelectOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Zones` | `[]string` | 内置世界列表 | 可选时区。 |
|
||||
| `Common` | `[]string` | 内置常用列表 | 置顶的常用时区。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 计算偏移所用的时刻（夏令时会改变偏移）。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
关闭、打开（搜索框 + 分组列表）、高亮、已选（勾）、无结果、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告选中的时区变化。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Enter、Space 或 ↓ 打开；输入搜索；↑/↓ 移动高亮；Enter 选择；Escape 关闭。
|
||||
|
||||
## 限制
|
||||
|
||||
- 内嵌 `time/tzdata`，离线可用；未知时区名 panic。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 433 ReminderPicker · 提醒选择
|
||||
|
||||
## 用途
|
||||
|
||||
多选事件前的提醒时间，按选项顺序保存。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
reminders := []time.Duration{15 * time.Minute}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.ReminderPicker(c, &reminders, mujica.ReminderPickerOptions{Max: 3}).Changed() {
|
||||
fmt.Println("reminders", reminders)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func ReminderPicker(c *ui.Context, value *[]time.Duration, opts ReminderPickerOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Choices` | `[]time.Duration` | 0、5 分、15 分、30 分、1 时、1 天、1 周 | 可选的提前量，须为整分钟且不重复。 |
|
||||
| `Max` | `int` | 0（不限） | 最多选择的数量，达到后其余选项禁用。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、选中（选中底色 + 下划线标记）、达到上限的禁用项、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告选择变化。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入列表，↑/↓ 移动，Space 切换。
|
||||
|
||||
## 限制
|
||||
|
||||
- 只支持事件开始前的提醒；提前量须为整分钟，否则 panic。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 434 AttendeeList · 参与者列表
|
||||
|
||||
## 用途
|
||||
|
||||
列出参与者、头像、邮箱与回复状态（文字 + 图标），顶部汇总各状态人数。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
people := []mujica.Attendee{{Name: "Sakiko", Status: mujica.AttendeeAccepted, Organizer: true}, {Name: "Mutsumi"}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if i, ok := mujica.AttendeeList(c, people, mujica.AttendeeListOptions{Removable: true}).Removed(); ok {
|
||||
people = append(people[:i], people[i+1:]...)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func AttendeeList(c *ui.Context, attendees []Attendee, opts AttendeeListOptions) AttendeeListResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Removable` | `bool` | false | 除组织者外显示移除按钮。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
接受、待定、拒绝、未回复（各有图标与文字）、组织者、可选、空状态、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Removed()` 返回被移除者的下标，由调用方从切片中删除。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到达各移除按钮，Enter 移除。
|
||||
|
||||
## 限制
|
||||
|
||||
- 回复状态不由组件修改。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 435 WeekPicker · 周选择器
|
||||
|
||||
## 用途
|
||||
|
||||
选择整周：悬停时预览整周，值为该周第一天。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
var week mujica.Date
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.WeekPicker(c, &week, mujica.WeekPickerOptions{WeekStart: mujica.WeekStartMonday, Clearable: true}).Changed() {
|
||||
fmt.Println("week of", week)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func WeekPicker(c *ui.Context, value *Date, opts WeekPickerOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日：跟随语言或周日、周一、周六。 |
|
||||
| `Min / Max` | `Date` | 零值 | 所选周必须落在范围内。 |
|
||||
| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期。 |
|
||||
| `Clearable` | `bool` | false | 显示清空按钮。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
关闭、打开（整周预览带、已选周）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告选中周变化。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Enter、Space 或 ↓ 打开；方向键移动；Enter 选择所在周；Escape 关闭。
|
||||
|
||||
## 限制
|
||||
|
||||
- 值不是周起始日时 panic；更换周起始日后由调用方重设值。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 436 DurationPicker · 时长选择器
|
||||
|
||||
## 用途
|
||||
|
||||
以时、分、秒三个数字框编辑时长，并检查范围。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
length := 90 * time.Minute
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
opts := mujica.DurationPickerOptions{Min: 15 * time.Minute, Max: 8 * time.Hour}
|
||||
if mujica.DurationPicker(c, &length, opts).Changed() {
|
||||
fmt.Println("length", length)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func DurationPicker(c *ui.Context, value *time.Duration, opts DurationPickerOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Seconds` | `bool` | false | 显示秒字段；关闭时值须为整分钟。 |
|
||||
| `Min / Max` | `time.Duration` | 0 / 99 时 59 分 59 秒 | 允许的范围。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
默认、聚焦、超出范围（错误说明，值不写入）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告合法的新时长。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 在三个字段间移动；↑/↓ 步进；键入数字后 Enter。
|
||||
|
||||
## 限制
|
||||
|
||||
- 超出范围的输入保留并报告，不会被夹取。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 437 CronEditor · Cron 编辑器
|
||||
|
||||
## 用途
|
||||
|
||||
编辑标准 5 字段 cron 表达式，逐字段解释、就地报告错误，并预览接下来的运行时间。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
expr := "0 9 * * MON-FRI"
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.CronEditor(c, &expr, mujica.CronEditorOptions{Location: time.Local}).Changed() {
|
||||
if _, err := mujica.ParseCron(expr); err == nil {
|
||||
fmt.Println("schedule", expr)
|
||||
}
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func CronEditor(c *ui.Context, expr *string, opts CronEditorOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 预览的起点。 |
|
||||
| `Runs` | `int` | 0（即 5） | 预览的次数。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
有效（字段卡片 + 运行时间）、错误（出错字段红框 + 说明，不显示预览）、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告表达式文本变化；`ParseCron` 可单独校验并计算 `Next`。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 在表达式框中输入；解释与预览随输入更新。
|
||||
|
||||
## 限制
|
||||
|
||||
- 支持列表、范围、步长、`*` 与月份/星期英文缩写；日与星期同时受限时任一匹配即运行（cron 惯例）。
|
||||
- 夏令时跳过的时间不运行；重复的时间取第一次并标注。
|
||||
- 只搜索未来五年。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 438 RelativeTime · 相对时间
|
||||
|
||||
## 用途
|
||||
|
||||
把时间显示为“3 分钟前”“2 天后”，并在提示与标签中给出精确时间。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
posted := time.Date(2026, time.October, 5, 9, 0, 0, 0, time.Local)
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.RelativeTime(c, posted, mujica.RelativeTimeOptions{Location: time.Local})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func RelativeTime(c *ui.Context, t time.Time, opts RelativeTimeOptions) *ui.Element`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Location` | `*time.Location` | 必填 | 切分日期与显示时间所用的时区；为 nil 时 panic，不做隐式 UTC 转换。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 固定当前时间并停止刷新。 |
|
||||
| `Hour12` | `bool` | false | 12 小时制显示时间。 |
|
||||
|
||||
## 状态
|
||||
|
||||
刚刚、分钟、小时、天、月、年。
|
||||
|
||||
## 事件
|
||||
|
||||
无事件。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 不可聚焦；精确时间写在标签与提示中。
|
||||
|
||||
## 限制
|
||||
|
||||
- 刷新频率随距离变化：2 分钟内每秒、2 小时内每分钟、更远每小时；仅在可见时用 `c.After` 预约，隐藏即停止。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 439 Countdown · 倒计时
|
||||
|
||||
## 用途
|
||||
|
||||
显示距截止时间的剩余时间，归零时报告一次并朗读提示。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
deadline := time.Date(2026, time.December, 31, 23, 59, 59, 0, time.Local)
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.Countdown(c, deadline, mujica.CountdownOptions{}).Finished() {
|
||||
fmt.Println("happy new year")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func Countdown(c *ui.Context, deadline time.Time, opts CountdownOptions) CountdownResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Format` | `CountdownFormat` | `CountdownClock` | 时钟格式 01:02:03 或文字格式“1 小时 2 分 3 秒”。 |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 固定当前时间并停止刷新。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
计时中、归零（强调色）。
|
||||
|
||||
## 事件
|
||||
|
||||
`Finished()` 在每个截止时间归零的那一帧报告一次。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 不可聚焦；归零时通过 `Announce` 通知读屏。
|
||||
|
||||
## 限制
|
||||
|
||||
- 仅在可见时每秒用 `c.After` 预约重绘，隐藏或归零后停止。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 440 Stopwatch · 秒表
|
||||
|
||||
## 用途
|
||||
|
||||
秒表：开始、暂停、继续、计次与复位，计次列表显示单圈与累计时间。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
var sw mujica.StopwatchState
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.Stopwatch(c, &sw, mujica.StopwatchOptions{}).Changed() {
|
||||
fmt.Println("laps", len(sw.Laps))
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`func Stopwatch(c *ui.Context, s *StopwatchState, opts StopwatchOptions) ChoiceResult`
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Now` | `time.Time` | 零值（系统时钟） | 固定当前时间并停止刷新。 |
|
||||
| `Disabled` | `bool` | false | 禁用：不响应点击、拖动与快捷键，弹层随之关闭。 |
|
||||
| `Label` | `string` | 内置文案 | 辅助技术读出的名称。 |
|
||||
|
||||
## 状态
|
||||
|
||||
未开始、运行中、暂停（显示“继续”）、有计次、禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
`Changed()` 报告开始、暂停、计次或复位；`StopwatchState.Elapsed` 与 `Laps` 读取结果。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到达开始/暂停、计次与复位，Enter 或 Space 按下。
|
||||
|
||||
## 限制
|
||||
|
||||
- 运行且可见时每 100 ms 用 `c.After` 预约重绘；暂停或隐藏后停止。
|
||||
Reference in new issue
Block a user