尧图网页设计 
Builder.io Swell 插件实战指南把 Swell 商品与集合数据无缝接入 Builder.io 内容平台【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本文围绕 Builder.io 官方开源仓库中的plugins/swell插件讲解如何将 Swell 电商平台的商品Product与集合Collection数据接入 Builder.io 的内容编辑与个性化体系。你将掌握插件的安装与鉴权方式、六种新增字段类型在自定义定向Custom Targeting、组件模型字段Component Model Fields与符号输入Symbol Inputs三种场景下的用法理解字段值如何被自动解析为 Builder.ioRequest对象并学会本地开发、调试与发布该插件。插件定位为 Builder.io 打开 Swell 数据通道Swell 是一个 API 优先的电商平台headless commerce商品、分类、订单等数据都通过 REST/GraphQL API 暴露。plugins/swell插件的核心目标正如其 README 所述Easily connect your Swell data to your Builder.io content!即让内容编辑者在 Builder.io 的模型Model、符号Symbol和自定义组件Custom Component中直接搜索、选择 Swell 商品或集合并把选中结果作为字段值写入内容。插件本质是一个 Builder.io 平台插件Plugin通过 Builder 提供的插件注册机制动态扩展编辑器的字段类型与定向能力。在 plugins/swell/src/plugin.ts 中插件调用builder.io/commerce-plugin-tools提供的registerCommercePlugin完成注册import { registerCommercePlugin } from builder.io/commerce-plugin-tools; import swell from swell-js; registerCommercePlugin( { name: Swell, // should always match package.json package name id: builder.io/plugin-swell, ... }, async settings { ... } );registerCommercePlugin是 Builder.io 为电商类插件提供的一站式基座同一机制被 plugins/shopify/src/plugin.ts、plugins/bigcommerce/src/plugin.ts、plugins/vtex/src/plugin.ts 等大量电商插件复用它约定了product与category两组统一资源接口findById、findByHandle、search、getRequestObject。Swell 插件只需按此契约实现 Swell API 的适配即可自动获得 Builder 编辑器中的搜索弹窗、字段解析与定向能力。安装插件与鉴权配置安装插件在 Builder.io 后台完成无需改动任何前端代码登录后进入Account Organization对应 README 中的 builder.io/account/organization页面在插件列表中选中builder.io/plugin-swell点击保存Save此时系统会提示输入 Swell 商店的连接凭据。凭据部分需要注意 README 与源码的一处差异README 安装段落写作youll be prompted for storeId and secretKey而插件实际注册的配置项见 plugins/swell/src/plugin.ts是storeId与publicKey两个必填项helperText 明确指示从 Swell 商店设置的 API Keys Public api key 中获取settings: [ { name: storeId, type: string, required: true, helperText: Get your Store ID from swell store settings https://swell.store/docs/api/?javascript#authentication, }, { name: publicKey, type: string, required: true, helperText: Get your Public key from swell store settings API keys Public api key https://swell.store/docs/api/?javascript#authentication, }, ], ctaText: Connect your swell.is store,连接按钮文案为 Connect your swell.is store。鉴权完成后插件会执行swell.init(storeId, publicKey)见 plugins/swell/src/plugin.ts初始化swell-js客户端。需要说明storeId 与 publicKey 都是公开信息public key 仅用于只读的 storefront 请求因此可以安全地以明文形式出现在前端插件中如果后续需要写入订单等敏感操作则应使用服务端密钥secret key而非该 publicKey。安装成功后编辑器中将出现六种新的字段类型它们分别适用于三种上下文自定义定向属性、组件模型字段与符号输入。下表是六种字段类型的速览字段类型适用上下文作用Swell Product自定义定向 / 符号输入按商品 ID 定向或搜索选择商品Swell Product Handle自定义定向按商品 handleslug定向Swell Collection自定义定向 / 符号输入按集合 ID 定向或搜索选择集合Swell Collection Handle自定义定向按集合 handleslug定向Swell Product Preview组件模型字段动态拼接商品模板的预览 URLSwell Collection Preview组件模型字段动态拼接集合模板的预览 URL场景一自定义定向Custom TargetingBuilder.io 的自定义定向允许内容按任意属性attribute做细分投放。Swell 插件将商品与集合扩展为可用的定向类型当某个内容条目设置了Swell Product类型的目标属性时只有访问上下文中携带了对应商品 ID 的用户才会命中该内容。要让服务端渲染SSR或客户端渲染CSR正确识别需要先在宿主站点设置目标属性。客户端渲染场景下使用builder.setUserAttributes设置当前上下文见 plugins/swell/src/plugin.ts 对应的 README 示例builder.setUserAttributes({ product: currentProduct.id, });服务端场景下则把用户属性作为查询参数传给内容 APIQuery API 的userAttributes参数或在 Gatsby、Next.js 中通过 GraphQL API 的 targeting 参数传入。例如通过 Query API 请求时大致形态为// https://cdn.builder.io/api/v1/html/page?...userAttributes.productproductId各字段类型的定向语义如下Swell Product定向到字段值等于商品 ID的上下文。需要在宿主环境用上述任一方法设置当前商品 IDSwell Product Handle若希望按商品的 handle即 URL slug而不是数字 ID 定向改用此类型。宿主环境设置builder.setUserAttributes({ product: currentProduct.handle })即可Swell Collection定向到特定集合按集合 ID 匹配宿主环境需设置集合 IDSwell Collection Handle按集合 handle 定向适合以语义化 slug 做匹配的场景。从源码角度看ID 与 handle 的解析分别由插件暴露的findById与findByHandle完成见 plugins/swell/src/plugin.ts二者都调用swell.products.get(id | handle)——Swell API 允许以 ID 或 slug 直接读取资源async findById(id: string) { const product await swell.products.get(id); return transformResource(product); }, async findByHandle(handle: string) { const product await swell.products.get(handle); return transformResource(product); },场景二组件模型字段Component Model Fields组件模型Component Model通常用于表达商品页模板或集合页模板可作用于全部或某一组商品/集合。为了让内容编辑者在编辑器中实时预览任意商品/集合对应的模板页面插件提供了两个预览字段Swell Product Preview在组件模型上添加类型为Swell Product Preview的自定义字段并给模型配置带变量的模板编辑 URL例如https://www.mystore.com/product/${previewProduct.handle}此后创建新的内容条目时Builder 会基于当前预览的商品动态地把 handle 填入 URL。官方建议为该字段设置默认值这样开发者进入模板组件开发时能直接落在某个具体的商品页而不是空 URL。Swell Collection Preview用法与 Product Preview 完全对称给模型添加Swell Collection Preview字段并把模型 URL 配置为集合模板例如https://www.mystore.com/collection/${previewCollection.handle}创建条目后handle 会基于预览集合动态填充。同样建议为字段设置默认值保证开发时稳定落在某个集合页。这两个字段依赖插件在transformResource见 plugins/swell/src/plugin.ts中返回的handle字段取自 Swell 资源的slug因此模型 URL 中可以直接引用${previewProduct.handle}/${previewCollection.handle}这样的插值const transformResource (resource: any) ({ id: resource.id, title: resource.name, handle: resource.slug, ...(resource.images { image: { src: resource.images[0]?.file.url, }, }), });场景三符号输入Symbol Inputs与 Request 对象解析当把Swell Product或Swell Collection用作符号Symbol输入字段时编辑器中的 UI 会弹出搜索框允许按关键字搜索 Swell 商品/集合。搜索由插件的search方法实现见 plugins/swell/src/plugin.ts通过swell.products.list/swell.categories.list拉取结果并注明如需分页可扩展 limit/pageasync search(search: string) { const response await swell.products.list({ search, // TODO: pagination if needed limit: 100, page: 1, }); return response.results.map(transformResource); },关键在于值形态当字段被 API、SDK 或 Builder 编辑器消费时选中的商品/集合不会被存成普通字符串而是被自动解析为一个 Builder.io 标准的Request对象{ yourFieldName: { type: builder.io/core:Request, request: { url: ... }, data: { product: { /* ... */ } } } }这个对象由插件的getRequestObject方法生成见 plugins/swell/src/plugin.tsURL 拼接规则为https://{publicKey}{storeId}.swell.store/api/products/{id}分类同理为/api/categories/{id}getRequestObject(id: string) { return { type: builder.io/core:Request as const, request: { url: https://${publicKey}${storeId}.swell.store/api/products/${id}, }, options: { product: id, }, }; },理解这一设计对内容架构很重要Request对象是 Builder.io 的延迟取数机制——字段里只保存请求描述URL真正拉取响应数据发生在渲染阶段data中的product/category是请求完成后填充的响应内容。因此内容条目天然携带可重放的数据请求既能在编辑器里预览也能在 SSR/CSR 阶段由 Builder SDK 自动请求并注入避免把易过期的商品快照硬编码进内容。本地开发把插件跑起来plugins/swell是仓库中独立的可开发插件包npm 包名为builder.io/plugin-swell版本见 plugins/swell/package.json本地开发流程如下1. 安装依赖git clone 本仓库地址 cd plugins/swell npm install2. 启动开发服务器npm start该命令等价于SERVEtrue rollup -c rollup.config.ts -w见 plugins/swell/package.json。Rollup 的 serve 插件会在1268 端口托管dist目录下的构建产物见 plugins/swell/rollup.config.ts并附带Access-Control-Allow-Origin: *与Access-Control-Allow-Private-Network响应头以兼容浏览器私有网络访问PNA预检。3. 把本地插件接入 Builder.io回到 Account Organization 的插件设置页把本地地址填入插件配置http://localhost:1268/plugin.system.js?pluginIdbuilder.io/ecom-swell-is注意Builder.io 后台是 https 站点而本地开发地址是 http。浏览器会阻止混入的不安全脚本需要在页面右上角点击盾牌图标并选择 Load unsafe scripts加载不安全脚本才能正常加载本地插件。每次修改源码后重启 Builder 页面即可看到最新版本要卸载插件直接在插件管理 UI 中移除即可。4. 验证插件效果创建一个自定义模型、自定义组件或符号在其中添加 Swell 类型字段即可编辑验证。例如给模型加一个Swell Product字段编辑器里应出现商品搜索弹窗选中后字段值显示为商品卡片含图片、标题、handle。5. 构建与发布生产构建命令为npm run build先rimraf dist清理再tscrollup打包见 plugins/swell/package.json。产物入口为dist/plugin.system.jsSystemJS 格式见 plugins/swell/rollup.config.ts。插件发布走语义化版本npm run release:dev打 dev 预发布版本用于联调合并 PR 后npm run release:patch发布补丁版本发布与测试流程详见 plugins/README.md。仓库还配置了 jest 测试与 90% 以上的覆盖率门槛见 plugins/swell/package.json为插件行为提供回归保障。插件 UI 技术栈与最佳实践Builder.io 插件体系的 UI 统一基于React与Material UI样式使用Emotion见 README 的 Frameworks 小节以及 plugins/swell/package.json 中的react、material-ui/core、emotion/core依赖。插件与宿主共享这些运行时因此 Rollup 配置将这些包显式列入external见 plugins/swell/rollup.config.ts避免重复打包导致 React 多实例问题external: [ react, builder.io/react, builder.io/app-context, material-ui/core, emotion/core, emotion/styled, mobx, react-dom, mobx-react, ],注释明确提示不要改动这份 external 列表新增依赖也应保持不被打包这是插件在 Builder 编辑器内稳定运行的前提。开发插件时遵循这一约定配合builder.io/commerce-plugin-tools的product/category资源契约即可用极少的代码让任意电商后端接入 Builder.io——这正是plugins/swell这份实现完整源码仅一个 plugin.ts 文件所展示的典型范式。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Builder.io Swell 插件实战指南：把 Swell 商品与集合数据无缝接入 Builder.io 内容平台
Builder.io Swell 插件实战指南把 Swell 商品与集合数据无缝接入 Builder.io 内容平台【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本文围绕 Builder.io 官方开源仓库中的plugins/swell插件讲解如何将 Swell 电商平台的商品Product与集合Collection数据接入 Builder.io 的内容编辑与个性化体系。你将掌握插件的安装与鉴权方式、六种新增字段类型在自定义定向Custom Targeting、组件模型字段Component Model Fields与符号输入Symbol Inputs三种场景下的用法理解字段值如何被自动解析为 Builder.ioRequest对象并学会本地开发、调试与发布该插件。插件定位为 Builder.io 打开 Swell 数据通道Swell 是一个 API 优先的电商平台headless commerce商品、分类、订单等数据都通过 REST/GraphQL API 暴露。plugins/swell插件的核心目标正如其 README 所述Easily connect your Swell data to your Builder.io content!即让内容编辑者在 Builder.io 的模型Model、符号Symbol和自定义组件Custom Component中直接搜索、选择 Swell 商品或集合并把选中结果作为字段值写入内容。插件本质是一个 Builder.io 平台插件Plugin通过 Builder 提供的插件注册机制动态扩展编辑器的字段类型与定向能力。在 plugins/swell/src/plugin.ts 中插件调用builder.io/commerce-plugin-tools提供的registerCommercePlugin完成注册import { registerCommercePlugin } from builder.io/commerce-plugin-tools; import swell from swell-js; registerCommercePlugin( { name: Swell, // should always match package.json package name id: builder.io/plugin-swell, ... }, async settings { ... } );registerCommercePlugin是 Builder.io 为电商类插件提供的一站式基座同一机制被 plugins/shopify/src/plugin.ts、plugins/bigcommerce/src/plugin.ts、plugins/vtex/src/plugin.ts 等大量电商插件复用它约定了product与category两组统一资源接口findById、findByHandle、search、getRequestObject。Swell 插件只需按此契约实现 Swell API 的适配即可自动获得 Builder 编辑器中的搜索弹窗、字段解析与定向能力。安装插件与鉴权配置安装插件在 Builder.io 后台完成无需改动任何前端代码登录后进入Account Organization对应 README 中的 builder.io/account/organization页面在插件列表中选中builder.io/plugin-swell点击保存Save此时系统会提示输入 Swell 商店的连接凭据。凭据部分需要注意 README 与源码的一处差异README 安装段落写作youll be prompted for storeId and secretKey而插件实际注册的配置项见 plugins/swell/src/plugin.ts是storeId与publicKey两个必填项helperText 明确指示从 Swell 商店设置的 API Keys Public api key 中获取settings: [ { name: storeId, type: string, required: true, helperText: Get your Store ID from swell store settings https://swell.store/docs/api/?javascript#authentication, }, { name: publicKey, type: string, required: true, helperText: Get your Public key from swell store settings API keys Public api key https://swell.store/docs/api/?javascript#authentication, }, ], ctaText: Connect your swell.is store,连接按钮文案为 Connect your swell.is store。鉴权完成后插件会执行swell.init(storeId, publicKey)见 plugins/swell/src/plugin.ts初始化swell-js客户端。需要说明storeId 与 publicKey 都是公开信息public key 仅用于只读的 storefront 请求因此可以安全地以明文形式出现在前端插件中如果后续需要写入订单等敏感操作则应使用服务端密钥secret key而非该 publicKey。安装成功后编辑器中将出现六种新的字段类型它们分别适用于三种上下文自定义定向属性、组件模型字段与符号输入。下表是六种字段类型的速览字段类型适用上下文作用Swell Product自定义定向 / 符号输入按商品 ID 定向或搜索选择商品Swell Product Handle自定义定向按商品 handleslug定向Swell Collection自定义定向 / 符号输入按集合 ID 定向或搜索选择集合Swell Collection Handle自定义定向按集合 handleslug定向Swell Product Preview组件模型字段动态拼接商品模板的预览 URLSwell Collection Preview组件模型字段动态拼接集合模板的预览 URL场景一自定义定向Custom TargetingBuilder.io 的自定义定向允许内容按任意属性attribute做细分投放。Swell 插件将商品与集合扩展为可用的定向类型当某个内容条目设置了Swell Product类型的目标属性时只有访问上下文中携带了对应商品 ID 的用户才会命中该内容。要让服务端渲染SSR或客户端渲染CSR正确识别需要先在宿主站点设置目标属性。客户端渲染场景下使用builder.setUserAttributes设置当前上下文见 plugins/swell/src/plugin.ts 对应的 README 示例builder.setUserAttributes({ product: currentProduct.id, });服务端场景下则把用户属性作为查询参数传给内容 APIQuery API 的userAttributes参数或在 Gatsby、Next.js 中通过 GraphQL API 的 targeting 参数传入。例如通过 Query API 请求时大致形态为// https://cdn.builder.io/api/v1/html/page?...userAttributes.productproductId各字段类型的定向语义如下Swell Product定向到字段值等于商品 ID的上下文。需要在宿主环境用上述任一方法设置当前商品 IDSwell Product Handle若希望按商品的 handle即 URL slug而不是数字 ID 定向改用此类型。宿主环境设置builder.setUserAttributes({ product: currentProduct.handle })即可Swell Collection定向到特定集合按集合 ID 匹配宿主环境需设置集合 IDSwell Collection Handle按集合 handle 定向适合以语义化 slug 做匹配的场景。从源码角度看ID 与 handle 的解析分别由插件暴露的findById与findByHandle完成见 plugins/swell/src/plugin.ts二者都调用swell.products.get(id | handle)——Swell API 允许以 ID 或 slug 直接读取资源async findById(id: string) { const product await swell.products.get(id); return transformResource(product); }, async findByHandle(handle: string) { const product await swell.products.get(handle); return transformResource(product); },场景二组件模型字段Component Model Fields组件模型Component Model通常用于表达商品页模板或集合页模板可作用于全部或某一组商品/集合。为了让内容编辑者在编辑器中实时预览任意商品/集合对应的模板页面插件提供了两个预览字段Swell Product Preview在组件模型上添加类型为Swell Product Preview的自定义字段并给模型配置带变量的模板编辑 URL例如https://www.mystore.com/product/${previewProduct.handle}此后创建新的内容条目时Builder 会基于当前预览的商品动态地把 handle 填入 URL。官方建议为该字段设置默认值这样开发者进入模板组件开发时能直接落在某个具体的商品页而不是空 URL。Swell Collection Preview用法与 Product Preview 完全对称给模型添加Swell Collection Preview字段并把模型 URL 配置为集合模板例如https://www.mystore.com/collection/${previewCollection.handle}创建条目后handle 会基于预览集合动态填充。同样建议为字段设置默认值保证开发时稳定落在某个集合页。这两个字段依赖插件在transformResource见 plugins/swell/src/plugin.ts中返回的handle字段取自 Swell 资源的slug因此模型 URL 中可以直接引用${previewProduct.handle}/${previewCollection.handle}这样的插值const transformResource (resource: any) ({ id: resource.id, title: resource.name, handle: resource.slug, ...(resource.images { image: { src: resource.images[0]?.file.url, }, }), });场景三符号输入Symbol Inputs与 Request 对象解析当把Swell Product或Swell Collection用作符号Symbol输入字段时编辑器中的 UI 会弹出搜索框允许按关键字搜索 Swell 商品/集合。搜索由插件的search方法实现见 plugins/swell/src/plugin.ts通过swell.products.list/swell.categories.list拉取结果并注明如需分页可扩展 limit/pageasync search(search: string) { const response await swell.products.list({ search, // TODO: pagination if needed limit: 100, page: 1, }); return response.results.map(transformResource); },关键在于值形态当字段被 API、SDK 或 Builder 编辑器消费时选中的商品/集合不会被存成普通字符串而是被自动解析为一个 Builder.io 标准的Request对象{ yourFieldName: { type: builder.io/core:Request, request: { url: ... }, data: { product: { /* ... */ } } } }这个对象由插件的getRequestObject方法生成见 plugins/swell/src/plugin.tsURL 拼接规则为https://{publicKey}{storeId}.swell.store/api/products/{id}分类同理为/api/categories/{id}getRequestObject(id: string) { return { type: builder.io/core:Request as const, request: { url: https://${publicKey}${storeId}.swell.store/api/products/${id}, }, options: { product: id, }, }; },理解这一设计对内容架构很重要Request对象是 Builder.io 的延迟取数机制——字段里只保存请求描述URL真正拉取响应数据发生在渲染阶段data中的product/category是请求完成后填充的响应内容。因此内容条目天然携带可重放的数据请求既能在编辑器里预览也能在 SSR/CSR 阶段由 Builder SDK 自动请求并注入避免把易过期的商品快照硬编码进内容。本地开发把插件跑起来plugins/swell是仓库中独立的可开发插件包npm 包名为builder.io/plugin-swell版本见 plugins/swell/package.json本地开发流程如下1. 安装依赖git clone 本仓库地址 cd plugins/swell npm install2. 启动开发服务器npm start该命令等价于SERVEtrue rollup -c rollup.config.ts -w见 plugins/swell/package.json。Rollup 的 serve 插件会在1268 端口托管dist目录下的构建产物见 plugins/swell/rollup.config.ts并附带Access-Control-Allow-Origin: *与Access-Control-Allow-Private-Network响应头以兼容浏览器私有网络访问PNA预检。3. 把本地插件接入 Builder.io回到 Account Organization 的插件设置页把本地地址填入插件配置http://localhost:1268/plugin.system.js?pluginIdbuilder.io/ecom-swell-is注意Builder.io 后台是 https 站点而本地开发地址是 http。浏览器会阻止混入的不安全脚本需要在页面右上角点击盾牌图标并选择 Load unsafe scripts加载不安全脚本才能正常加载本地插件。每次修改源码后重启 Builder 页面即可看到最新版本要卸载插件直接在插件管理 UI 中移除即可。4. 验证插件效果创建一个自定义模型、自定义组件或符号在其中添加 Swell 类型字段即可编辑验证。例如给模型加一个Swell Product字段编辑器里应出现商品搜索弹窗选中后字段值显示为商品卡片含图片、标题、handle。5. 构建与发布生产构建命令为npm run build先rimraf dist清理再tscrollup打包见 plugins/swell/package.json。产物入口为dist/plugin.system.jsSystemJS 格式见 plugins/swell/rollup.config.ts。插件发布走语义化版本npm run release:dev打 dev 预发布版本用于联调合并 PR 后npm run release:patch发布补丁版本发布与测试流程详见 plugins/README.md。仓库还配置了 jest 测试与 90% 以上的覆盖率门槛见 plugins/swell/package.json为插件行为提供回归保障。插件 UI 技术栈与最佳实践Builder.io 插件体系的 UI 统一基于React与Material UI样式使用Emotion见 README 的 Frameworks 小节以及 plugins/swell/package.json 中的react、material-ui/core、emotion/core依赖。插件与宿主共享这些运行时因此 Rollup 配置将这些包显式列入external见 plugins/swell/rollup.config.ts避免重复打包导致 React 多实例问题external: [ react, builder.io/react, builder.io/app-context, material-ui/core, emotion/core, emotion/styled, mobx, react-dom, mobx-react, ],注释明确提示不要改动这份 external 列表新增依赖也应保持不被打包这是插件在 Builder 编辑器内稳定运行的前提。开发插件时遵循这一约定配合builder.io/commerce-plugin-tools的product/category资源契约即可用极少的代码让任意电商后端接入 Builder.io——这正是plugins/swell这份实现完整源码仅一个 plugin.ts 文件所展示的典型范式。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考