builder.io/sdk-angular 从零到实战Builder.io Gen2 Angular SDK 能力全景与版本演进解析【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder导读本文以builder.io/sdk-angularBuilder.io Gen2 Angular SDK的完整变更记录为主线结合本仓库packages/sdks/output/angular的产物与packages/sdks/src的 Mitosis 源码系统讲解该 SDK 的内容获取、渲染、个性化、A/B 测试、可视化编辑与多运行时构建能力。读完本文你将掌握fetchOneEntry/fetchEntries的完整参数体系、Content组件的正确用法、自定义组件注册协议以及如何为 Angular 17 应用接入 Builder 无头可视化开发能力。SDK 定位与安装builder.io/sdk-angular是 Builder 的 Gen2 Angular SDK与 React、Vue、Svelte、Qwik 等 SDK 一样由 Mitosis 从同一份跨框架源码编译生成其 Mitosis 源位于 packages/sdks/src。当前仓库中的产物版本为 0.25.13见 packages/sdks/output/angular/package.json。安装与版本约束npm install builder.io/sdk-angular该 SDK 要求 Angular 版本17.3.0peer 依赖为angular/common与angular/core见 package.json。这一点与 0.21.0 的 Breaking Change直接相关SDK 全面转向 Angular 17 的信号signals体系。运行时依赖仅有isolated-vm用于 Node 端代码块解释执行与tslib。isolated-vm在 0.23.0 从5.0.0升级到6.0.0以支持 Node v24同时弃用 Node 18 与 Node 20因此生产环境需使用 Node 220.0.5 时支持 Node v22或 Node 24。包通过条件导出exports提供node/browser/edge/edge-routine/netlify多种入口分别指向lib/node、lib/browser、lib/edge三个构建产物对应多 bundle 支持0.1.0 引入。内容获取fetchOneEntry 与 fetchEntries 完整参数SDK 的核心数据入口是fetchOneEntry返回单条内容内部调用fetchEntries并取limit: 1的首项与fetchEntries返回分页数组。其实现位于 packages/sdks/src/functions/get-content/index.ts参数类型定义在 packages/sdks/src/functions/get-content/types.ts。import { fetchOneEntry } from builder.io/sdk-angular; const content await fetchOneEntry({ apiKey: YOUR_API_KEY, model: page, userAttributes: { urlPath: /, device: mobile, }, });GetContentOptions的核心参数参数类型默认值 / 说明modelstring必填要获取内容的模型名apiKeystring必填公开 API Keylimitnumber1fetchOneEntry 固定为 1offsetnumber0分页偏移userAttributesRecordstring, any用户属性用于定向如urlPath、returnVisitor、device随userAttributesJSON 参数发送queryRecordstring, anyMongoDB 风格查询如{ data: { myCustomField: { $gt: 20 } } }会被扁平化后写入 URLlocalestring自动解析本地化字段见 0.17.1、0.19.3 的 locale 修复enrichboolean是否解析多级引用enrichOptionsEnrichOptions约束引用解析行为0.25.13 新增fields/omitstring字段白名单/黑名单omit优先于fieldscanTrackbooleantrue置 false 时禁用 A/B 测试与 Cookie 定向cacheSecondsnumber缓存秒数写入 Cache-Control max-agestaleCacheSecondsnumberstale-while-revalidate 的陈旧缓存时长sort{ [key]: 1 \| -1 }排序如{ createdDate: 1 }includeUnpublishedbooleanfalse是否包含草稿apiVersionv3目前仅支持v3apiHoststring默认https://cdn.builder.io0.2.23 新增fetch/fetchOptions—覆盖全局 fetch 及其 init 参数URL 的组装逻辑在 generate-content-url.ts 中可查证缺少apiKey会直接抛出Missing API key非v3的apiVersion会抛出Invalid apiVersionomit的默认值是meta.componentsUsed对应 0.18.10 的修复noTraverse参数在limit ! 1时为true以优化列表性能。enrichOptions精细控制引用解析0.25.13EnrichOptionstypes.ts允许在开启enrich后约束引用解析的深度与字段await fetchOneEntry({ apiKey, model: page, enrich: true, enrichOptions: { enrichLevel: 2, // 嵌套引用最多解析 2 层 model: { product: { fields: id,name,data.price, // 每模型包含字段 omit: data.blocks, // 或省略字段 }, }, }, });其中enrichLevel决定嵌套引用解析层数层数越高响应体越大应尽量取业务所需的最低层数model按模型名提供fields/omit白黑名单。这些约束不仅影响请求还会同步告知 Visual Editor 站点使用了哪些约束条件。只有enrich: true时该选项才会被序列化进enrichOptions查询参数见 generate-content-url.ts。错误处理语义0.17.00.17.0 是一个 Breaking ChangefetchEntries与fetchOneEntry此前会吞掉一切错误并返回null此后fetch抛出的任何错误、或 Builder API 返回的任何非成功响应都会直接向上抛出见 index.ts 中throw content的实现。这意味着调用方必须自行 try/catch并根据null未命中与异常请求失败区分两种情形。渲染Content 组件与标准接入方式获取到内容后通过builder-content组件渲染。SDK 的 READMEpackages/sdks/output/angular/README.md给出了一个完整的独立组件示例import { Component } from angular/core; import { Content, fetchOneEntry, type BuilderContent } from builder.io/sdk-angular; Component({ selector: app-catchall, standalone: true, imports: [Content], template: if (content) { builder-content [model]model [content]content [apiKey]apiKey/builder-content } else { div404 - Content not found/div } , }) export class CatchAllComponent { apiKey YOUR_API_KEY; model page; content: BuilderContent | null null; async ngOnInit() { const urlPath window.location.pathname || ; const content await fetchOneEntry({ apiKey: this.apiKey, model: this.model, userAttributes: { urlPath }, }); if (!content) return; this.content content; } }要点组件选择器是builder-content0.2.14 将导出选择器修正为builder-content以兼容 Angular v180.2.10 也将content-variants选择器改回content。model与content是必填 props0.18.0 Breaking ChangeapiKey可额外传入。nonceprop0.2.1可为 SDK 内联生成的style/script标签设置nonce属性便于与 CSP 策略配合。BlocksWrapperProps0.18.13允许为单个blocks实例覆写全局 props覆盖时局部 props 完全替换全局 props除非手动合并详见 CHANGELOG 中的builderContext.BlocksWrapperProps合并示例。SSR 注意事项0.17.4 起Angular SSR v17 应用从 Content 层面跳过 hydration因为 Angular 不支持对动态创建的元素做 hydration同时 0.23.1 修复了从 SSR 渲染页面路由跳转时的 hydration 问题。信号驱动重构Angular 17 的响应式基础0.21.00.21.0 是 SDK 历史上最重要的重构 Breaking Change整个 SDK 迁移到 Angular v17 的信号体系signals、computed、inputs、声明式语句。CHANGELOG 明示了两个收益重算时机收窄只有当依赖的信号更新时才重新计算而不是每个变更检测周期都重算渲染范围收窄带子组件的组件不再因任何变更而整棵重渲染消除了 Visual Editor 中的卡顿交互。从 0.25.7 的修复可以进一步印证这一内部机制props.content更新钩子被编译为 Angulareffect()它跟踪函数体内实际读取到的所有信号而非声明的依赖列表因此任何无关的 context 更新都可能重新触发合并逻辑导致编辑器里的改动被页面初次加载的props.content覆盖。修复方式是为合并加上prevContent守卫与相邻的props.data、props.locale钩子采用同一模式。配套的版本门控在 0.25.4被弃用的allowSignalWriteseffect 选项不再被无条件丢弃而是按运行时 Angular 版本VERSION.major 19决定是否传递从而在 Angular 19 上消除弃用告警同时保持对低版本的向后兼容。自定义组件注册registerComponent 与 ComponentInfoSDK 允许注册自定义组件供可视化编辑器使用注册信息通过builder.registerComponent消息序列化后发送给编辑器见 register-component.ts。类型定义在 packages/sdks/src/types/components.ts其中包括name唯一组件名可以用同名注册覆盖内置组件如Textinputs输入 schema含type、required、autoFocus、bubble、defaultValue等字段group?: string0.25.10 新增把自定义组件归入编辑器插入菜单中自己的折叠分组相同group的组件聚合在一起未设置或为空时回退到默认的 Custom Components 分组canHaveChildren/noWrap/fragment子节点与包裹元素行为models限定组件可用的模型列表0.2.3 修复requiredPermissions按用户权限限制组件可见性override覆盖内置组件时跳过默认特殊行为如 Image 的宽高比编辑器、Columns 的列编辑器hooks自定义生命周期钩子meta0.17.1 新增组件元信息。shouldReceiveBuilderProps精确控制 Builder props 注入注册组件的shouldReceiveBuilderProps配置决定 SDK 是否向组件注入builderBlock、builderContext、builderComponents、builderLinkComponent四个 Builder props。0.1.0 引入时默认值builderBlock: true、builderContext: true、其余false并给出按需覆写的示例如只保留builderBlock与builderComponents0.2.0 将其改为全部默认false——默认不再注入任何 Builder props只有显式打开对应开关才注入。仓库中的内置组件是很好的参照accordion/component-info.ts、columns/component-info.ts、form/component-info.ts、symbol/component-info.ts 四者都全量开启button/component-info.ts 只开启builderLinkComponentimage/component-info.ts 只开启builderBlock。输入回调与序列化0.2.19 为自定义组件输入的onChange增加了第二个参数previousOptions回调在旧 options 状态下触发前保留快照且支持异步函数0.17.10.2.9 / 0.2.5 保证注册信息与插件中的函数如字段上的showIf函数可以被正确序列化0.25.11 进一步让showIf回调能接收父级参数并通过context.locale读取编辑器当前 locale0.25.10 同时修复了 Image 组件在 alt 文本为空时渲染显式空alt属性避免无障碍语义丢失。个性化与 A/B 测试setClientUserAttributes写入用户属性 CookiesetClientUserAttributes自 0.17.7 导出用于设置 Builder 的用户属性 Cookie该 Cookie 被 Personalization Containers个性化容器用来决定渲染哪个变体import { setClientUserAttributes } from builder.io/sdk-angular; setClientUserAttributes({ device: tablet, });其底层实现在 packages/sdks/src/helpers/user-attributes.ts调用userAttributesService.setUserAttributes把新属性与已有属性合并后写入名为builder.userAttributes的 Cookie并通知所有订阅者在非浏览器环境SSR下直接跳过写入。注意canTrack: false时不会写入 Cookie0.0.6 还修复过 Symbols 中canTrackfalse不被尊重的问题。A/B 测试的脚本注入策略A/B 测试0.18.3 引入支持相关内联脚本的注入经历了一个引入 → 去重 → 回退 → 再修复的演进0.25.2 与 0.25.3先移除 DOM 中重复插入的 A/B 测试脚本随即因引发 hydration 回归而回退0.25.5window.builderIoAbTest/window.builderIoRenderContent初始化脚本改为仅在 Content 实际渲染 A/B 变体时才注入且定义为幂等、在 hydration 目标上自移除从而在不做客户端 DOM 变更的前提下避免重复注入0.25.9同样的策略推广到个性化脚本——window.builderIoPersonalization/window.filterWithCustomTargeting/window.updateVisibilityStylesScript此前每个顶层Content都会注入一次无论是否存在 Variant Container现在只由实际包含个性化块的Content注入定义同样幂等。另外fetchEntries/fetchOneEntry在浏览器端会通过handleABTesting在客户端导航场景直接处理 A/B 测试见 get-content/index.ts0.18.2 修复了/track调用在默认与变体场景下重复上报的校验逻辑0.24.1 修复了trackConversion方法。0.25.12 修复了 Builder Studio 定向请求中布尔型用户属性的处理。可视化编辑subscribeToEditor 与编辑器通信可视化编辑依赖 SDK 与编辑器 iframe 之间的 postMessage 通信。0.18.0 对subscribeToEditor做了破坏性改造参数从位置参数改为具名参数对象且apiKey变为必填// 旧写法已废弃 subscribeToEditor(page, () { ... }, { trustedHosts: [...] }); // 新写法 subscribeToEditor({ apiKey: ..., model: ..., trustedHosts: [...], callback: () { ... }, });编辑器消息的接收端在 packages/sdks/src/helpers/subscribe-to-editor.ts每次收到 MessageEvent 都会先经过isFromTrustedHost(trustedHosts, event)校验然后按消息类型分发到builder.configureSdk、builder.triggerAnimation、builder.resetState、builder.contentUpdate等回调。0.25.6 加强了来源校验——改用精确的可信主机名比对并拒绝格式非法或非 HTTP(S) 的 origin0.0.8 起就要求先确认e.origin是合法 URL。可视化编辑相关的历史修复还包括0.18.1编辑器 iframe 中修改输入值能即时触发变更0.18.4Custom Code 块的代码修改实时反映、修复nativeElement找不到的问题0.17.3 起支持嵌入 iframe0.18.6 / 0.18.7 / 0.18.9修复可视化编辑时新子块被添加到顶部的问题Section 等使用 children 渲染的组件0.18.7 引入ngAfterContentChecked钩子并补充详尽注释0.25.7修复编辑器改动被初次渲染内容覆盖的回归即前文effect()跟踪问题0.18.12Symbol 条目在编辑器中变化时加载正确内容0.17.2支持在 Builder Visual Editor 的 Studio 标签中预览内容。图像与多媒体块的能力演进Image / Video / RawImg 块的优化贯穿整个版本历史是性能与功能并重的典型模块响应式图片0.19.0 为 RawImg 组件添加srcset并给 Video 组件接入 Intersection Observer 实现视口懒加载0.19.1 给 RawImg 加loadinglazy0.25.8 在 Gen2 SDK 中暴露 Image 的sizes字段并修复响应式源的选择逻辑加载策略0.0.7 为 Image 块增加highPriority选项实现 eager 加载0.17.9 为 video 元素增加懒加载0.17.6 移除 Video 块的 z-index避免遮挡子元素文件类型0.0.9 支持 Image 块上传webp0.17.1 扩展了 Image/Video 块允许的文件类型0.0.9 同时移除了 Embed 块逻辑中硬编码的iframelyAPI key0.2.3 修复 SVG 图片冗余srcset0.18.8 为图片增加title选项表单块0.0.10 支持 TextArea 块并修复 Select/TextArea 的required选项0.17.5 修复 Form 块重复渲染 children0.18.15 修复表单提交错误处理0.20.1 修复表单提交应使用 radio 的值而非 name。运行时与多环境构建node / browser / edgeSDK 针对不同运行环境产出独立 bundle0.1.0 引入多 bundle 支持构建脚本见 packages/sdks/output/angular/package.jsonbuild依次执行build:node、build:browser、build:edge产物输出到lib/下的node/browser/edge三个目录。Node 端代码执行依赖isolated-vm沙箱解释执行 JS 代码块见 packages/sdks/src/functions/evaluate/node-runtime。0.2.17 修复了 arm64 机器运行 Node 20 时禁用initializeNodeRuntime()的问题0.24.0 消除长时间运行 Node.js 进程中的内存泄漏0.22.3 保证只有导入 edge build 时才使用 edge runtime。SSR 支持0.1.0 为 A/B 测试与 Symbols 提供 SSR0.2.2 将onInit转换为服务端与客户端都执行的ngOnInit而onMount/onUpdate只在浏览器执行带浏览器判断的ngOnInit/ngOnChanges0.2.24 修复 Builder children 块未被 SSR 的问题。调试0.2.26 支持在process.env.DEBUGtrue时记录 SDK 命中的每个 API URL。版本演进路线图从 0.0.1 的 alpha 至今SDK 的演进可归纳为几个关键节点版本里程碑0.0.1 – 0.0.10alpha 起步Angular 16.2 支持、多 bundle、TextArea/WebP 等基础能力0.1.0 – 0.2.0shouldReceiveBuilderProps引入并默认收敛为全关闭SSR A/B 测试与 Symbols0.17.0 – 0.18.0获取 API 抛错语义、subscribeToEditor具名参数化、model/content必填、A/B 测试支持0.21.0全面信号化重构最低 Angular 17.3.00.22.x – 0.25.x脚本注入去重与幂等、Visual Editor 修复、group分组、enrichOptions对照 CHANGELOGpackages/sdks/output/angular/CHANGELOG.md可以看到每一次 Patch 都与具体的源码行为一一对应这也是将 CHANGELOG 作为 SDK 行为说明书使用的价值所在它记录了每个参数的引入时机如apiHost在 0.2.23、nonce在 0.2.1、每个 Breaking Change 的迁移方式以及大量可视化编辑、SSR、个性化场景下的边界修复。升级 SDK 前对照该文件逐条排查影响面是避免回归的最直接手段。实践建议总结内容获取优先使用fetchOneEntryuserAttributes至少包含urlPath完成首屏渲染列表场景使用fetchEntries配合limit/offset/query/sort需要引用解析时开启enrich并用enrichOptions收敛体积。错误处理0.17.0 之后fetchOneEntry可能抛异常务必 try/catch并用null与异常区分无内容与请求失败。组件注册自定义组件默认不再收到任何 Builder props按需开启shouldReceiveBuilderProps用group归组插入菜单项用models限制可用模型。个性化与 A/B通过setClientUserAttributes在客户端更新定向属性理解脚本注入的幂等策略避免页面多Content时的重复脚本问题。运行时选型Node 24 / 22 环境使用 node build边缘函数场景按条件导入 edge buildAngular 应用需确保版本17.3.0。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
@builder.io/sdk-angular 从零到实战：Builder.io Gen2 Angular SDK 能力全景与版本演进解析
builder.io/sdk-angular 从零到实战Builder.io Gen2 Angular SDK 能力全景与版本演进解析【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder导读本文以builder.io/sdk-angularBuilder.io Gen2 Angular SDK的完整变更记录为主线结合本仓库packages/sdks/output/angular的产物与packages/sdks/src的 Mitosis 源码系统讲解该 SDK 的内容获取、渲染、个性化、A/B 测试、可视化编辑与多运行时构建能力。读完本文你将掌握fetchOneEntry/fetchEntries的完整参数体系、Content组件的正确用法、自定义组件注册协议以及如何为 Angular 17 应用接入 Builder 无头可视化开发能力。SDK 定位与安装builder.io/sdk-angular是 Builder 的 Gen2 Angular SDK与 React、Vue、Svelte、Qwik 等 SDK 一样由 Mitosis 从同一份跨框架源码编译生成其 Mitosis 源位于 packages/sdks/src。当前仓库中的产物版本为 0.25.13见 packages/sdks/output/angular/package.json。安装与版本约束npm install builder.io/sdk-angular该 SDK 要求 Angular 版本17.3.0peer 依赖为angular/common与angular/core见 package.json。这一点与 0.21.0 的 Breaking Change直接相关SDK 全面转向 Angular 17 的信号signals体系。运行时依赖仅有isolated-vm用于 Node 端代码块解释执行与tslib。isolated-vm在 0.23.0 从5.0.0升级到6.0.0以支持 Node v24同时弃用 Node 18 与 Node 20因此生产环境需使用 Node 220.0.5 时支持 Node v22或 Node 24。包通过条件导出exports提供node/browser/edge/edge-routine/netlify多种入口分别指向lib/node、lib/browser、lib/edge三个构建产物对应多 bundle 支持0.1.0 引入。内容获取fetchOneEntry 与 fetchEntries 完整参数SDK 的核心数据入口是fetchOneEntry返回单条内容内部调用fetchEntries并取limit: 1的首项与fetchEntries返回分页数组。其实现位于 packages/sdks/src/functions/get-content/index.ts参数类型定义在 packages/sdks/src/functions/get-content/types.ts。import { fetchOneEntry } from builder.io/sdk-angular; const content await fetchOneEntry({ apiKey: YOUR_API_KEY, model: page, userAttributes: { urlPath: /, device: mobile, }, });GetContentOptions的核心参数参数类型默认值 / 说明modelstring必填要获取内容的模型名apiKeystring必填公开 API Keylimitnumber1fetchOneEntry 固定为 1offsetnumber0分页偏移userAttributesRecordstring, any用户属性用于定向如urlPath、returnVisitor、device随userAttributesJSON 参数发送queryRecordstring, anyMongoDB 风格查询如{ data: { myCustomField: { $gt: 20 } } }会被扁平化后写入 URLlocalestring自动解析本地化字段见 0.17.1、0.19.3 的 locale 修复enrichboolean是否解析多级引用enrichOptionsEnrichOptions约束引用解析行为0.25.13 新增fields/omitstring字段白名单/黑名单omit优先于fieldscanTrackbooleantrue置 false 时禁用 A/B 测试与 Cookie 定向cacheSecondsnumber缓存秒数写入 Cache-Control max-agestaleCacheSecondsnumberstale-while-revalidate 的陈旧缓存时长sort{ [key]: 1 \| -1 }排序如{ createdDate: 1 }includeUnpublishedbooleanfalse是否包含草稿apiVersionv3目前仅支持v3apiHoststring默认https://cdn.builder.io0.2.23 新增fetch/fetchOptions—覆盖全局 fetch 及其 init 参数URL 的组装逻辑在 generate-content-url.ts 中可查证缺少apiKey会直接抛出Missing API key非v3的apiVersion会抛出Invalid apiVersionomit的默认值是meta.componentsUsed对应 0.18.10 的修复noTraverse参数在limit ! 1时为true以优化列表性能。enrichOptions精细控制引用解析0.25.13EnrichOptionstypes.ts允许在开启enrich后约束引用解析的深度与字段await fetchOneEntry({ apiKey, model: page, enrich: true, enrichOptions: { enrichLevel: 2, // 嵌套引用最多解析 2 层 model: { product: { fields: id,name,data.price, // 每模型包含字段 omit: data.blocks, // 或省略字段 }, }, }, });其中enrichLevel决定嵌套引用解析层数层数越高响应体越大应尽量取业务所需的最低层数model按模型名提供fields/omit白黑名单。这些约束不仅影响请求还会同步告知 Visual Editor 站点使用了哪些约束条件。只有enrich: true时该选项才会被序列化进enrichOptions查询参数见 generate-content-url.ts。错误处理语义0.17.00.17.0 是一个 Breaking ChangefetchEntries与fetchOneEntry此前会吞掉一切错误并返回null此后fetch抛出的任何错误、或 Builder API 返回的任何非成功响应都会直接向上抛出见 index.ts 中throw content的实现。这意味着调用方必须自行 try/catch并根据null未命中与异常请求失败区分两种情形。渲染Content 组件与标准接入方式获取到内容后通过builder-content组件渲染。SDK 的 READMEpackages/sdks/output/angular/README.md给出了一个完整的独立组件示例import { Component } from angular/core; import { Content, fetchOneEntry, type BuilderContent } from builder.io/sdk-angular; Component({ selector: app-catchall, standalone: true, imports: [Content], template: if (content) { builder-content [model]model [content]content [apiKey]apiKey/builder-content } else { div404 - Content not found/div } , }) export class CatchAllComponent { apiKey YOUR_API_KEY; model page; content: BuilderContent | null null; async ngOnInit() { const urlPath window.location.pathname || ; const content await fetchOneEntry({ apiKey: this.apiKey, model: this.model, userAttributes: { urlPath }, }); if (!content) return; this.content content; } }要点组件选择器是builder-content0.2.14 将导出选择器修正为builder-content以兼容 Angular v180.2.10 也将content-variants选择器改回content。model与content是必填 props0.18.0 Breaking ChangeapiKey可额外传入。nonceprop0.2.1可为 SDK 内联生成的style/script标签设置nonce属性便于与 CSP 策略配合。BlocksWrapperProps0.18.13允许为单个blocks实例覆写全局 props覆盖时局部 props 完全替换全局 props除非手动合并详见 CHANGELOG 中的builderContext.BlocksWrapperProps合并示例。SSR 注意事项0.17.4 起Angular SSR v17 应用从 Content 层面跳过 hydration因为 Angular 不支持对动态创建的元素做 hydration同时 0.23.1 修复了从 SSR 渲染页面路由跳转时的 hydration 问题。信号驱动重构Angular 17 的响应式基础0.21.00.21.0 是 SDK 历史上最重要的重构 Breaking Change整个 SDK 迁移到 Angular v17 的信号体系signals、computed、inputs、声明式语句。CHANGELOG 明示了两个收益重算时机收窄只有当依赖的信号更新时才重新计算而不是每个变更检测周期都重算渲染范围收窄带子组件的组件不再因任何变更而整棵重渲染消除了 Visual Editor 中的卡顿交互。从 0.25.7 的修复可以进一步印证这一内部机制props.content更新钩子被编译为 Angulareffect()它跟踪函数体内实际读取到的所有信号而非声明的依赖列表因此任何无关的 context 更新都可能重新触发合并逻辑导致编辑器里的改动被页面初次加载的props.content覆盖。修复方式是为合并加上prevContent守卫与相邻的props.data、props.locale钩子采用同一模式。配套的版本门控在 0.25.4被弃用的allowSignalWriteseffect 选项不再被无条件丢弃而是按运行时 Angular 版本VERSION.major 19决定是否传递从而在 Angular 19 上消除弃用告警同时保持对低版本的向后兼容。自定义组件注册registerComponent 与 ComponentInfoSDK 允许注册自定义组件供可视化编辑器使用注册信息通过builder.registerComponent消息序列化后发送给编辑器见 register-component.ts。类型定义在 packages/sdks/src/types/components.ts其中包括name唯一组件名可以用同名注册覆盖内置组件如Textinputs输入 schema含type、required、autoFocus、bubble、defaultValue等字段group?: string0.25.10 新增把自定义组件归入编辑器插入菜单中自己的折叠分组相同group的组件聚合在一起未设置或为空时回退到默认的 Custom Components 分组canHaveChildren/noWrap/fragment子节点与包裹元素行为models限定组件可用的模型列表0.2.3 修复requiredPermissions按用户权限限制组件可见性override覆盖内置组件时跳过默认特殊行为如 Image 的宽高比编辑器、Columns 的列编辑器hooks自定义生命周期钩子meta0.17.1 新增组件元信息。shouldReceiveBuilderProps精确控制 Builder props 注入注册组件的shouldReceiveBuilderProps配置决定 SDK 是否向组件注入builderBlock、builderContext、builderComponents、builderLinkComponent四个 Builder props。0.1.0 引入时默认值builderBlock: true、builderContext: true、其余false并给出按需覆写的示例如只保留builderBlock与builderComponents0.2.0 将其改为全部默认false——默认不再注入任何 Builder props只有显式打开对应开关才注入。仓库中的内置组件是很好的参照accordion/component-info.ts、columns/component-info.ts、form/component-info.ts、symbol/component-info.ts 四者都全量开启button/component-info.ts 只开启builderLinkComponentimage/component-info.ts 只开启builderBlock。输入回调与序列化0.2.19 为自定义组件输入的onChange增加了第二个参数previousOptions回调在旧 options 状态下触发前保留快照且支持异步函数0.17.10.2.9 / 0.2.5 保证注册信息与插件中的函数如字段上的showIf函数可以被正确序列化0.25.11 进一步让showIf回调能接收父级参数并通过context.locale读取编辑器当前 locale0.25.10 同时修复了 Image 组件在 alt 文本为空时渲染显式空alt属性避免无障碍语义丢失。个性化与 A/B 测试setClientUserAttributes写入用户属性 CookiesetClientUserAttributes自 0.17.7 导出用于设置 Builder 的用户属性 Cookie该 Cookie 被 Personalization Containers个性化容器用来决定渲染哪个变体import { setClientUserAttributes } from builder.io/sdk-angular; setClientUserAttributes({ device: tablet, });其底层实现在 packages/sdks/src/helpers/user-attributes.ts调用userAttributesService.setUserAttributes把新属性与已有属性合并后写入名为builder.userAttributes的 Cookie并通知所有订阅者在非浏览器环境SSR下直接跳过写入。注意canTrack: false时不会写入 Cookie0.0.6 还修复过 Symbols 中canTrackfalse不被尊重的问题。A/B 测试的脚本注入策略A/B 测试0.18.3 引入支持相关内联脚本的注入经历了一个引入 → 去重 → 回退 → 再修复的演进0.25.2 与 0.25.3先移除 DOM 中重复插入的 A/B 测试脚本随即因引发 hydration 回归而回退0.25.5window.builderIoAbTest/window.builderIoRenderContent初始化脚本改为仅在 Content 实际渲染 A/B 变体时才注入且定义为幂等、在 hydration 目标上自移除从而在不做客户端 DOM 变更的前提下避免重复注入0.25.9同样的策略推广到个性化脚本——window.builderIoPersonalization/window.filterWithCustomTargeting/window.updateVisibilityStylesScript此前每个顶层Content都会注入一次无论是否存在 Variant Container现在只由实际包含个性化块的Content注入定义同样幂等。另外fetchEntries/fetchOneEntry在浏览器端会通过handleABTesting在客户端导航场景直接处理 A/B 测试见 get-content/index.ts0.18.2 修复了/track调用在默认与变体场景下重复上报的校验逻辑0.24.1 修复了trackConversion方法。0.25.12 修复了 Builder Studio 定向请求中布尔型用户属性的处理。可视化编辑subscribeToEditor 与编辑器通信可视化编辑依赖 SDK 与编辑器 iframe 之间的 postMessage 通信。0.18.0 对subscribeToEditor做了破坏性改造参数从位置参数改为具名参数对象且apiKey变为必填// 旧写法已废弃 subscribeToEditor(page, () { ... }, { trustedHosts: [...] }); // 新写法 subscribeToEditor({ apiKey: ..., model: ..., trustedHosts: [...], callback: () { ... }, });编辑器消息的接收端在 packages/sdks/src/helpers/subscribe-to-editor.ts每次收到 MessageEvent 都会先经过isFromTrustedHost(trustedHosts, event)校验然后按消息类型分发到builder.configureSdk、builder.triggerAnimation、builder.resetState、builder.contentUpdate等回调。0.25.6 加强了来源校验——改用精确的可信主机名比对并拒绝格式非法或非 HTTP(S) 的 origin0.0.8 起就要求先确认e.origin是合法 URL。可视化编辑相关的历史修复还包括0.18.1编辑器 iframe 中修改输入值能即时触发变更0.18.4Custom Code 块的代码修改实时反映、修复nativeElement找不到的问题0.17.3 起支持嵌入 iframe0.18.6 / 0.18.7 / 0.18.9修复可视化编辑时新子块被添加到顶部的问题Section 等使用 children 渲染的组件0.18.7 引入ngAfterContentChecked钩子并补充详尽注释0.25.7修复编辑器改动被初次渲染内容覆盖的回归即前文effect()跟踪问题0.18.12Symbol 条目在编辑器中变化时加载正确内容0.17.2支持在 Builder Visual Editor 的 Studio 标签中预览内容。图像与多媒体块的能力演进Image / Video / RawImg 块的优化贯穿整个版本历史是性能与功能并重的典型模块响应式图片0.19.0 为 RawImg 组件添加srcset并给 Video 组件接入 Intersection Observer 实现视口懒加载0.19.1 给 RawImg 加loadinglazy0.25.8 在 Gen2 SDK 中暴露 Image 的sizes字段并修复响应式源的选择逻辑加载策略0.0.7 为 Image 块增加highPriority选项实现 eager 加载0.17.9 为 video 元素增加懒加载0.17.6 移除 Video 块的 z-index避免遮挡子元素文件类型0.0.9 支持 Image 块上传webp0.17.1 扩展了 Image/Video 块允许的文件类型0.0.9 同时移除了 Embed 块逻辑中硬编码的iframelyAPI key0.2.3 修复 SVG 图片冗余srcset0.18.8 为图片增加title选项表单块0.0.10 支持 TextArea 块并修复 Select/TextArea 的required选项0.17.5 修复 Form 块重复渲染 children0.18.15 修复表单提交错误处理0.20.1 修复表单提交应使用 radio 的值而非 name。运行时与多环境构建node / browser / edgeSDK 针对不同运行环境产出独立 bundle0.1.0 引入多 bundle 支持构建脚本见 packages/sdks/output/angular/package.jsonbuild依次执行build:node、build:browser、build:edge产物输出到lib/下的node/browser/edge三个目录。Node 端代码执行依赖isolated-vm沙箱解释执行 JS 代码块见 packages/sdks/src/functions/evaluate/node-runtime。0.2.17 修复了 arm64 机器运行 Node 20 时禁用initializeNodeRuntime()的问题0.24.0 消除长时间运行 Node.js 进程中的内存泄漏0.22.3 保证只有导入 edge build 时才使用 edge runtime。SSR 支持0.1.0 为 A/B 测试与 Symbols 提供 SSR0.2.2 将onInit转换为服务端与客户端都执行的ngOnInit而onMount/onUpdate只在浏览器执行带浏览器判断的ngOnInit/ngOnChanges0.2.24 修复 Builder children 块未被 SSR 的问题。调试0.2.26 支持在process.env.DEBUGtrue时记录 SDK 命中的每个 API URL。版本演进路线图从 0.0.1 的 alpha 至今SDK 的演进可归纳为几个关键节点版本里程碑0.0.1 – 0.0.10alpha 起步Angular 16.2 支持、多 bundle、TextArea/WebP 等基础能力0.1.0 – 0.2.0shouldReceiveBuilderProps引入并默认收敛为全关闭SSR A/B 测试与 Symbols0.17.0 – 0.18.0获取 API 抛错语义、subscribeToEditor具名参数化、model/content必填、A/B 测试支持0.21.0全面信号化重构最低 Angular 17.3.00.22.x – 0.25.x脚本注入去重与幂等、Visual Editor 修复、group分组、enrichOptions对照 CHANGELOGpackages/sdks/output/angular/CHANGELOG.md可以看到每一次 Patch 都与具体的源码行为一一对应这也是将 CHANGELOG 作为 SDK 行为说明书使用的价值所在它记录了每个参数的引入时机如apiHost在 0.2.23、nonce在 0.2.1、每个 Breaking Change 的迁移方式以及大量可视化编辑、SSR、个性化场景下的边界修复。升级 SDK 前对照该文件逐条排查影响面是避免回归的最直接手段。实践建议总结内容获取优先使用fetchOneEntryuserAttributes至少包含urlPath完成首屏渲染列表场景使用fetchEntries配合limit/offset/query/sort需要引用解析时开启enrich并用enrichOptions收敛体积。错误处理0.17.0 之后fetchOneEntry可能抛异常务必 try/catch并用null与异常区分无内容与请求失败。组件注册自定义组件默认不再收到任何 Builder props按需开启shouldReceiveBuilderProps用group归组插入菜单项用models限制可用模型。个性化与 A/B通过setClientUserAttributes在客户端更新定向属性理解脚本注入的幂等策略避免页面多Content时的重复脚本问题。运行时选型Node 24 / 22 环境使用 node build边缘函数场景按条件导入 edge buildAngular 应用需确保版本17.3.0。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
