用 Builder.io 与 React 搭建可视化多页转化漏斗：从零配置到源码级剖析
【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder
本文基于仓库中的 react-multipage-funnel 示例 编写，完整讲解如何使用 Builder.io 的视觉开发能力，结合 React 与 React Router 构建一套「多页面转化漏斗」（multipage funnel）。你将掌握 Builder.io 空间（Space）的初始化、私有密钥与公开 API Key 的获取流程、CLI 导入 CMS 内容的方法，以及
BuilderContent/BuilderComponent在 React 中渲染漏斗各步骤的底层实现原理。
什么是多页漏斗，为什么用 Builder.io 来做
转化漏斗（Funnel）是一系列按顺序引导用户完成目标（注册、下单、填写信息等）的页面组合。传统做法中，每一页都写死在前端路由里，营销团队想调整某一步的内容或新增一步，都需要开发介入、重新发布。
Builder.io 的思路是：页面结构交给前端，页面内容交给可视化编辑器。本示例把漏斗定义为一个名为multipage-funnel的 CMS 数据模型，漏斗中的每一步（section）引用另一类模型funnel-section的已发布内容。于是：
- 业务人员可以在 Builder.io 后台直接编辑每一步的文案、图片、按钮；
- 前端只负责按路由把对应内容渲染出来，并注入「下一步 / 上一步」的导航能力；
- 漏斗的步骤数量、顺序、标题全部由后台数据驱动，前端代码无需改动。
仓库中的示例工程位于 examples/react-multipage-funnel，其核心依赖在 package.json 中可见：@builder.io/react、react-router-dom、react-scripts。
快速开始：两种运行方式
在 CodeSandbox 中在线运行
README 提供了直接在浏览器打开 CodeSandbox 示例 的入口，无需本地环境即可查看效果。
本地运行
git clone https://github.com/BuilderIO/builder.git cd examples/react npm install npm start注意：README 中的本地运行路径写作
examples/react，但实际工程位于仓库的examples/react-multipage-funnel目录。克隆仓库后请以实际目录为准，即cd builder/examples/react-multipage-funnel后再执行npm install与npm start。
前置条件
本指南假设你已经安装：
- Node.js（示例使用
react-scripts，对应 Create React App 开发服务器） - npm 或 yarn（工程锁定了
package-lock.json，见 examples/react-multipage-funnel/package-lock.json） - git
完成后你将拥有一个已配置好、可直接使用的 Builder.io 多页漏斗空间（Space）。
第一步：注册 Builder.io 账号
访问 builder.io 注册页 创建账号。注册后你会得到一个组织（Organization），所有空间与密钥都在组织层面管理。
第二步：获取 Builder.io 私有密钥（Private Key）
私有密钥用于在本地通过 CLI 向你的账号创建空间，操作路径如下：
- 打开组织设置页，或从列表中选择一个组织；
- 点击左侧边栏的Account；
- 找到Private keys一行，点击编辑图标；
- 复制自动生成的密钥，或新建一个对你有意义命名的新密钥。
第三步：克隆仓库并用 CLI 初始化 Builder.io 空间
在本地克隆本仓库并进入示例目录，然后全局安装 Builder.io CLI，最后用builder create命令创建空间：
git clone https://github.com/BuilderIO/builder cd builder/examples/react-multipage-funnel npm install --global "@builder.io/cli" builder create --key "<private-key>" --name "<space-name>" --debug参数说明：
| 参数 | 含义 |
|---|---|
--key | 上一步复制的私有密钥，用于鉴权 |
--name | 新空间的名称，后续可在后台修改 |
--debug | 开启调试输出，便于确认每一步执行结果 |
执行成功后，CLI 会返回新空间的公开 API Key（public API Key），控制台输出形如：
____ _ _ _ _ _ _ | __ ) _ _ (_) | | __| | ___ _ __ (_) ___ ___ | | (_) | _ \ | | | | | | | | / _` | / _ \ | '__| | | / _ \ / __| | | | | | |_) | | |_| | | | | | | (_| | | __/ | | _ | | | (_) | | (__ | | | | |____/ \__,_| |_| |_| \__,_| \___| |_| (_) |_| \___/ \___| |_| |_| |████████████████████████████████████████| multipage-funnel | 1/1 |████████████████████████████████████████| funnel-section: writing section-three.json | 1/3 Your new space "...." public API Key: 1234795283492198789217893712893关键点：这个命令不只是创建空白空间，还会把示例工程builder目录下预置的 CMS 内容发布到新空间。从输出可以看到，CLI 依次处理了multipage-funnel模型与funnel-section模型下的三个 section 内容（section-one.json、section-two.json、section-three.json）。
把返回的公开 API Key（上例中的1234795283492198789217893712893）复制下来，填入 src/index.js 中的builder.init(...)。
仓库中预置的 CMS 内容结构
示例的builder目录本身就是一份可导入的空间备份，完整呈现了漏斗所需的数据模型与内容，路径为 examples/react-multipage-funnel/builder：
builder/ ├── settings.json # 空间配置（type: space） ├── funnel-section/ # 漏斗每一步的视觉内容模型 │ ├── schema.model.json │ ├── section-one.json │ ├── section-two.json │ └── section-three.json ├── multipage-funnel/ # 漏斗本身的数据模型 │ ├── schema.model.json │ └── my-first-funnel.json └── page/ # 通用页面模型（本例未直接使用） └── schema.model.jsonsettings.json（查看）记录空间的名称multipage-funnels-space，并通过cloneInfo中的contentIdMap/modelIdMap把源内容 ID 映射到新空间，这正是builder create能完成内容迁移的原理。
两个核心模型：漏斗数据与漏斗步骤
multipage-funnel：漏斗的骨架
模型定义见 builder/multipage-funnel/schema.model.json。它的kind为data（纯数据模型，不直接渲染为页面），repeatable: false，核心字段只有一个：
sections（类型list，必填）：漏斗的步骤列表，每一项包含两个子字段：title（text）：步骤在导航栏显示的标题；content（reference）：对funnel-section模型内容的引用，helperText明确说明"Which content to render at the specified path"，即决定该步骤在指定路由下渲染哪份内容。
实际内容示例见 my-first-funnel.json，其中data.sections定义了三个步骤：Welcome、Information、Good Bye，每一步的content都是一个@builder.io/core:Reference，指向funnel-section模型下某份内容的 ID。
funnel-section：漏斗每一步的视觉内容
模型定义见 builder/funnel-section/schema.model.json，kind为component，字段blocks（类型uiBlocks）承载可视化画布上的元素树。
每份内容都是一个完整的 Builder 元素树。以 section-one.json 为例，它包含：
Core:Section根容器（maxWidth: 1200，全宽背景图、高度 700px，中屏 500px、小屏 350px 响应式）；Text组件：标题 "Something Great to Say"（58px 大字号，随断点缩至 31px）与副标题；Core:Button组件："Let's Go!"，其actions.click绑定state.navigateNext()。
这个state.navigateNext不是前端组件自带的方法，而是由宿主应用在渲染时通过data注入的状态，这正是整个漏斗能够"翻页"的关键——下一节详细拆解。
源码级剖析：React 侧如何渲染漏斗
入口文件 src/index.js 是理解整套机制的最佳样本，全流程可分为四层。
1. 初始化 SDK
import { BuilderComponent, BuilderContent, builder } from '@builder.io/react'; builder.init('cebf462cf12940c78302d9b4a201d7e6');builder.init接收的正是 CLI 创建空间时返回的公开 API Key（示例文件中内置的是该示例空间原本的 Key，你自己的工程请替换为第三步获得的 Key）。
2. 用 BuilderContent 拉取漏斗数据
<BuilderContent options={{ includeRefs: true }} model="multipage-funnel"> {(funnel, loading) => { ... }} </BuilderContent>model="multipage-funnel"对应后台的数据模型名；options={{ includeRefs: true }}是关键：漏斗的sections[].content是**引用（Reference）**而非内嵌内容，必须展开引用才能拿到每步的实际内容，渲染时才能传给BuilderComponent；- 渲染函数处理三种状态：
loading时显示占位文案，funnel不存在时提示"no data have you connected builder correctly?"（即 API Key 或空间内容未正确连接），正常时渲染Steps。
3. Steps 组件：数据驱动路由与导航
const Steps = ({ funnel }) => { const history = useHistory(); const navigateNext = step => history.push(getStepLink(step + 1)); const navigateBack = step => history.push(getStepLink(step - 1)); const getStepLink = index => (index === 0 ? '/' : `/step-${index}`); ... };getStepLink把步骤索引映射为路由：第 0 步是/，后续是/step-1、/step-2……；- 顶部导航根据
funnel.sections动态生成链接，并用CustomLink（基于useRouteMatch判断激活态）高亮当前步骤； - 路由区域用
<Switch>遍历funnel.sections，为每一步注册一条<Route>。
4. 向 BuilderComponent 注入导航状态
<BuilderComponent data={{ navigateBack: navigateBack.bind(null, index), navigateNext: navigateNext.bind(null, index), hasPrev: index > 0, hasNext: index < funnel.sections.length - 1, }} model="funnel-section" content={section.content.value} />这里回答了"state.navigateNext从哪来"：data对象会被合并进该内容的渲染状态，于是视觉内容里按钮的click动作state.navigateNext()就会调用这里绑定的函数，通过history.push跳到下一步；hasPrev/hasNext也可供视觉内容做条件判断（例如在最后一步隐藏"下一步"按钮）。content={section.content.value}传入的正是BuilderContent展开引用后得到的步骤内容。
至此，完整数据流可以概括为：
builder.init(publicApiKey) → BuilderContent 拉取 multipage-funnel 数据（includeRefs 展开引用） → Steps 按 sections 生成路由 + 导航 → 每步 Route 渲染 BuilderComponent(model="funnel-section", content, data) → 视觉内容中按钮 click → state.navigateNext() → history.push 翻页扩展阅读与下一步
- 想快速上手 React SDK 的其他能力，可参考 packages/react 的源码 与 README；
- CLI 的更多子命令与参数实现见 packages/cli/src；
- 仓库还提供了其他框架的多页/漏斗类示例，例如 examples/next-js-cms-blog、examples/react-design-system，用于对比不同技术栈下内容模型的组织方式。
一个可以立刻动手的实验：在 Builder.io 后台给funnel-section模型新增一份内容（比如"Thanks"感谢页），再回到multipage-funnel内容里新增一个 section 引用它。不需要改任何前端代码，新步骤就会自动出现在导航栏和路由中——这就是数据驱动漏斗与手写多页表单的本质区别。
【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
