border-beam-react 是一个用于 React 应用的动画边框光束/辉光效果组件。它由 ara.so 制作，收录于 Daily 2026 Skills 集合。
用途 border-beam 是一个轻量级 React 组件，可在任意元素周围渲染动态流动的光束/辉光效果，适用于卡片、按钮、输入框、搜索栏或任何容器。它使用 CSS @property 实现 GPU 加速动画，无需任何运行时动画库。
安装与要求 安装命令：npm install border-beam 要求：React 18+；现代浏览器：Chrome 85+、Safari 15.4+、Firefox 128+。
基本用法 import { BorderBeam } from 'border-beam';
function App() { return ( <BorderBeam> <div style={{ padding: 32, borderRadius: 16, background: '#1d1d1d' }}> Your content here </div> </BorderBeam> ); }
BorderBeam 包裹内容并自动检测第一个子元素的 border-radius。所有效果层使用 pointer-events: none，因此不会阻挡交互。
尺寸预设
- size="md"：完整边框辉光（默认），适用于卡片、面板。
- size="sm"：紧凑辉光，适用于图标按钮等小元素。
- size="line"：仅底部流动辉光，适用于搜索栏、输入框。
颜色变体
- colorVariant="colorful"：彩虹光谱（默认），带色相动画。
- colorVariant="mono"：灰度，无色相动画。
- colorVariant="ocean"：蓝紫色调。
- colorVariant="sunset"：橙黄红色调。 除 mono 外，所有变体默认都会进行色相偏移循环动画。
主题（深色/浅色/自动）
- theme="dark"：默认，适用于深色背景。
- theme="light"：适用于浅色背景。
- theme="auto"：检测系统 prefers-color-scheme。
控制强度
- strength：0（不可见）到 1（全强度，默认），仅影响光束层。
- brightness 与 saturation：亮度与饱和度乘数。
播放/暂停与回调 可通过 active 属性控制播放/暂停，并带淡入淡出过渡；onActivate 在淡入完成时调用，onDeactivate 在淡出完成时调用。示例：
import { useState } from 'react'; import { BorderBeam } from 'border-beam';
function AnimatedCard() { const [active, setActive] = useState(true);
return ( <> <BorderBeam active={active} onActivate={() => console.log('Beam faded in')} onDeactivate={() => console.log('Beam faded out')} > <div style={{ padding: 32, borderRadius: 16, background: '#111' }}> Hover-activated beam </div> </BorderBeam> <button onClick={() => setActive(a => !a)}>Toggle Beam</button> </> ); }
自定义时长与色相范围
- duration：动画周期（秒），默认 md 为 1.96，line 为 2.4。
- hueRange：色相旋转范围（度），默认 30。
- staticColors：设为 true 可完全禁用色相偏移。
自定义圆角 如果自动检测不生效（例如圆角通过 CSS 类设置），可显式传入 borderRadius： <BorderBeam borderRadius={24}> <div className="my-card">Content</div> </BorderBeam>
转发 HTML 属性 包裹用的 <div> 会转发所有标准 HTMLDivElement 属性，例如 className、style、data-testid 等。
常见模式
- 悬停激活光束：用 useState 跟踪 hovered，将 active 设为 hovered，并配合 strength、colorVariant。
- 带 line 光束的搜索栏：size="line"、colorVariant="sunset"、theme="dark"，包裹 input。
- 浅色主题卡片：theme="light"、colorVariant="colorful"、strength={0.8}。
- 减少动态效果无障碍：组件本身不会自动响应 prefers-reduced-motion，需在使用方处理，例如通过 window.matchMedia('(prefers-reduced-motion: reduce)').matches 判断后设置 active={!reduceMotion}。
完整 Props 参考
- children：ReactNode，要包裹的内容。
- size：'sm' | 'md' | 'line'，默认 'md'，尺寸/类型预设。
- colorVariant：'colorful' | 'mono' | 'ocean' | 'sunset'，默认 'colorful'，颜色调色板。
- theme：'dark' | 'light' | 'auto'，默认 'dark'，背景适配。
- strength：number，默认 1，光束不透明度 0–1，不影响子元素。
- duration：number，默认 1.96 / 2.4，动画周期（秒）。
- active：boolean，默认 true，播放/暂停并带淡入淡出过渡。
- borderRadius：number，默认自动检测，以 px 覆盖圆角。
- brightness：number，默认 1.3，辉光亮度乘数。
- saturation：number，默认 1.2，辉光饱和度乘数。
- hueRange：number，默认 30，色相旋转范围（度）。
- staticColors：boolean，默认 false，禁用色相偏移动画。
- className：string，包裹 div 的类名。
- style：CSSProperties，包裹 div 的内联样式。
- onActivate：() => void，淡入完成时调用。
- onDeactivate：() => void，淡出完成时调用。
工作原理 BorderBeam 渲染一个包裹 <div>，包含三个效果层，全部为 pointer-events: none、绝对定位，不影响布局或交互：
- ::after：光束描边（锥形渐变遮罩到边框边缘）。
- ::before：内部辉光层。
- [data-beam-bloom]：外部泛光/辉光子 <div>。 动画使用 CSS @property 实现平滑、GPU 加速的色相循环。
故障排查
- 光束不可见：确保子元素有可见背景和圆角；检查 strength 不为 0；确认 active 为 true。
- 圆角不匹配：如果圆角来自 CSS 类而非内联样式，请显式传入 borderRadius。
- 效果覆盖内容/阻挡点击：所有层默认 pointer-events: none；若出现此问题，请检查包裹元素的 CSS 冲突。
- 浏览器中动画不工作：需要 CSS @property 支持：Chrome 85+、Safari 15.4+、Firefox 128+。可查阅 caniuse.com/@property。
- SSR / Next.js：组件使用 DOM API 检测圆角；在 Next.js App Router 中需包裹在客户端组件（'use client'）内。
适用场景 适用于需要在 React 界面中为卡片、按钮、输入框、搜索栏等元素添加动态边框光束/辉光视觉效果的场景，尤其适合追求轻量、无运行时动画库依赖的实现。
限制 需要 React 18+ 与支持 CSS @property 的现代浏览器；组件本身不自动响应 prefers-reduced-motion，需使用方自行处理；在 SSR/Next.js App Router 中需作为客户端组件使用。