BorderBeam 边框流光

一道渐变光沿容器边框循环流动，用于给卡片、容器等内容加一层灵动的视觉强调。

何时使用

• 想突出某个卡片 / 面板，让它在页面中更吸睛。
• 营销页、活动入口、AI 能力卡片等需要动态氛围感的场景。

基本使用

默认插槽放置被包裹的内容，流光会绕着容器边框流动。borderRadius 默认 8，与 c-card 圆角一致，直接包裹卡片即可严丝合缝；不传 color 时使用主题主色渐变。

自定义配色

通过 color 传入单个颜色字符串。

渐变停靠点

color 传入停靠点数组（percent 取值 0 ~ 100）可得到多色渐变光带。

内置配色预设

内置 6 套配色预设（Ocean / Sunset / Aurora / Forest / Ember / Nebula），从 @vaebe/ccui 导出 borderBeamPresets，直接把 preset.color 传给 color 即可。下方可切换预览。

调速

duration 控制跑完一圈的时长（秒），值越小越快。

多条流光

count 控制同时显示的流光数量。多条流光会沿路径均匀错开，不会在起点重叠。

外扩与圆角

outset 让流光层相对容器边缘向外扩展，borderWidth 调整光带粗细，borderRadius 决定边框环圆角；较小的 size 可以缩短光带，避免在紧凑卡片的拐角处形成过长尾迹。

继承真实边框

开启 asChild 后不会生成包装层，流光层会直接挂载到唯一的默认插槽元素中。未显式传入 outset 时，组件会读取目标元素四边的实际边框宽度；未显式传入 borderRadius 时，流光会继承目标元素的圆角，因此支持非对称圆角和 CSS 变量。

如果目标元素使用 overflow: hidden、clip、auto 或 scroll，外扩的子元素会被目标自身裁剪。组件会自动把流光收进内容边缘（outset 按 0 处理），保证流光可见；需要严格覆盖外侧边框时，请使用默认包装模式。

目标元素需要建立定位上下文（例如 position: relative），并且默认插槽只能包含一个最终渲染为 HTMLElement 的元素或单根组件。

Hover 控制

流光层使用 .ccui-border-beam__effect 类，可以通过普通 CSS 控制 hover 时的显示或暂停，不需要额外属性。

.beam-on-hover .ccui-border-beam__effect {
  opacity: 0;
  transition: opacity 0.2s;
}

.beam-on-hover:hover .ccui-border-beam__effect {
  opacity: 1;
}

size 使用限制

建议保持 size < 2 × min(容器宽度, 容器高度)。超过该范围时，光带可能同时覆盖两条相对边，视觉上不再像单条连续流光。

API

Props

参数	说明	类型	默认值
color	流光颜色，单色字符串或渐变停靠点数组；不传时用主题主色渐变	BorderBeamColor	-
outset	流光层相对容器边缘的外扩距离；asChild 下未显式传入则读取目标元素四边边框	number | string	0
borderWidth	边框 / 光带粗细（number 视为 px）	number | string	1
borderRadius	流光层圆角；asChild 下未显式传入则继承目标元素，可使用非对称 CSS 圆角	number | string	8
size	流光渐变层边长，同时控制拐角处的平滑转弯半径（number 视为 px）	number | string	100
duration	跑完一圈的时长（秒），必须大于 0	number	6
count	同时显示的流光数量，取大于等于 1 的整数	number	1
asChild	移除包装层，并把流光层挂载到唯一的默认插槽 HTMLElement；目标元素需要建立定位上下文	boolean	false

Slots

插槽名	说明
default	被流光包裹的内容

BorderBeam 类型定义

BorderBeamColor

export interface BorderBeamColorStop {
  /** 颜色值，支持任意 CSS 颜色 */
  color: string
  /** 渐变停靠位置，取值 0 ~ 100 */
  percent: number
}

export type BorderBeamColor = string | BorderBeamColorStop[]

内置预设

从 @vaebe/ccui 导出，按定义顺序提供 6 套配色：

import { borderBeamPresetKeys, borderBeamPresets } from '@vaebe/ccui'

// borderBeamPresetKeys: ['ocean', 'sunset', 'aurora', 'forest', 'ember', 'nebula']
// borderBeamPresets.ocean.color → BorderBeamColorStop[]

export interface BorderBeamPreset {
  key: string
  name: string
  color: BorderBeamColorStop[]
}