BorderBeam 流光边框
沿边框游走或呼吸的光束包装器
用法
旋转形态
size 取 sm、md 或 line;line 只沿底边游走。
Loading demo...
脉冲形态
pulse-inner 在边框内呼吸;pulse-outside 从内容背后向外扩散,子元素须不透明并自带 1px 边框。
Loading demo...
配色与主题
colorVariant 有四种配色;theme 按背景深浅调色,auto 跟随系统。
<template>
<TxBorderBeam color-variant="ocean" theme="light">
<div class="card">ocean · light</div>
</TxBorderBeam>
<TxBorderBeam color-variant="sunset" :strength="0.7">
<div class="card">sunset · 70%</div>
</TxBorderBeam>
</template>
节奏
duration 是一圈游走或一次呼吸的秒数;hueRange 限定色相摆幅,staticColors 冻结色相。
<template>
<TxBorderBeam :duration="4" :hue-range="60">
<div class="card">慢速 · 大色相摆幅</div>
</TxBorderBeam>
<TxBorderBeam static-colors>
<div class="card">静止配色</div>
</TxBorderBeam>
</template>
最佳实践
- 插槽内容自带背景,圆角与
borderRadius一致。 pulse-outside的周围要留出溢出空间(overflow: visible)。- 一个区块只放一个光束;默认的色相动画会让光束的滤镜每帧重绘,同屏多个时控制数量,
staticColors可关闭这项动画。 - 浅色页面用
theme="light"或"auto";默认的深色参数在浅色背景上对比不足。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
size | 'sm' | 'md' | 'line' | 'pulse-outside' | 'pulse-inner' | 'md' | 形态预设:旋转(sm、md、line)或脉冲。 |
colorVariant | 'colorful' | 'mono' | 'ocean' | 'sunset' | 'colorful' | 配色;mono 同时冻结色相。 |
theme | 'dark' | 'light' | 'auto' | 'dark' | 按背景深浅调色;auto 跟随系统。 |
strength | number | 1 | 光束层强度(0–1),不影响插槽内容。 |
duration | number | 1.96 / 3.1 / 2.3 | 周期秒数;默认值依次对应旋转、line、脉冲。 |
active | boolean | true | 是否播放;切换时淡入淡出。 |
borderRadius | number | 自动检测 | 光束圆角(px)。 |
brightness | number | 按形态预设(1.3) | 光晕亮度倍率。 |
saturation | number | 1.2(暗色) | 光晕饱和度倍率。 |
hueRange | number | 30 | 色相摆幅(度);line 上限 13。 |
staticColors | boolean | false | 关闭色相动画。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
activate | - | 淡入结束时触发。 |
deactivate | - | 淡出结束时触发。 |
插槽
| 插槽名 | Props | 说明 |
|---|---|---|
default | - | 被包裹的内容。 |
CSS 变量
| 变量 | 来源 | 说明 |
|---|---|---|
--beam-strength | strength | 光束层不透明度,钳制在 0–1。 |
--pulse-glow-sx / --pulse-glow-sy | 内部测量 | pulse-outside 光晕按元素尺寸的轴向缩放。 |
--pulse-glow-boost | 消费方可选 | 脉冲光晕增益,默认 1。 |
概述
- 特效层均为
pointer-events: none,不拦截插槽交互,焦点样式由插槽内容提供。 - 未设
borderRadius时读取首个插槽元素的border-top-left-radius,读不到则用形态预设值。 - 滚出视口(余量 256px)时暂停动画,不派发
activate/deactivate。 - 减少动态效果时,脉冲形态停止呼吸。
技术实现
- 每个实例注入一段以
data-beam隔离的<style>;脉冲形态由共享的约 30fps rAF 循环驱动。 styles.ts与pulse-driver.ts移植自 Jakubantalik/Libraries · border-beam(MIT © Jakub Antalik)。- 源码:
packages/tuffex/packages/components/src/border-beam/。
查看源码
packages/tuffex/packages/components/src/border-beam/index.ts