BorderBeam 边框流光

为容器边框提供持续流动的装饰性高亮效果，适合登录面板、推荐卡片、重点 CTA 区域等场景。

为容器边框提供持续流动的装饰性高亮效果。

何时使用

  • 需要强化某个容器的视觉关注度，但又不希望引入业务状态语义时。
  • 适合登录面板、推荐卡片、AI 模块、重点 CTA 区域等场景。
  • 它是装饰性效果，不应替代焦点态、校验态或业务状态边框。

导入

import { BorderBeam } from "@reglow/reui";

代码演示

基础用法

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <BorderBeam>
    <div class="w-80 p-6 rounded-lg border bg-card shadow-sm">
      <h3 class="text-lg font-medium mb-2">边框流光效果</h3>
      <p class="text-sm text-muted-foreground">这是一个带有流光边框的容器</p>
    </div>
  </BorderBeam>
</template>

自定义颜色

通过 color 属性设置流光颜色，支持单色字符串或渐变停靠点数组。

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <!-- 单色 -->
  <BorderBeam color="#ff6b00">
    <div class="w-80 p-6 rounded-lg border bg-card shadow-sm">
      <p>橙色流光</p>
    </div>
  </BorderBeam>

  <!-- 渐变色 -->
  <BorderBeam
    :color="[
      { color: '#ff0000', percent: 0 },
      { color: '#00ff00', percent: 50 },
      { color: '#0000ff', percent: 100 },
    ]"
  >
    <div class="w-80 p-6 rounded-lg border bg-card shadow-sm">
      <p>渐变流光</p>
    </div>
  </BorderBeam>
</template>

外扩距离

通过 outset 设置流光层相对容器边缘的外扩距离。

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <!-- 遇到裁剪容器时设为 0 -->
  <div class="overflow-hidden rounded-lg">
    <BorderBeam :outset="0">
      <div class="w-80 p-6 border bg-card">
        <p>无外扩流光</p>
      </div>
    </BorderBeam>
  </div>

  <!-- 外扩 4px -->
  <BorderBeam :outset="4">
    <div class="w-80 p-6 rounded-lg border bg-card shadow-sm">
      <p>外扩 4px 流光</p>
    </div>
  </BorderBeam>
</template>

旋转方向

默认所有流光均顺时针旋转，通过 reverse 让流光逆时针旋转，同页多个流光时可形成方向差异。流光头部（亮端）始终朝行进方向，尾部渐隐拖后，顺序与 ant.design 一致。

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <div class="flex gap-4">
    <!-- 顺时针（默认） -->
    <BorderBeam color="#1677ff">
      <div class="w-40 p-6 rounded-lg border bg-card">
        <p>顺时针</p>
      </div>
    </BorderBeam>

    <!-- 逆时针 -->
    <BorderBeam color="#52c41a" reverse>
      <div class="w-40 p-6 rounded-lg border bg-card">
        <p>逆时针</p>
      </div>
    </BorderBeam>
  </div>
</template>

与卡片配合

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <BorderBeam>
    <div class="w-96 rounded-2xl border bg-card shadow-lg p-6">
      <div class="flex items-center gap-3 mb-4">
        <div
          class="w-10 h-10 rounded-full bg-gradient-to-br from-blue-500 to-purple-600"
        />
        <div>
          <h3 class="font-medium">AI 助手</h3>
          <p class="text-xs text-muted-foreground">智能问答</p>
        </div>
      </div>
      <p class="text-sm text-muted-foreground">
        点击下方按钮开始与 AI 助手对话...
      </p>
      <button
        class="mt-4 px-4 py-2 rounded-md bg-primary text-primary-foreground text-sm"
      >
        开始对话
      </button>
    </div>
  </BorderBeam>
</template>

登录面板

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <BorderBeam color="#1677ff">
    <div class="w-80 p-8 rounded-xl bg-card border shadow-xl">
      <h2 class="text-xl font-semibold text-center mb-6">登录</h2>
      <div class="space-y-4">
        <input
          placeholder="用户名"
          class="w-full h-10 px-3 rounded-md border bg-background"
        />
        <input
          placeholder="密码"
          type="password"
          class="w-full h-10 px-3 rounded-md border bg-background"
        />
        <button
          class="w-full h-10 rounded-md bg-primary text-primary-foreground"
        >
          登录
        </button>
      </div>
    </div>
  </BorderBeam>
