AnimatedBeam

animated-beam

动效光束 · 连接两元素的流光曲线(motion 渐变 + SVG + ResizeObserver)

用法

左到右流动

在容器内连接两组节点，光束沿曲线自左向右扫过（reverse=false）。

tsx

<div ref={container} className="relative flex items-center justify-between">
  <div ref={l1}>...</div>
  <div ref={hub}>...</div>
  <AnimatedBeam containerRef={container} fromRef={l1} toRef={hub} curvature={30} reverse={false} />
</div>

四周汇聚

左侧光束流入中枢、右侧反向流入，营造数据汇聚到中心的观感。

tsx

{/* 左两条 reverse=false 流入中枢，右两条 reverse=true 流入中枢 */}
<AnimatedBeam containerRef={container} fromRef={l1} toRef={hub} curvature={30} reverse={false} />
<AnimatedBeam containerRef={container} fromRef={hub} toRef={r1} curvature={-30} reverse={true} />

右到左流动

整体反向，光束自右向左扫，表达回流/响应方向。

tsx

<AnimatedBeam containerRef={container} fromRef={l1} toRef={hub} curvature={30} reverse={true} />

何时用

想在画布里把两个 DOM 节点用一条会流光的曲线连接起来（架构图、集成示意、AI 数据流、"汇聚到中枢"动效）时用。它靠 containerRef/fromRef/toRef 测量端点几何并画 SVG 曲线，可叠多条组合成网络。要绕单个容器边框的光点用 BorderBeam；要图标沿圆周公转用 OrbitingCircles。

导入

import { AnimatedBeam } from "@hulianui/ui"

Props

名称	类型	默认	说明
containerRef*	`RefObject<HTMLElement \| null>`	—	定位基准容器，须 `position:relative`
fromRef*	`RefObject<HTMLElement \| null>`	—	起点元素 ref
toRef*	`RefObject<HTMLElement \| null>`	—	终点元素 ref
curvature	`number`	`0`	曲率（>0 上凸）
reverse	`boolean`	`false`	光束反向流动
duration	`number`	—	一趟时长(s)
delay	`number`	—	起始延迟
pathColor	`string`	border token	底线颜色
pathWidth	`number`	—	底线宽度
pathOpacity	`number`	—	底线不透明度
gradientStartColor	`string`	chart token	流光渐变起色
gradientStopColor	`string`	chart token	流光渐变止色
startXOffset / startYOffset	`number`	—	起点偏移
endXOffset / endYOffset	`number`	—	终点偏移
className	`string`	—	透传 className

禁忌 / 坑

客户端组件，依赖 ref 测量，必须 "use client"；containerRef 容器必须 position:relative，否则曲线坐标错位。
流光扫描方向由 reverse 决定（沿容器水平方向，与 path 端点顺序无关）：false 左→右、true 右→左；做"四周汇聚到中枢"时需让右侧光束 reverse。
颜色 prop 喂 token 需带 --color- 前缀——参见 [[hulian-token-color-var-needs-color-prefix]]。
端点元素与光束同处容器，记得给端点 z-10 之类层级使其压在光束上。

用法

左到右流动

在容器内连接两组节点，光束沿曲线自左向右扫过（reverse=false）。

tsx

<div ref={container} className="relative flex items-center justify-between">
  <div ref={l1}>...</div>
  <div ref={hub}>...</div>
  <AnimatedBeam containerRef={container} fromRef={l1} toRef={hub} curvature={30} reverse={false} />
</div>

四周汇聚

左侧光束流入中枢、右侧反向流入，营造数据汇聚到中心的观感。

tsx

{/* 左两条 reverse=false 流入中枢，右两条 reverse=true 流入中枢 */}
<AnimatedBeam containerRef={container} fromRef={l1} toRef={hub} curvature={30} reverse={false} />
<AnimatedBeam containerRef={container} fromRef={hub} toRef={r1} curvature={-30} reverse={true} />

右到左流动

整体反向，光束自右向左扫，表达回流/响应方向。

tsx

<AnimatedBeam containerRef={container} fromRef={l1} toRef={hub} curvature={30} reverse={true} />

何时用

Props

名称	类型	默认	说明
containerRef*	`RefObject<HTMLElement \| null>`	—	定位基准容器，须 `position:relative`
fromRef*	`RefObject<HTMLElement \| null>`	—	起点元素 ref
toRef*	`RefObject<HTMLElement \| null>`	—	终点元素 ref
curvature	`number`	`0`	曲率（>0 上凸）
reverse	`boolean`	`false`	光束反向流动
duration	`number`	—	一趟时长(s)
delay	`number`	—	起始延迟
pathColor	`string`	border token	底线颜色
pathWidth	`number`	—	底线宽度
pathOpacity	`number`	—	底线不透明度
gradientStartColor	`string`	chart token	流光渐变起色
gradientStopColor	`string`	chart token	流光渐变止色
startXOffset / startYOffset	`number`	—	起点偏移
endXOffset / endYOffset	`number`	—	终点偏移
className	`string`	—	透传 className

禁忌 / 坑

客户端组件，依赖 ref 测量，必须 "use client"；containerRef 容器必须 position:relative，否则曲线坐标错位。

流光扫描方向由 reverse 决定（沿容器水平方向，与 path 端点顺序无关）：false 左→右、true 右→左；做"四周汇聚到中枢"时需让右侧光束 reverse。

颜色 prop 喂 token 需带 --color- 前缀——参见 [[hulian-token-color-var-needs-color-prefix]]。

端点元素与光束同处容器，记得给端点 z-10 之类层级使其压在光束上。

AnimatedBeam

用法

左到右流动

四周汇聚

右到左流动

何时用

导入

Props

禁忌 / 坑

相关

AnimatedBeam

用法

左到右流动

四周汇聚

右到左流动

何时用

导入

Props

禁忌 / 坑

相关