message 消息提示

胶囊形态的轻量提示。支持同 key 覆盖与 loading 类型。

基础用法

vue

<script setup>
import { message } from '@starriver/ui'

message.success('保存成功')
message.info('这是一条提示')
</script>

与 toast 的差别

两个都是命令式提示，message 多了两个能力：

	`toast`	`message`
同 key 覆盖	—	✅
`loading` 类型	—	✅
累积多个	都显示	同 key 只留最后一个

message 的定位是「会被反复触发的提示」—— 比如表单里的校验失败、批量操作的逐条结果。这类场景下不加控制的 toast 会在一秒内堆出十条，把屏幕盖住。

普通的单次提示用 toast 就够了。 只有确实需要覆盖时才用 message。

同 key 覆盖

// 第三个参数是 key
message.info('第 1 条', 3000, 'same')
message.info('第 2 条', 3000, 'same')   // ← 顶掉第 1 条
message.info('第 3 条', 3000, 'same')   // ← 顶掉第 2 条

屏幕上只会有一条。 这就是 key 的作用。

什么时候该用 key：

场景	key 建议
表单校验失败	用字段名，如 `'form-name'`，避免每个字段各弹一条
批量操作结果	用固定的 `'batch'`，只显示最新一条
网络错误	按错误类型，如 `'network'`
操作成功提示	不用 key——它们本来就该各显示各的

loading → 结果的替换

先显示加载中，完成后用同 key 替换成结果——视觉上是"原地变化"，而不是"消失一个、出现一个"。

function save() {
  // loading 的 key 是第 2 个参数
  message.loading('正在保存…', 'save')

  try {
    await api.save(data)
    // 结果的 key 是第 3 个参数 —— 必须带上，否则顶不掉上面那条 loading
    message.success('保存成功', 2000, 'save')
  } catch (e) {
    message.error(e.message, 3000, 'save')
  }
}

结果那一侧必须显式带上同一个 key

message.loading(msg, key) 之后，只有同样带 key 的调用才能顶掉它。

漏传的后果是：loading 被强制 duration: 0（进行中的状态无法预知何时结束，到点自动消失等于暗示"已完成"），于是它会一直转下去—— 而成功的提示会另起一条，两条互相矛盾的消息并排挂着。

这也是为什么结果的 key 是第 3 个参数而不是第 2 个：第 2 个位置留给了 duration。两处位置不同容易记混，统一写法可以用 message.keyed()：

message.keyed('save', { type: 'loading', message: '正在保存…' })
message.keyed('save', { type: 'success', message: '保存成功', duration: 2000 })

loading 不会自动消失（传 duration 也没用），必须由后续的 success / error 替换，或手动 close。

时长与关闭

message.info('3 秒后消失')            // 默认 3000ms
message.info('不自动消失', 0)          // 0 表示手动关
message.info('5 秒', 5000)

const id = message.info('这条')
message.close(id)
message.closeAll()

API

方法	参数	返回
`message.success(text, duration?, key?)`	文本、时长、覆盖键	id
`message.error(text, duration?, key?)`	同上	id
`message.warning(text, duration?, key?)`	同上	id
`message.info(text, duration?, key?)`	同上	id
`message.loading(text, key?)`	文本、覆盖键；不自动消失	id
`message.close(id)`	提示 id	—
`message.closeAll()`	—	—

也支持对象形式，用于更细的控制：

import { showMessage } from '@starriver/ui'

showMessage({
  type: 'success',
  message: '保存成功',
  duration: 3000,
  key: 'save'
})

无障碍

容器带 role="status" 与 aria-live="polite"；错误类型用 aria-live="assertive"（需要打断当前朗读）
同 key 覆盖对读屏用户也友好——它避免了同一句话被念十遍
与 toast 同样的时长建议：默认 3 秒对读屏用户偏短，重要信息应延长或改为手动关闭
提示不应包含唯一的操作入口（它会自动消失）

message 消息提示 ​

基础用法 ​

与 toast 的差别 ​

同 key 覆盖 ​

loading → 结果 的替换 ​

时长与关闭 ​

API ​

无障碍 ​