Banner (横幅)
贴在页面顶部的整宽公告条,一句话加可选的操作与关闭按钮;可以记住关闭状态,刷新后不再出现。
基础用法
点右侧的 × 关闭横幅,下面的内容会平滑上移。
Basic.vue
颜色与变体
Colors.vue
链接与操作
横幅里的链接自动沿用横幅的文字颜色并加下划线。
Actions.vue
记住关闭状态
横幅显示中。
Persist.vue
服务端渲染也不会闪
设置 storageKey 后,关闭状态写进 localStorage。服务端读不到 localStorage,所以横幅前面会渲染一段很短的内联脚本:浏览器解析到它时横幅还没画出来,已关闭的横幅在第一帧就是隐藏的,不闪、不跳。每条公告用一个新的 storageKey,关过旧公告的人会重新看到新公告。站点的 CSP 禁止内联脚本时,传入 nonce。
也可以用 Cookie
不设 storageKey,把 v-model 绑到 Nuxt 的 useCookie 上,服务端就能直接不渲染已关闭的横幅,连脚本都不需要。代价是页面 HTML 因人而异,不能再整页缓存到 CDN 或预渲染。
放在哪里
页面最上方,随页面滚走
把 KunBanner 放在布局的第一个元素,在吸顶导航栏之上。它在正常文档流里,不固定、不吸顶:吸顶的横幅会一直挡住页面内容,键盘聚焦的元素可能被它盖住(WCAG 2.4.11)。同一页面只放一条。它是一个带名字的 region 地标,不是 role=alert —— 随页面一起到达的内容不会被 alert 播报,页面加载后插入的又会打断读屏。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| ariaLabel | string | locale banner.label | Accessible name of the banner's region landmark. |
| className | string | "" | |
| closable | boolean | true | Draw a close button. Closing sets `v-model` to `false` and emits `close`; the banner collapses and the page below moves up. |
| color | KunUIColor | "primary" | Semantic colour of the strip. |
| icon | string | "" | Bundled icon name shown before the text, e.g. `lucide:info`. Only the icons compiled into ui-core exist — an unbundled name renders nothing. |
| modelValue | boolean | true | Whether the banner is shown. Starts open when unbound; with `storageKey`, a dismissal stored by an earlier visit sets it to `false` after mount. |
| nonce | string | — | CSP nonce for that inline script. Under a `script-src` that forbids inline scripts and has no nonce for it, a closed banner shows until hydration removes it. |
| storageKey | string | "" | Remember the open state in `localStorage` under this key, so a banner the user closed stays closed after a reload, and setting `v-model` back to `true` clears the record. Give each announcement its own key: a new key shows again to everyone who closed the old one. Characters other than letters, digits, `-` and `_` become `-`. A small inline script rendered in front of the banner hides a closed one before first paint, so a server-rendered page neither flashes it nor shifts. |
| text | string | "" | The one sentence the banner carries. For markup (a link, bold text) use the default slot, which renders in its place. |
| variant | "flat" | "solid" | "solid" | `solid` fills the strip with the colour and a contrast-correct foreground; `flat` is a soft tint with coloured text. |
事件
| 事件 | 回调参数 |
|---|---|
| close | — |
| update:modelValue | value: boolean |
插槽
| 插槽 | 作用域 |
|---|---|
| #actions | { dismiss: () => void; } |
| #default | { dismiss: () => void; } |