DavidHDev/canvas-ui · 上手攻略

• 仓库：DavidHDev/canvas-ui
• 链接：https://github.com/DavidHDev/canvas-ui
• 分类：前端 · Canvas / WebGL 组件库
• 作者：Tom
• 更新：2026-08-03

这是什么

Canvas UI 是一个开源的创意 Canvas 组件库，将实时 WebGL 视觉效果覆盖在真实、可交互的 HTML 之上。官方的说法是"html-in-canvas"——让 Canvas 元素直接渲染 live DOM 内容，再由 WebGL shader 对这张"纹理"施加流体、光效、玻璃扭曲等视觉效果，DOM 始终保持可点击、可选中，无需 iframe 或 DOM-to-image 方案。

33 个组件持续增加中，覆盖流体模拟、火焰光效、玻璃折射、故障艺术、粒子重组、3D 场景等多种风格。每个组件同时提供 React、Solid、Preact、Vue、Svelte、Vanilla TS 六种版本，通过 shadcn 风格的注册表分发，源码直接落入项目，完全属于你。

解决什么问题

在 Web 上做视觉特效，通常只有两条路：

1. CSS/JS 方案：性能有限，做复杂流体或光栅变形很吃力。
2. Three.js / WebGL 裸写：效果好，但门槛高、DOM 交互要自己处理。

Canvas UI 走的是第三条路：利用 Chrome 实验特性 html-in-canvas API（chrome://flags/#canvas-draw-element），让 Canvas 内部直接渲染你写的 HTML 组件——按钮、文本、图片都保留原生行为——同时 shader 效果叠加在上面。浏览器不支持该 API 时（Firefox/Safari 等），自动降级为 WebGL overlay，内容照常可交互。

典型场景：

• 落地页/作品集：鼠标跟随的流体拖尾、玻璃折射效果，让页面"动起来"但不影响正常使用。
• H5 营销页：火焰边框、粒子重组、光束解密等炫酷转场，一个 <Liquid> 包裹即可。
• 数据可视化增强：给图表叠加 glitch / VHS 等复古滤镜，增强表现力。
• AI 应用界面：MCP ready，直接对 AI 助手说"加个 Liquid 组件"，它会帮你安装。

快速安装

前置要求

• Node.js 18+
• Chrome（启用 flag）或参与 origin trial 的域名（效果组件才需要；3D 效果组件所有浏览器均可用）
• 各框架版本：React 19、Solid 1.9+、Preact 10、Vue 3.5+、Svelte 5

方式一：shadcn CLI（推荐）

# 初始化（已有 shadcn 项目可跳过）
npx shadcn@latest init

# 添加任意组件（示例：React 版 Liquid）
npx shadcn@latest add @canvas-ui/liquid-react

# 换成其他框架只需改后缀：
# @canvas-ui/liquid-solid
# @canvas-ui/liquid-vue
# @canvas-ui/liquid-svelte
# @canvas-ui/liquid

组件源码落入 components/canvasui/（Svelte 落入 src/lib/components/canvasui/），完全可编辑、无供应商锁定。

方式二：MCP（AI 助手直装）

# 初始化 shadcn MCP
npx shadcn@latest mcp init --client claude

# 重启 Claude Code 后直接对话：
# "Show me the components in the @canvas-ui registry"
# "Add liquid from @canvas-ui to my hero section"

方式三：手动复制

打开 https://canvasui.dev/docs/components/liquid，切到目标框架 Tab，复制代码到项目即可。

启用 html-in-canvas 效果（仅限 Chrome）

开发时需手动开启 flag：

chrome://flags/#canvas-draw-element

生产环境需申请 Chrome origin trial，token 绑定域名（见 https://developer.chrome.com/blog/html-in-canvas-origin-trial）。若不申请，内容在 Chrome 中降级为普通 HTML，不报错。

核心用法

最简示例：包裹即生效

import { Liquid } from "@/components/canvasui/Liquid";

export default function Hero() {
  return (
    <Liquid>
      <main>
        <h1>我的作品集</h1>
        <p>鼠标拖动体验流体动效</p>
        <button>按钮仍然可点击</button>
      </main>
    </Liquid>
  );
}

Liquid 接受以下可选 props（React 版，其他框架类型一致）：

按组件类别速查

流体与运动类

npx shadcn@latest add @canvas-ui/liquid-react      # 指针驱动流体
npx shadcn@latest add @canvas-ui/ripple-react      # 点击水波纹
npx shadcn@latest add @canvas-ui/cloth-react       # 布料飘动
npx shadcn@latest add @canvas-ui/droplets-react    # 雨滴滑落
npx shadcn@latest add @canvas-ui/bubble-react       # 鼠标跟随 Metaball
npx shadcn@latest add @canvas-ui/displacement-react # 网格位移

火焰与能量类

npx shadcn@latest add @canvas-ui/blaze-react        # 火星烟雾 + 热扭曲
npx shadcn@latest add @canvas-ui/flame-wrap-react   # 元素火焰边框
npx shadcn@latest add @canvas-ui/force-field-react  # 能量护盾
npx shadcn@latest add @canvas-ui/laser-react        # 滚动光束解密内容

