GridScan

grid-scan

透视扫描网格 WebGL 背景 · 射线投射无限网格(实线/虚线/点线)+纵深推进的发光扫描脉冲+鼠标视差偏摆(ogl·token·reduced-motion 降级静态网格)

用法

基础用法

默认往返扫描；children 通过 relative z-10 层叠在透视网格之上。

tsx

<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
  <GridScan>
    <div className="flex h-full items-center justify-center text-white/80">
      内容层
    </div>
  </GridScan>
</div>

虚线网格 · 向前扫描

lineStyle 切换实/虚/点线，scanDirection 控制扫描带运动方向。

tsx

<GridScan lineStyle="dashed" scanDirection="forward" scanOpacity={0.6} />

点线网格 + 自定义扫描色

gridScale 越小格子越密，scanColor 改扫描脉冲发光色。

tsx

<GridScan lineStyle="dotted" gridScale={0.07} scanColor="var(--color-chart-4)" />

稀疏慢扫（壁纸级）

大 gridScale + 长 scanDuration + 高 scanSoftness 得到从容的宽光带。

tsx

<GridScan
  gridScale={0.18}
  scanDuration={4}
  scanDelay={1}
  scanSoftness={3}
  scanColor="var(--color-chart-1)"
/>

何时用

需要科技感透视网格 + 纵深推进的发光扫描脉冲做 hero / 仪表盘背景时用。只要静态网格底纹（无扫描、无 WebGL）用 GridPattern；要复古地平线透视网格用 RetroGrid。

导入

import { GridScan } from "@hulianui/ui"

Props

名称	类型	默认	说明
linesColor	`string`	`var(--color-border)`	网格线颜色，CSS 颜色字符串，默认取 token 明暗自适应
scanColor	`string`	`var(--color-primary)`	扫描带发光颜色，默认取品牌主色
gridScale	`number`	`0.1`	网格密度（格子缩放），越小越密，建议 0.05–0.3
lineThickness	`number`	`1`	网格线粗细（屏幕像素）
lineStyle	`"solid" \| "dashed" \| "dotted"`	`"solid"`	线条样式：实线 / 虚线 / 点线
scanOpacity	`number`	`0.45`	扫描带发光不透明度(0–1)，0=纯网格无脉冲
scanDirection	`"forward" \| "backward" \| "pingpong"`	`"pingpong"`	扫描方向：由远及近 / 由近及远 / 往返循环
scanDuration	`number`	`2`	单趟扫描时长(秒)，越大越慢
scanDelay	`number`	`2`	两趟扫描间停顿(秒)，pingpong 时仅影响起步延迟
scanSoftness	`number`	`2`	扫描带柔化程度，越大光带越宽越柔
noiseIntensity	`number`	`0.01`	颗粒噪声强度，0=干净无噪点
parallax	`boolean`	`true`	随鼠标轻微透视偏摆；reduced-motion / 无 WebGL 自动失效
className	`string`	—	透传根容器(或 fallback div)

Slots

插槽	类型	说明
children	`ReactNode`	叠在网格上方的内容，自动 relative z-10 层叠
fallback	`ReactNode`	reduced-motion / 无 WebGL 时的静态替代内容，默认 token 静态网格

禁忌 / 坑

ogl/WebGL，仅客户端渲染；SSR 出 fallback 静态网格，水合后切真 shader 属正常。reduced-motion / 无 WebGL 下停在 fallback。
全屏背景层置于 opaque 背景的非层叠上下文父级里可能被父背景盖住而全黑，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
自定义 scanColor/linesColor 传 CSS 变量须用 --color- 前缀 token，裸 var(--primary) 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。

Playground

网格密度线粗 px线条样式扫描方向扫描亮度扫描秒数

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <GridScan
    gridScale={0.1}
    lineThickness={1}
    lineStyle="solid"
    scanDirection="pingpong"
    scanOpacity={0.45}
    scanDuration={2}
  />
</div>

用法

基础用法

默认往返扫描；children 通过 relative z-10 层叠在透视网格之上。

tsx

<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
  <GridScan>
    <div className="flex h-full items-center justify-center text-white/80">
      内容层
    </div>
  </GridScan>
</div>

虚线网格 · 向前扫描

lineStyle 切换实/虚/点线，scanDirection 控制扫描带运动方向。

tsx

<GridScan lineStyle="dashed" scanDirection="forward" scanOpacity={0.6} />

点线网格 + 自定义扫描色

gridScale 越小格子越密，scanColor 改扫描脉冲发光色。

tsx

<GridScan lineStyle="dotted" gridScale={0.07} scanColor="var(--color-chart-4)" />

稀疏慢扫（壁纸级）

大 gridScale + 长 scanDuration + 高 scanSoftness 得到从容的宽光带。

tsx

<GridScan
  gridScale={0.18}
  scanDuration={4}
  scanDelay={1}
  scanSoftness={3}
  scanColor="var(--color-chart-1)"
/>

Props

名称	类型	默认	说明
linesColor	`string`	`var(--color-border)`	网格线颜色，CSS 颜色字符串，默认取 token 明暗自适应
scanColor	`string`	`var(--color-primary)`	扫描带发光颜色，默认取品牌主色
gridScale	`number`	`0.1`	网格密度（格子缩放），越小越密，建议 0.05–0.3
lineThickness	`number`	`1`	网格线粗细（屏幕像素）
lineStyle	`"solid" \| "dashed" \| "dotted"`	`"solid"`	线条样式：实线 / 虚线 / 点线
scanOpacity	`number`	`0.45`	扫描带发光不透明度(0–1)，0=纯网格无脉冲
scanDirection	`"forward" \| "backward" \| "pingpong"`	`"pingpong"`	扫描方向：由远及近 / 由近及远 / 往返循环
scanDuration	`number`	`2`	单趟扫描时长(秒)，越大越慢
scanDelay	`number`	`2`	两趟扫描间停顿(秒)，pingpong 时仅影响起步延迟
scanSoftness	`number`	`2`	扫描带柔化程度，越大光带越宽越柔
noiseIntensity	`number`	`0.01`	颗粒噪声强度，0=干净无噪点
parallax	`boolean`	`true`	随鼠标轻微透视偏摆；reduced-motion / 无 WebGL 自动失效
className	`string`	—	透传根容器(或 fallback div)

插槽

类型

说明

children

ReactNode

叠在网格上方的内容，自动 relative z-10 层叠

fallback

ReactNode

reduced-motion / 无 WebGL 时的静态替代内容，默认 token 静态网格

禁忌 / 坑

ogl/WebGL，仅客户端渲染；SSR 出 fallback 静态网格，水合后切真 shader 属正常。reduced-motion / 无 WebGL 下停在 fallback。

全屏背景层置于 opaque 背景的非层叠上下文父级里可能被父背景盖住而全黑，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

自定义 scanColor/linesColor 传 CSS 变量须用 --color- 前缀 token，裸 var(--primary) 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。

Playground

网格密度线粗 px线条样式扫描方向扫描亮度扫描秒数

<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <GridScan
    gridScale={0.1}
    lineThickness={1}
    lineStyle="solid"
    scanDirection="pingpong"
    scanOpacity={0.45}
    scanDuration={2}
  />
</div>

GridScan

用法

基础用法

虚线网格 · 向前扫描

点线网格 + 自定义扫描色

稀疏慢扫（壁纸级）

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground

GridScan

用法

基础用法

虚线网格 · 向前扫描

点线网格 + 自定义扫描色

稀疏慢扫（壁纸级）

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground