什么是ui-builder？一行代码给你的React应用嵌入Figma风格可视化编辑器，让非开发者拖拽搭建页面

ui-builder是一个面向 React 应用的开源无代码（no-code）可视化编辑器组件，以 shadcn/ui 包的形式发布。它能把一个 Figma 风格的拖拽编辑器直接嵌入你自己的产品里，让运营、产品甚至客户不用写代码，就能用你项目里现成的 React 组件搭建落地页、仪表盘、邮件模板和定制门户。页面结构最终以纯 JSON 存储，方便版本管理与动态渲染。

🤔 为什么需要 ui-builder？

市面上的无代码工具大多有一个通病：它们自带一套组件库，逼着你从头重建 UI，最终生成的页面和你产品的视觉风格格格不入。

ui-builder 反其道而行——组件由你提供：

• 它运行在你现有的 React 组件之上，你只需通过componentRegistry告诉编辑器"哪些组件可用"
• 拖拽出来的 Button、Card 就是你自己@/components/ui里的那些组件，视觉风格天然统一
• 布局以 JSON 形式保存，可以入库、进 Git、做版本对比

✨ 核心功能一览

🖥️ 编辑器界面长什么样？

界面分为三个区域：

1. 左侧面板：Layers（图层树，管理组件层级与页面切换）和Appearance（外观与变量设置）两个标签页
2. 中间画布：所见即所得的编辑区，直接点选、拖拽组件，实时调整
3. 右侧属性面板：选中组件后自动出现，可编辑尺寸、间距、Tailwind 类名、变体等所有 props

下面是官方演示动画，展示了拖拽搭建页面的完整过程：

深色主题下同样完整可用，右侧属性面板支持直接编辑 className、子组件和变体：

🚀 三步快速上手

第 1 步：安装（shadcn 一行命令）

npx shadcn@latest add https://raw.githubusercontent.com/olliethedev/ui-builder/main/registry/block-registry.json

第 2 步：创建页面并嵌入编辑器

新建app/builder/page.tsx，核心只有几行——导入UIBuilder组件，传入你的componentRegistry：

"use client"; import UIBuilder from "@/components/ui/ui-builder"; import { primitiveComponentDefinitions } from "@/lib/ui-builder/registry/primitive-component-definitions"; import { complexComponentDefinitions } from "@/lib/ui-builder/registry/complex-component-definitions"; export default function BuilderPage() { return ( <main className="h-screen"> <UIBuilder componentRegistry={{ ...primitiveComponentDefinitions, ...complexComponentDefinitions, }} /> </main> ); }

访问http://localhost:3000/builder即可看到编辑器。

第 3 步：生产环境渲染页面

正式展示页面时不需要编辑器外壳，用LayerRenderer（客户端）或ServerLayerRenderer（SSR/RSC）直接渲染保存的 JSON 布局，还可以注入variableValues实现动态内容。

🎯 典型使用场景

• 市场团队：不排期等开发，自行更新落地页
• 产品经理：调整邮件模板，部分内容按用户动态渲染
• B2B / 白标业务：客户用自己的内容与品牌定制门户
• Headless CMS：给内容 API 加一个可视化"头部"，连接内容库与组件库

项目内置的邮件构建能力（见 lib/ui-builder/email/）还可以直接拖拽搭建 react-email 邮件模板。

📂 关键文件导航

想深入源码或文档，可以从这些入口入手：

• 主组件（编辑器入口）：components/ui/ui-builder/index.tsx
• 客户端渲染器：components/ui/ui-builder/layer-renderer.tsx
• 服务端渲染器（SSR/RSC）：components/ui/ui-builder/server-layer-renderer.tsx
• 内置基础组件注册表：lib/ui-builder/registry/primitive-component-definitions.ts
• shadcn 组件注册表：lib/ui-builder/registry/shadcn-component-definitions.ts
• 安装用 shadcn 注册表 JSON：registry/block-registry.json、registry/shadcn-components-registry.json
• 官方文档内容（项目自带文档站源码）：app/docs/docs-data/docs-page-layers/introduction.ts、app/docs/docs-data/docs-page-layers/variables.ts

❓ 常见问题

它和普通的无代码建站工具有什么区别？无代码工具通常用自带的组件体系生成页面；ui-builder 直接用你项目里的 React 组件，产出的页面与产品视觉 100% 一致，还能导出回 React 代码。

非开发者能独立使用吗？可以。编辑器提供拖拽画布、图层树和自动生成的属性表单，理解"组件嵌套"概念即可上手。

需要哪些技术栈？Next.js 14+（推荐 App Router）、React 18+、Tailwind CSS（启用 CSS 变量以便主题化）。React 19 用户如遇 peer dependency 警告，在.npmrc中加入legacy-peer-deps=true即可。

布局怎么保存？以纯 JSON 存储，通过onChange回调写入数据库或 localStorage，天然支持版本管理与动态数据渲染。

总结来说：如果你的 React 产品需要一个"让非开发者也能拖拽搭页面"的能力，ui-builder几乎就是为这个需求而生的——一行代码嵌入 Figma 风格编辑器，组件、主题、代码导出全部无缝融入现有项目。