</template>

跟随容器圆角

BorderBeam 会在初始化时读取容器的 border-radius，流光会跟随圆角。

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <BorderBeam>
    <div
      class="w-80 p-6 rounded-3xl border bg-card shadow-sm"
      style="border-radius: 24px"
    >
      <p>圆角 24px 的流光边框</p>
    </div>
  </BorderBeam>
</template>

嵌套使用

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <div class="overflow-hidden rounded-lg relative">
    <!-- 裁剪容器内 outset 设为 0 -->
    <BorderBeam :outset="0" color="#1677ff">
      <div class="p-6 border bg-card">
        <BorderBeam :outset="0" color="#52c41a">
          <div class="p-4 border-2 border-green-200 bg-green-50 rounded">
            <p>嵌套流光</p>
          </div>
        </BorderBeam>
      </div>
    </BorderBeam>
  </div>
</template>

多条流光 / 动画时长 / 尺寸 / 线宽

通过 count / duration / size / lineWidth 控制流光的数量、动画时长与可见段外观。

<script setup>
import { BorderBeam } from "@reglow/reui";
</script>

<template>
  <!-- 3 条流光均匀分布，一圈 4 秒 -->
  <BorderBeam :count="3" :duration="4">
    <div class="w-80 p-6 rounded-lg border bg-card shadow-sm">
      <p>多条流光</p>
    </div>
  </BorderBeam>

  <!-- 自定义流光可见段尺寸与线宽 -->
  <BorderBeam :size="60" :line-width="2">
    <div class="w-80 p-6 rounded-lg border bg-card shadow-sm">
      <p>更细更短的流光</p>
    </div>
  </BorderBeam>
</template>

API

Props

参数说明类型默认值
color流光颜色，支持单色字符串或渐变停靠点数组string | { color: string; percent: number }[]#1677ff
count流光数量number1
duration流光完成一圈动画的时间，单位秒number6
lineWidth流光线宽，数字类型按像素处理number | string1
size流光可见段的尺寸，数字类型按像素处理number | string100
outset流光层相对容器边缘的外扩距离number | string0
reverse流光逆时针旋转booleanfalse
class附加类名string-
style附加样式CSSProperties-

Slots

名称说明
default装饰内容（需为 DOM 元素）

注意事项

  1. 子元素需要定位上下文：被包裹的内容会自动获得 position: relative。
  2. 圆角跟随：组件在初始化时读取容器的 border-radius，后续圆角变化不会自动同步。
  3. 裁剪容器：当父级有 overflow: hidden 时，建议设置 outset 为 0。
  4. 减少动态效果：当用户开启 prefers-reduced-motion: reduce 时，流光效果会自动隐藏。
  5. 性能：圆角计算在初始化时完成，不会持续监听。
  6. 浏览器支持：流光基于 CSS Motion Path（offset-path: rect(...)）实现，仅在支持的浏览器中显示（Chrome 116+ / Edge 116+ / Safari 18.2+ 等），不支持时自动隐藏，与 ant.design 行为一致。
  7. 流光顺序：流光沿边框路径匀速运动（非整盘旋转），头部朝行进方向、尾部渐隐拖后；宽高差异大的容器上四条边的经过顺序也保持均匀。

color 渐变停靠点

percent 表示渐变停靠点的位置，取值 0 ~ 100：

[
  { color: "#ff0000", percent: 0 }, // 0% 位置为红色
  { color: "#00ff00", percent: 50 }, // 50% 位置为绿色
  { color: "#0000ff", percent: 100 }, // 100% 位置为蓝色
];

组件会为尾部透明过渡保留空间，保持流光尾迹连续可见。

Toggle 开关按钮
可切换按下/弹起状态的按钮
MasonryGrid 瀑布流
通用数据驱动瀑布流布局组件，支持响应式列数、图片懒加载、无限滚动与空态占位。