## 42 · 消息通知 Message

### 42.1 用途
在页面**顶部**给一条不打断操作的结果提示（提交成功、网络异常、库存告警、操作回执）。移动端与桌面端的关键差别是**不阻断**：桌面端顶部提示常做成整条横幅、推进页面布局；触屏上页面本身就是有限的可视区域，横幅会把内容挤下去并引发重排，所以这条消息**浮在内容之上**（`position: fixed`）且**不吃手势**（层自身 `pointer-events: none`），用户读完继续操作，页面不跳。它与轻提示 Toast 的分工是：Toast 占据视口中央、用于「结果就是你此刻唯一关心的事」；Message 贴在顶部一条、用于「结果要告诉你，但不该拦着你」。

### 42.2 结构（anatomy）
- `message`：消息层根元素，顶部固定的纵向列表容器；`pointer-events: none` 让下方页面照常可点
- `item`：单条消息，一行「图标 + 文字（+ 可选关闭）」，带 `role="status"` 与 `aria-live="polite"`
- `icon`：语气图标（装饰），`aria-hidden="true"`，语义由文字承担
- `text`：消息文字，超长换行，不截断
- `close`：可选的关闭按钮（原生 `button`，热区 44px）

### 42.3 变体维度
- `tone`：`info`（信息）/ `success`（成功）/ `warning`（警告）/ `error`（错误）—— 图标字形与侧边描边同族，文字保持正文色
- `closable`：`false`（读完自己消失）/ `true`（右侧出现关闭按钮）

### 42.4 状态
- closed：收起（`opacity: 0` + 上移 100%，不可见）
- open：展开（`is-open`，滑下淡入 240ms）

### 42.5 交互与触控
- **两种用法，API 只暴露组件形态**：
  - **组件形态**（本组件提供的接口）：受控 `open` + 内容 props；`duration` 到点回传 `close`，由宿主决定是否收起
  - **命令式调用**（宿主侧组装）：宿主维护一个消息数组与定时器，把 `open` / `tone` / `text` 逐个喂给组件实例 —— 命令式 API 需要单例容器、跨端定时器与「销毁后仍在计时的定时器」治理，属宿主或框架层职责，组件不提供全局方法（规格 §42.7）
- 消息层不吃手势（根 `pointer-events: none`），**只有关闭按钮自己**接收手势（`pointer-events: auto`）——因此顶部有消息时，下方页面仍可正常点击与滚动
- 自动消失时长由**宿主**决定：组件没有默认时长之外的隐式行为，`duration=0` 表示不自动关闭（需要用户读完的长文案）
- 入场从上滑下并淡入 240ms（`--kole-m-duration-slide`），减少动态偏好下瞬时切换
- 多条并列时纵向排列，新的追加在下方；**同屏条数上限与超出后的合并策略由宿主决定**（规格 §42.7）

### 42.6 无障碍
- 每条消息 `role="status"` + `aria-live="polite"`：读屏朗读一次，不打断用户当前操作（不用 `assertive`，那会打断朗读）
- 语气图标 `aria-hidden="true"`，**语义全部由文字承担**（颜色不是唯一的信息通道：图标字形与描边同时变化）
- 关闭按钮是原生 `button` 并带 `aria-label`（「关闭消息」），可用 Tab 聚焦、Enter 触发
- 消息不抢焦点：出现时不移动焦点，用户正在输入的内容不受影响

### 42.7 doNotInvent
- 自动关闭的默认时长与「超时后是否保留」的策略
- 多条消息的排队、合并、去重与同屏上限
- 命令式全局方法（`Message.success()` 这类）与其单例容器
- 消息内的操作按钮与跳转链接（需要动作时请用通知栏或对话框）

### 42.8 unknowns
- `tone=warning` 与 `error` 是否需要不同的停留时长（当前统一由宿主传 `duration`）
- 顶部多条同时出现时是否该限制为最多两条（当前不限，由宿主控制）
- 是否需要在消息层上提供「点整条跳详情」的交互（当前只有可选的关闭按钮可点）

---