Banner (横幅)
贴在页面顶部的整宽公告条,一句话加可选的操作与关闭按钮;可以记住关闭状态,刷新后不再出现。
基础用法
点右侧的 × 关闭横幅,下面的内容会平滑上移。
Basic.vue
颜色与变体
Colors.vue
链接与操作
横幅里的链接自动沿用横幅的文字颜色并加下划线。
Actions.vue
紧凑尺寸
横幅一直显示时,在窄屏上用 sm 少占一截高度。
横幅一直显示时,在窄屏上用 sm 少占一截高度。
Compact.vue
一直显示的提示用 sm
size="sm" 的横幅高 32px,文字 text-xs。适合内容模式这类一直显示、不能关闭的提示:手机上一句话会折成好几行,sm 能少占一截高度。一次性的公告仍用默认的 md。sm 横幅的 #actions 里放 size="xs" 的按钮。
记住关闭状态
横幅显示中。
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. |
| size | "sm" | "md" | "md" | `md` is a 40px strip with `text-sm`. `sm` is a 32px strip with `text-xs` and tighter padding, for a standing notice (a content-mode reminder) that should not take a phone screen's worth of space once it wraps. In `sm`, put a `size="xs"` button in `#actions` so it fits the strip. |
| 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; } |