组件/BorderBeam 流光边框

BorderBeam 流光边框

沿边框游走或呼吸的光束包装器

Verified自 0.3.9

用法

旋转形态

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 跟随系统。
strengthnumber1光束层强度(0–1),不影响插槽内容。
durationnumber1.96 / 3.1 / 2.3周期秒数;默认值依次对应旋转、line、脉冲。
activebooleantrue是否播放;切换时淡入淡出。
borderRadiusnumber自动检测光束圆角(px)。
brightnessnumber按形态预设(1.3)光晕亮度倍率。
saturationnumber1.2(暗色)光晕饱和度倍率。
hueRangenumber30色相摆幅(度);line 上限 13。
staticColorsbooleanfalse关闭色相动画。

事件

事件名参数说明
activate-淡入结束时触发。
deactivate-淡出结束时触发。

插槽

插槽名Props说明
default-被包裹的内容。

CSS 变量

变量来源说明
--beam-strengthstrength光束层不透明度,钳制在 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