在 Vue 3 Vite 项目中集成 Builder.io 可视化开发基于官方示例的完整实战指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本文以本仓库中的官方示例 examples/vue/vue-3 为核心主体讲解如何在 Vue 3 Vite 技术栈中接入 Builder.io 的可视化开发能力从申请 API Key、接入 Visual Editor 实时预览到通过builder.io/sdk-vueSDK 的Content组件与fetchOneEntry数据获取 API 将可视化页面内容渲染进 Vue 组件并配置自定义可编辑组件。读完本文你将能够在自己的 Vue 3 项目中复现拖拽式可视化编辑 前端组件渲染的完整链路同时掌握该示例工程在 IDE、TypeScript、构建脚本等方面的工程化配置要点。示例工程定位与技术栈该示例位于 examples/vue/vue-3是一个标准的 Vite Vue 3 项目用于演示 Vue SDKbuilder.io/sdk-vue 的 Gen2 版本在 Vue 3 中的用法。从 package.json 可以看到其核心依赖vue^3.4.21Vue 3 运行时builder.io/sdk-vue^1.0.28Builder.io 官方 Vue SDK负责拉取、渲染并预览 Builder 中编辑的页面内容开发依赖包括vite^5.2.8、vitejs/plugin-vue、typescript~5.4.0、vue-tsc^2.0.11以及npm-run-all2用于类型检查与并行构建。SDK 的安装方式很简单仓库中 packages/sdks/output/vue/README.md 给出了命令npm install builder.io/sdk-vue值得说明的是这个 SDK 是由 Mitosis 生成的This SDK is generated by Mitosis因此 Vue、React、Svelte、Qwik 等框架的 SDK 共享同一套 Mitosis 源码与输出管线这也是本仓库能以多框架覆盖Visual Development能力的原因之一。Builder.io 接入配置从 API Key 到可视化预览README 中的核心接入步骤只有 4 步却串联起了 Builder.io 可视化开发的关键闭环。结合示例源码 src/App.vue 可以还原每一步对应的代码位置登录 builder.io进入你的账号工作区复制 API Key粘贴到源码中README 中提到的是DynamicallyRenderBuilderPage.vue中的BUILDER_API_KEY在当前版本示例中对应常量是 src/App.vue 里的BUILDER_PUBLIC_API_KEY源码中标注了// TODO: enter your public API key并预置了一个可用的示例公钥打开名为page的 model的 Visual Editor。所谓 model是 Builder 中的内容模型示例里const model page即指定要渲染的内容类型在 Builder 预览区右上角的 URL 栏输入http://localhost:3000随后在 Layers 面板中拖入一个组件它会立刻出现在编辑器中——这就是可视化编辑Visual Editing的核心体验页面运行在你的本地开发服务器上Builder 通过 iframe 预览并实时回传编辑结果。这 4 步形成的数据流是Builder 云端存储页面内容 → Vue 应用通过 SDK 按model拉取 → 渲染进页面 → Visual Editor 预览并继续编辑 → 保存后页面自动更新。README 还提供了 Loom 视频链接作为可视化演示参考该视频最初面向 React Native但操作步骤完全一致。渲染链路源码拆解Content 组件与数据获取示例中真正的Builder 集成逻辑集中在 src/App.vue 的script setup与模板中这是一份非常值得逐行研读的最小可运行实现import { Content, fetchOneEntry, isPreviewing, type BuilderContent, getBuilderSearchParams, } from builder.io/sdk-vue;用 fetchOneEntry 获取页面内容onMounted中异步拉取 Builder 内容onMounted(async () { content.value await fetchOneEntry({ model, // page apiKey: BUILDER_PUBLIC_API_KEY, options: getBuilderSearchParams(new URL(location.href).searchParams), userAttributes: { urlPath: window.location.pathname, }, }); canShowContent.value content.value ? true : isPreviewing(); });参数说明model要获取的内容模型名这里固定为pageapiKey你的 Builder 公钥options通过getBuilderSearchParams从当前 URL 查询参数中提取 Builder 的预览/编辑相关参数例如builder.preview、builder.space等保证在 Visual Editor 中预览时能命中正确的草稿内容userAttributes自定义用户属性这里传入了urlPath用于让 Builder 按当前路由路径匹配对应页面内容——这是实现多页面按路由渲染的关键字段。canShowContent的取值逻辑值得注意当内容存在时直接为true当内容为空时若正处于 Builder 的预览模式isPreviewing()也为true这样在编辑器中即使还没有发布内容也能看到画布而非显示Content not Found。用 Content 组件渲染页面模板部分将获取到的内容交给Content组件渲染并注册自定义组件Content :modelmodel :contentcontent :api-keyBUILDER_PUBLIC_API_KEY :customComponentsREGISTERED_COMPONENTS /model/content/api-key与fetchOneEntry参数对应告知渲染组件当前模型、内容与密钥customComponents将 Vue 组件注册为可在 Builder 可视化编辑器中拖拽使用的自定义组件这是把业务组件暴露给非技术编辑者的入口。当canShowContent为false既无内容也不在预览模式时模板显示Content not Found内容存在时还会展示content.data.title作为页面标题未发布时显示Unpublished。自定义组件注册规范REGISTERED_COMPONENTS展示了 Builder 注册自定义组件的结构约定const REGISTERED_COMPONENTS [ { component: HelloWorldComponent, // 指向 Vue 组件 name: Hello World, // 在 Builder 编辑器中显示的名称 canHaveChildren: true, // 是否允许嵌套子组件 inputs: [ // 暴露给编辑器的属性配置 { name: text, type: string, defaultValue: World, }, ], }, ];与之对应的组件 src/components/HelloWorld.vue 是一个带textprop 和默认插槽的简单组件slot/slot支撑了canHaveChildren: true的嵌套能力——编辑器里拖入的任意子节点都会被渲染到该插槽中。也就是说inputs中声明的每个字段都会成为 Builder 编辑面板中的可配置项编辑者修改后即通过 prop 传入组件这正是可视化配置业务组件的机制。入口文件与 Vite 别名入口 src/main.ts 是标准的 Vue 3 挂载方式createApp(App).mount(#app)。模板中使用的/assets/logo.svg别名由 vite.config.ts 配置resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } }Vue SDK 的 Nuxt 与 SSR 注意事项虽然本示例是纯 Vite SPA但 packages/sdks/output/vue/README.md 明确说明该 SDK 支持独立 Vue 3 与 Nuxt 3 两种形态并给出两条关键提示Nuxt 场景需要在nuxt.config.js中挂载 SDK 的 Nuxt 模块示例工程可参考本仓库的 examples/vue/nuxt-3 与 examples/vue/nuxt-3-catchallexport default defineNuxtConfig({ modules: [builder.io/sdk-vue/nuxt], });非 Nuxt 的 SSR 框架需要在入口处手动引入 SDK 样式Builder 渲染所需的基础 CSS再渲染 Builder Contentscript import builder.io/sdk-vue/css; /script另外需要注意该包依赖fetch在使用 Node 环境或 SSR 时应确保提供全局 fetch 能力较新的 Node 版本已原生支持。推荐 IDE 与 .vue 文件的 TypeScript 类型支持VSCode VolarREADME 推荐的 IDE 组合为VSCode Volar并禁用 Vetur TypeScript Vue Plugin (Volar)。原因是 Vetur 主要面向 Vue 2 工具链Vue 3 Vite 项目应统一使用 Volar 生态。.vue 导入的类型支持原理TypeScript 默认无法为.vue单文件组件导入提供类型信息示例工程通过两条途径解决命令行类型检查用vue-tsc取代原生tsc。这一点直接体现在 package.json 的脚本中type-check: vue-tsc --build --force并且build脚本由run-p type-check build-only {} --npm-run-all2提供并行执行类型检查与vite build编辑器内类型感知在 VSCode 中安装 TypeScript Vue Plugin (Volar)让 TS 语言服务识别.vue的类型。工程内 env.d.ts 也补充了declare module *.vue的模块声明作为兜底并引用了vite/client类型。更快的 Take Over Mode可选如果独立插件速度不够快可以启用 Volar 的 Take Over Mode打开 VSCode 命令面板执行Extensions: Show Built-in Extensions找到TypeScript and JavaScript Language Features右键选择Disable (Workspace)再次打开命令面板执行Developer: Reload Window重载窗口。启用后 Volar 将接管 TS 语言服务性能更佳。注意这是一个可选的性能优化项并非接入 Builder 的前提。项目安装与常用命令工程在 package.json 中定义的脚本如下npm install # 安装依赖 npm run dev # 启动 Vite 开发服务器含 HMR 热更新 npm run build # 并行执行类型检查 生产构建vue-tsc vite build npm run preview # 本地预览生产构建产物 npm run type-check # 仅执行 vue-tsc 类型检查分步解读npm install安装全部依赖首次接入的必做步骤npm run devVite 启动开发服务器并开启 Hot-Reload。注意README 接入步骤第 4 步要求在 Builder 预览地址栏输入http://localhost:3000而 Vite 默认端口是 5173因此实际操作时需要让开发服务器监听 3000 端口例如通过vite.config.ts设置server.port或在 Builder 中填写实际端口二者必须保持一致npm run build先用vue-tsc --build --force做类型检查再执行vite build产出生产包README 中提及的npm run lintESLint当前版本 package.json 的 scripts 中并未定义该脚本若需要代码检查可参照仓库根目录的 tslint.json 与builder.io/sdk-vue的检查约定自行补充 ESLint 配置这也说明该示例更侧重于最小可运行的集成演示。工程化配置速览tsconfig.json采用 Solution-style 引用分别指向tsconfig.node.jsonVite/构建工具侧与tsconfig.app.json应用侧env.d.ts提供*.vue模块声明与 Vite 客户端类型保证 TS 在.vue导入场景下不报错index.htmlVite 的 HTML 入口挂载#appvite.config.ts接入vitejs/plugin-vue插件并配置目录别名如需调整开发服务器端口也在此处配置。总结从示例到生产的最小迁移清单把示例工程迁移到自己的 Vue 3 项目核心只需四件事安装builder.io/sdk-vueNuxt 场景额外在nuxt.config挂载 SDK 模块用fetchOneEntry按model拉取内容并正确传入getBuilderSearchParams(location.search)与userAttributes.urlPath以支持预览与按路由匹配内容用Content组件渲染内容并通过customComponents按{ component, name, canHaveChildren, inputs }的约定注册业务组件处理好空内容与预览态isPreviewing()的降级展示避免编辑器中画布空白。从 examples/vue/vue-3 到 packages/sdks/output/vue再到本仓库 packages/sdks/src 中的 Mitosis 源码你可以沿着这条链路完整追踪可视化编辑 → 内容分发 → 组件渲染的每一层实现这也是理解 Builder.io 多框架 SDK 统一架构的最佳切入点。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考