玻璃与光学类

npx shadcn@latest add @canvas-ui/glass-react        # 水晶球跟随镜头
npx shadcn@latest add @canvas-ui/frost-react         # 冰霜融化/再冻结
npx shadcn@latest add @canvas-ui/magnify-react       # HUD 放大镜
npx shadcn@latest add @canvas-ui/bend-react          # 页面折叠成立方体面
npx shadcn@latest add @canvas-ui/clouds-react        # 鼠标风力驱散雾气

复古与故障类

npx shadcn@latest add @canvas-ui/vhs-react           # 录像带波纹 + 色偏
npx shadcn@latest add @canvas-ui/glitch-react        # 广播撕裂 + RGB 分裂
npx shadcn@latest add @canvas-ui/retro-dither-react  # 1-bit 抖动镜头
npx shadcn@latest add @canvas-ui/asciify-react       # ASCII 字符镜头
npx shadcn@latest add @canvas-ui/decrypt-react       # 密码解密动画

3D 效果类（无需 flag，所有浏览器支持）

npx shadcn@latest add @canvas-ui/ascii-object-react   # GLB/glTF → ASCII
npx shadcn@latest add @canvas-ui/glass-object-react   # 液体玻璃色散
npx shadcn@latest add @canvas-ui/particle-object-react # 粒子散射弹簧回弹
npx shadcn@latest add @canvas-ui/liquid-object-react  # 液体扭变 3D 模型

典型适用场景

坑与注意

1. html-in-canvas 依赖 Chrome 实验特性 - 非 Chrome 浏览器（Firefox/Safari/Edge 非 Chromium）下，组件自动降级，内容正常渲染但无特效（无报错）。 - 生产环境必须申请 origin trial，或明确告知用户推荐使用 Chrome。 - 3D 效果组件（ascii-object、glass-object 等）不受此限制，所有浏览器可用。

2. 性能需关注模拟分辨率 - simResolution 和 dyeResolution 默认 128/512，在低端移动设备上可能掉帧，建议酌情调低。 - 同一页面不要堆叠多个高分辨率流体组件。

3. Props 在运行时可动态调整，但要注意批处理 - Liquid 的 props 改变会触发 WebGL uniform 更新，频繁变更（如跟随滚动）可能导致 GC 压力。

4. shadcn 依赖项首次安装较多 - 每个组件页面会列出所需额外依赖，首次 npx shadcn add 时会自动安装。建议在 CI 中预装 class-variance-authority、clsx、tailwind-merge 等常见依赖以加速。

5. Commons Clause 限制 - MIT 协议基础上，Commons Clause 禁止单独销售本库（作为 SaaS 服务的核心资产打包卖）。在自己项目中免费使用无限制。

6. 版本 0.1.0，仍在活跃开发 - API 可能在 minor 版本中变化，生产项目建议锁定次级版本并留意 changelog。

与同类对比

核心差异：Canvas UI 是目前唯一利用 html-in-canvas API 实现"真实 DOM + WebGL shader 叠加"的组件库，解决了其他方案 DOM 与 Canvas 分层带来的交互割裂问题。它的竞争对手不是传统动画库，而是需要自己写 WebGL + DOM 同步的定制方案。

一句话推荐

如果你的落地页或作品集想在保持页面完全可交互的前提下获得炫酷的 WebGL 特效，Canvas UI 是目前上手最快、框架最广、源码最干净的方案——用 npx shadcn@latest add @canvas-ui/liquid-react 就能在 3 分钟内让整个 Hero 区动起来。

最小可跑命令

以下命令在有 shadcn 初始化的 Next.js 16 + React 19 项目中实测。Chrome 需开启 chrome://flags/#canvas-draw-element flag 并重启。

# 1. 初始化 shadcn（项目已有可跳过）
npx shadcn@latest init

# 2. 安装 Liquid 组件（React 版）
npx shadcn@latest add @canvas-ui/liquid-react

# 3. 复制以下代码到 app/page.tsx：
# import { Liquid } from "@/components/canvasui/Liquid";
# export default () => <Liquid><h1>Hello Canvas</h1></Liquid>;

# 4. 启动开发服务器
npm run dev
# Chrome 打开 http://localhost:3000，移动鼠标即可见流体效果

# 硬件参考：Apple M2 MacBook Pro，Chrome 136（开启 flag）
# 非 Chrome 浏览器：内容正常显示但无流体特效

原始 commit / issue 链接

• GitHub 主仓库：https://github.com/DavidHDev/canvas-ui
• 最新 commit（截至 2026-08-03 约 100 commits，5 hours ago）： https://github.com/DavidHDev/canvas-ui/commits/main
• MCP 文档：https://canvasui.dev/docs/mcp
• Chrome Origin Trial 申请：https://developer.chrome.com/blog/html-in-canvas-origin-trial