BorderBeam 流光边框

基础用法

示例加载中...

脉冲形态

Pulse 家族不旋转，光晕以约 30fps 的共享 rAF 循环呼吸；pulse-outside 的光晕渲染在内容层背后并向外扩散，因此需要不透明的子元素和自带的 1px 边框。

示例加载中...

组合示例

配色与主题

四种配色变体；mono 会自动关闭色相偏移动画。theme 决定光束针对深色还是浅色背景调色，auto 跟随系统 prefers-color-scheme。

<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>

交互契约

组件包裹插槽内容并叠加光束层；所有特效层均为 pointer-events: none，不影响插槽交互。
未指定 borderRadius 时，自动读取第一个插槽元素的 border-top-left-radius，检测失败回退到尺寸预设默认值。
active 切换触发淡入/淡出过渡，动画结束后分别发出 activate / deactivate 事件。
元素滚出视口（余量 256px）时动画自动暂停（data-paused），不会触发 activate/deactivate。
每个实例注入一段独立 <style>，选择器以实例 id（data-beam）隔离。
Pulse 家族在 prefers-reduced-motion: reduce 下停用呼吸驱动。

API

Props

属性名	类型	默认值	说明
`size`	`'sm' \| 'md' \| 'line' \| 'pulse-outside' \| 'pulse-inner'`	`'md'`	形态预设：旋转家族（sm/md/line）或脉冲家族。
`colorVariant`	`'colorful' \| 'mono' \| 'ocean' \| 'sunset'`	`'colorful'`	配色变体；`mono` 隐含 `staticColors`。
`theme`	`'dark' \| 'light' \| 'auto'`	`'dark'`	背景适配；`auto` 跟随系统偏好。
`strength`	`number`	`1`	特效整体强度（0-1），只影响光束层。
`duration`	`number`	`1.96` / `3.1` / `2.3`	动画周期秒数（rotate / line / pulse）。
`active`	`boolean`	`true`	是否播放，带淡入淡出过渡。
`borderRadius`	`number`	自动检测	光束圆角（px）。
`brightness`	`number`	按形态预设（`1.3`）	光晕亮度倍率。
`saturation`	`number`	`1.2`（暗色）	光晕饱和度倍率。
`hueRange`	`number`	`30`	色相偏移范围（度）；`line` 上限 13。
`staticColors`	`boolean`	`false`	关闭色相偏移动画。

Slots

插槽名	Props	说明
`default`	-	被包裹的内容；光束层渲染在其后。

Events

事件名	参数	说明
`activate`	-	淡入动画完成时触发。
`deactivate`	-	淡出动画完成时触发。

Exposed Methods

不暴露公开实例方法。

CSS Variables

变量	来源	说明
`--beam-strength`	`strength`	光束层整体不透明度（0-1，已钳制）。
`--pulse-glow-sx` / `--pulse-glow-sy`	内部测量	`pulse-outside` 光晕按元素尺寸的轴向缩放。
`--pulse-glow-boost`	消费方可选	脉冲光晕增益钩子，默认 `1`。

最佳实践

插槽内容自带背景色，且圆角与检测/指定的 borderRadius 一致，避免光束与内容边缘错位。
pulse-outside 需要不透明子元素和自带 1px 边框，并保证周围布局有溢出空间（overflow: visible）。
页面同屏多个实例时降低 strength 或放慢 duration；这是强注意力特效，一个视图区块保留一个即可。
浅色页面用 theme="light" 或 "auto"，暗色光束参数在浅背景上对比度不足。
光束层不参与命中测试，插槽内容自行处理 focus 样式。

审阅说明

已人工核对 packages/tuffex/packages/components/src/border-beam/ 下 index.ts、TxBorderBeam.vue、types.ts 与 border-beam.test.ts。
事件为 activate / deactivate，对应上游 React 版的 onActivate / onDeactivate 回调。

Source

Component source: packages/tuffex/packages/components/src/border-beam/src/TxBorderBeam.vue。
Types: packages/tuffex/packages/components/src/border-beam/src/types.ts。
Upstream: Jakubantalik/Libraries · border-beam（MIT）。
实测覆盖: Coverage: packages/tuffex/packages/components/src/border-beam/__tests__/border-beam.test.ts 验证插槽渲染、实例级样式注入、active 生命周期与 deactivate 事件、strength 钳制。

查看源码

packages/tuffex/packages/components/src/border-beam/index.ts