使用 Builder.io Angular SDKgen1构建动态页面基于 angular-gen1 示例的完整实践指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io 是一套面向 React、Vue、Svelte、Qwik 等框架的可视化开发平台本仓库中的 examples/angular-gen1 是它在 Angular 生态中的经典集成示例将 Builder.io 的视觉编辑能力嵌入 Angular 应用实现「非工程师在可视化编辑器里改页面Angular 应用自动渲染」的动态页面构建工作流。读完本文你将掌握如何在 Angular 项目中初始化 Builder SDK、注册自定义可编辑组件、渲染modelpage的动态内容并完成开发、构建与测试的完整闭环。示例项目定位与关联资源examples/angular-gen1是一个可直接运行的 Angular 应用演示了 Builder.io 在 Angular 中做动态页面构建dynamic page building的标准姿势。示例中用到的是 Builder.io Angular SDK 的 gen1第一代版本对应的 SDK 源码与完整文档位于 packages/angular。如果你关心服务端渲染SSR场景本仓库还提供了基于 Angular Universal 的完整示例examples/angular-universal它展示了在 SSR 架构下同样的builder-component如何预渲染与 hydration适合对 SEO 和首屏性能有要求的读者对比学习。从 examples/angular-gen1/package.json 可以看到本示例的技术底座Angular18.1.3core / common / compiler / router / forms 等全套模块、builder.io/angular^3.1.1-0、angular/elements、webcomponents/custom-elements与webcomponents/webcomponentsjs用于自定义元素 polyfill说明这套方案依赖 Web Components 标准来桥接 Builder 渲染引擎与 Angular 运行时。本地开发一条命令启动动态页面应用进入示例目录后安装依赖并启动开发服务器npm install ng serveng serve会启动 Angular CLI 的开发服务器浏览器访问http://localhost:4200/即可看到应用。开发服务器支持源码热重载——修改src下任意组件、模板或样式文件页面会自动刷新这与原生 Angular CLI 的开发体验完全一致也意味着你可以一边在 Builder.io 可视化编辑器里改内容、一边在本机预览渲染结果。package.json中预置了与开发相关的脚本{ scripts: { ng: ng, start: ng serve, build:dev: ng build, build: ng build --prod, test: ng test, lint: ng lint, e2e: ng e2e } }其中npm start等价于ng serve可直接作为日常开发入口。项目结构SDK 集成发生在哪里先看src目录的整体布局examples/angular-gen1/srcsrc/ ├── app/ │ ├── app.component.ts / .html / .css # 根组件承载 builder-component │ ├── app.module.ts # NgModule注册 BuilderModule.forRoot │ ├── foo.component.ts # 路由兜底组件 │ └── with-children.ts # 支持子区块的自定义组件示例 ├── environments/ # 环境配置dev / prod ├── main.ts # 引导入口 └── index.html模块级初始化BuilderModule.forRoot 与 API Key在 app.module.ts 中完成 SDK 的核心接入NgModule({ declarations: [AppComponent, FooComponent, CustomThing, CustomThingChildren], imports: [ BrowserModule, BuilderModule.forRoot(1f3bf1d766354f32ba70dde440fcef97), RouterModule.forRoot([ { path: **, component: FooComponent, }, ]), ], bootstrap: [AppComponent], }) export class AppModule {}三个关键点BuilderModule.forRoot(apiKey)以模块级静态工厂的形式注入 Builder 配置。从 SDK 源码 builder.module.ts 可以看到forRoot通过ModuleWithProviders把 API Key 注册到依赖注入容器public static forRoot(apiKey?: string): ModuleWithProvidersBuilderModule { return { ngModule: BuilderModule, providers: [ { provide: BUILDER_API_KEY, useValue: apiKey, }, ], }; }示例中的1f3bf1d766354f32ba70dde440fcef97是公开示例 Key你接入自己的空间space时替换为在 Builder.io 后台生成的真实 Key 即可。路由表将所有路径**统一路由到FooComponent。这是因为动态页面模式下页面内容完全由 Builder 内容模型决定Angular 侧只需要一个兜底路由承接具体页面内容由builder-component按 URL 动态拉取渲染。同文件还声明了CustomThing、CustomThingChildren两个自定义组件说明 Builder 自定义组件必须同时进入declarations才能被 SDK 实例化。模板层builder-component 即动态页面出口根组件模板 app.component.html 非常精简a routerLink/aA/a a routerLink/bB/a builder-component [options]options [data]data modelpage/builder-component router-outlet/router-outletbuilder-component是 SDK 暴露的公开组件modelpage表示拉取并渲染 Builder 中page 内容模型下、与当前 URL 匹配的条目。配合RouterModule的通配路由与页面链接就构成了「多 URL → 动态渲染多页面」的能力。动态渲染核心builder-component 的输入输出契约在 app.component.ts 中可以看到组件的典型用法export class AppComponent { title app; options: any { cacheSeconds: 1, data: { locale: en-US, }, }; data { property: hello, fn: (text: string) alert(text), }; load(event: any) { console.log(load, event); } error(event: any) { console.log(error, event); } }对照 SDK 组件实现 builder-component.component.tsbuilder-component对外契约如下输入 / 输出类型说明model必填string内容模型名称如page也可用name别名传入optionsGetContentOptions内容拉取选项如cacheSeconds缓存秒数dataany注入页面的初始数据模板中可通过{{property}}使用contextany全局上下文数据contentany直接传入内容 JSON跳过网络拉取hydrateboolean默认true是否客户端水合prerenderboolean默认true是否服务端预渲染handleRouting/reloadOnRouteboolean路由接管 / 路由变化时是否重新拉取内容load/route/errorEventEmitter内容加载成功 / 路由事件 / 加载失败回调示例中的两个细节值得展开options.cacheSeconds: 1内容请求的客户端缓存时长单位秒。设为 1 意味着每次路由访问都可能重新校验内容适合内容频繁改动的开发阶段生产环境可调大以减少请求量。该参数会直接透传给 SDK 的内容获取层。data中的fn函数data不只是静态值还可以携带函数如alert这意味着 Builder 可视化编辑器里配置的交互行为点击触发等可以绑定到这些注入的函数上实现「设计稿到交互逻辑」的打通。自定义可编辑组件BuilderBlock 装饰器仅渲染内置组件还不够业务组件如何暴露给可视化编辑器示例给出了答案——BuilderBlock装饰器。基础自定义组件app.component.ts 中的CustomThingComponent({ selector: custom-thing, template: Hello: {{name}}, }) export class CustomThing { Input() name ; } BuilderBlock({ tag: custom-thing, name: Custom thing, inputs: [ { name: name, type: string, }, ], })(CustomThing);BuilderBlock把 Angular 组件「注册」进 Builder 组件注册表声明了三件事tag组件对应的自定义元素标签与selector一致name显示在编辑器组件面板里的友好名称inputs属性 schema声明组件可被编辑器配置的属性及类型。type: string表示编辑器渲染文本输入框还支持number、boolean、color、richText、blocks等类型。从 SDK 的模块初始化逻辑builder.module.ts可以看出注册后的运行机制在浏览器端SDK 通过angular/elements的createCustomElement把已注册的 Angular 组件转换为标准自定义元素并customElements.define到浏览器从而让 Builder 渲染引擎本身运行在 Web Components 之上能够直接实例化这些组件。这也是示例依赖webcomponents/custom-elementspolyfill 的原因——需要在不支持自定义元素的旧浏览器上补齐能力。支持子区块的容器组件with-children.ts 展示了更进阶的用法——让自定义组件拥有可拖拽子区块children的编辑区域BuilderBlock({ tag: custom-thing-children, name: Custom thing with children, canHaveChildren: true, inputs: [ { name: name, type: string, }, { name: sectionA, type: blocks, hideFromUI: true, helperText: This is an editable region where you can drag and drop blocks., defaultValue: [ { type: builder.io/sdk:Element, component: { name: Text, options: { text: Section A Editable in Builder... } }, responsiveStyles: { large: { display: flex, flexDirection: column, position: relative, flexShrink: 0, boxSizing: border-box, marginTop: 20px, lineHeight: normal, height: auto, textAlign: center, }, }, }, ], }, { name: sectionB, type: blocks, hideFromUI: true, helperText: This is an editable region where you can drag and drop blocks., defaultValue: [ /* 与 sectionA 结构一致 */ ], }, ], })(CustomThingChildren);要点canHaveChildren: true表示该组件可包裹子组件type: blocks的输入项声明「这是一个可编辑区块区域」配合hideFromUI: true隐藏属性面板中的直接编辑入口改为在画布内通过builder-blocks-outlet拖拽内容见组件模板helperText给出编辑器内的提示文案defaultValue是区块的初始 JSON结构遵循 Builder 内容规范type: builder.io/sdk:Element标记元素类型component.name指向内置组件如TextresponsiveStyles.large声明大屏下的响应式样式——这与 Builder 可视编辑器产出的内容结构完全一致因此这些默认区块也能在编辑器中继续被拖拽修改。模板中通过builder-blocks-outlet把区块 JSON 渲染出来h2Section A/h2 builder-blocks-outlet [blocks]sectionA [builderState]builderState [builderBlock]builderBlock dataPathcomponent.options.sectionA /builder-blocks-outlet[blocks]传入区块数组、dataPath指明该区域在组件配置树中的路径SDK 借此把编辑器里的拖拽修改回写到正确位置。代码脚手架Angular CLI 生成器示例沿用了 Angular CLI 标准的代码生成能力为新增页面级组件或服务提供快捷方式ng generate component component-name也支持 CLI 内置的其余生成类型ng generate directive|pipe|service|class|guard|interface|enum|module生成的自定义组件component-name默认注册到app.module.ts的declarations中之后可按照上文BuilderBlock的方式将其暴露给 Builder 编辑器。注意本示例的 Angular CLI 版本为18.1.3见 package.json生成物的默认前缀与样式在 angular.json 的schematics段中配置prefix: app、style: css。构建与生产部署开发构建ng build构建产物输出到dist/目录输出路径在 angular.json 中配置为outputPath: dist此命令对应build:dev脚本不进行生产级优化。生产构建README 记载的使用-prod标志的写法属于旧版 Angular CLI 的语法以当前仓库为准生产构建应通过 npm 脚本执行npm run build其内部等价于ng build --prod见 package.json 中build: ng build --prod。从 angular.json 的production配置段可以看到生产构建启用的优化项optimization代码压缩与摇树、outputHashing: all产物指纹哈希便于缓存、buildOptimizer、vendorChunk: false、aot: trueAOT 编译并通过fileReplacements将environment.ts替换为environment.prod.ts同时以budgets对单个组件样式体积6kb警告阈值进行约束。生产构建的dist/产物是纯静态资源可部署到任意静态托管或 CDN如果页面内容依赖运行时拉取而非构建期预取需要确保部署域名在 Builder.io 后台的域名白名单中。测试单元测试与端到端测试单元测试Karma Jasmineng test该命令启动 Karma 测试运行器执行 Jasmine 单元测试。测试入口与配置分别位于 src/test.ts 与 karma.conf.js测试目标在 angular.json 的testarchitect 中指定main: src/test.ts、karmaConfig: ./karma.conf.js。示例自带的 app.component.spec.ts 可作为编写组件测试的参考起点——注意测试默认使用无头 Chrome需要本机具备 Chrome 环境。端到端测试Protractorng e2e通过 Protractor 执行端到端测试其配置与目标在 protractor.conf.js 及 angular.json 的angular-test-site-e2e项目中定义e2e 测试用例位于 e2e 目录。执行时 Protractor 会先拉起ng serve开发服务器再驱动浏览器做真实交互验证。重要提示gen1 与 gen2 的选择示例 README 末尾特别注明NOTEangular-gen1不是使用 Builder.io Angular SDK 的推荐方式。仓库同时提供了新一代集成示例 examples/angular-gen2它基于 Angular CLI 19 与新版 SDK 体系Web Components 原生渲染被 README 明确标注为推荐路径且无需builder.io/angular依赖、不依赖BuilderModule.forRoot这类模块级初始化。因此实际选型建议如下新项目优先参考 examples/angular-gen2其维护性与长期兼容性更好已使用 gen1 SDK 的存量项目本示例完整演示了BuilderModule.forRoot初始化、builder-component渲染、BuilderBlock自定义组件注册等 gen1 的核心 API可作为迁移与维护期排查问题的参照需要 SSR 的 Angular 项目无论 gen1 还是 gen2都可对照 examples/angular-universal 了解服务端渲染场景下的集成方式。小结通过examples/angular-gen1这个麻雀虽小五脏俱全的示例可以完整看清 Builder.io gen1 Angular SDK 的集成链路BuilderModule.forRoot(apiKey)注入配置 →builder-component modelpage渲染动态内容 →BuilderBlock把 Angular 组件注册为可视化编辑器可编辑的积木 → CLI 脚手架、构建与测试体系保障工程闭环。无论你最终选择 gen1 还是迁移到 gen2本文覆盖的 API Key 注入、内容模型渲染、自定义组件注册与区块容器这些概念都是理解 Builder.io × Angular 动态页面体系的公共地基。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
