Builder.io Magento 2 电商插件实战连接商品数据、构建定向内容与本地开发指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io 官方仓库中的plugins/magento2是一个面向电商场景的集成插件它让 Magento 2 商店的数据商品、分类可以被 Builder.io 的内容模型、符号Symbol与自定义组件直接引用。本文以该插件的 README 为骨架结合仓库内的源码与构建配置完整讲解插件的安装启用、六种 Magento 字段类型的使用场景、自定义定向配置方法以及如何在本地拉取源码开发并调试插件。读完本文你将掌握把 Magento 2 数据接入 Builder.io 的完整链路并理解其底层 GraphQL 数据获取与字段注册机制。插件能做什么一次连接三种使用上下文启用 Magento 集成后Builder.io 中会新增六种字段类型它们可以分别用在三种不同的上下文中覆盖从「内容定向」到「模板预览」再到「数据选择器」的完整电商场景字段类型适用上下文作用Magento Product自定义定向、Symbol 输入、自定义组件字段按商品ID / uid定位内容或弹出商品搜索选择器Magento Product Handle自定义定向按商品 handleurl_key定向内容Magento Product Preview组件模型字段在组件模型上绑定商品预览动态拼接模板编辑 URLMagento Category自定义定向、Symbol 输入、自定义组件字段按分类ID / uid定位内容或弹出分类搜索选择器Magento Category Handle自定义定向按分类 handleurl_key定向内容Magento Category Preview组件模型字段在组件模型上绑定分类预览动态拼接模板编辑 URL这六种字段类型并非手工注册而是由 plugin-tools 中的registerCommercePlugin根据插件返回的数据操作能力自动生成的。在 commerce.tsx 中可以看到它会为每个资源product / category依次注册${name}${Resource}数据资源选择器对应Magento Product、Magento Category${name}${Resource}Preview预览字段对应Magento Product Preview、Magento Category Preview${name}${Resource}Handlehandle 定向字段对应Magento Product Handle、Magento Category Handle${name}${Plural(Resource)}List可枚举的列表选择器对应Magento ProductsList、Magento CategoriesList。只要apiOperations[resourceName].findByHandle存在handle 类型的编辑器就会被注册——这正是 Magento 插件把url_key同时用作 id 与 handle 的原因之一。安装与连接启用集成并配置商店地址安装只需在 Builder.io 后台完成打开 Builder.io 账户组织页面中的 Integrations集成列表在集成列表中启用 Magento 集成点击保存保存时系统会提示你输入 store URL商店地址。从源码看连接参数正是 plugin.ts 中定义的settings数组插件声明了一个名为storeUrl、类型为string、required: true的必填配置项。保存连接时插件会对storeUrl做一次 URL 规范化const storeUrl new URL(settings.get(storeUrl)).origin;即只保留协议的源origin例如输入https://www.mystore.com/xxx会归一化为https://www.mystore.com后续所有 GraphQL 请求都基于这个源发起。连接成功回调中registerCommercePlugin会把hasConnected: true写入插件设置并注册上述全部编辑器见 commerce.tsx同时插件被注册为isSourcePlugin: true的数据源插件。若插件从未连接过Builder.io 会在应用加载时自动弹出设置对话框引导你完成连接见 commerce.tsx。自定义定向按商品与分类精准投放内容Builder.io 的自定义定向Custom targeting允许按多种属性为访客展示不同内容。启用 Magento 插件后你可以按具体的商品或分类定向投放内容。第一步是在宿主站点上设置对应的定向属性target attributes有两种方式方式一客户端渲染时通过userAttributes设置builder.setUserAttributes({ product: currentProduct.url_key, });方式二通过请求参数传入将属性作为 query param 传给内容 APIcontent API或在 Gatsby、Next.js 等场景下作为 targeting 参数放进 GraphQL 查询。设置好宿主端属性后即可使用如下定向字段Magento Product作为自定义定向类型使用时它定向「字段值等于某个商品 ID」的上下文。你需要用上述方法之一把商品 ID 设置到宿主环境中。若想按商品 handle 定向改用Magento Product Handle类型。Magento Category作为自定义定向属性可按分类 ID 定向到特定分类。同样需要在宿主环境设置分类 ID若想按分类 handle 定向改用Magento Category Handle。从实现上看这些定向类型之所以能工作是因为 service.ts 提供了findByHandle能力它会把 handle 翻译成 Magento 的 GraphQL 过滤条件filter: { url_key: { eq: ... } }去查询商品分类侧service.ts则使用categories(filters: { url_key: { eq: ... } })查询分类。handle 与 id 在这里被统一为url_key正如源码注释所说“No clear way to get a product by ID, opted to make urlKey both the id and the handle”Magento GraphQL 没有清晰的按 ID 查商品的途径因此将 url_key 同时用作 id 与 handle。组件模型字段为商品/分类页面模板提供实时预览组件模型Component Model可以用来为全部或某一特定集合的商品/分类构建页面模板。使用下面两个字段可以让模板在编辑器中随时预览任意商品或分类的实际效果Magento Product Preview在组件模型上添加Magento Product Preview类型自定义字段后你可以为模型设置带模板变量的编辑 URL例如https://www.mystore.com/product/${previewProduct.handle}当创建新条目时previewProduct.handle会根据所选的预览商品被动态替换进预览 URL。建议为Magento Product Preview字段设置默认值这样开发者打开模板组件时会默认落到一个具体商品页面上而不是空页面。Magento Category Preview同理在组件模型上添加Magento Category Preview类型字段可设置如下的分类模板编辑 URLhttps://www.mystore.com/category/${previewCategory.handle}创建新条目时previewCategory.handle会被替换为所选预览分类的 handle。同样建议设置默认值让模板开发时默认落在某个分类页。预览字段的底层实现是 plugin-tools 中独立的编辑器注册registerCommercePlugin会在noPreviewTypes为假时为每个资源额外注册${name}${Resource}Preview编辑器见 commerce.tsx并把isPreview: true传给选择器组件从而在字段 UI 上呈现“预览资源”的交互形态。Symbol 输入与自定义组件字段值为 Builder Request 对象把Magento Product和Magento Category用作 Symbol 的输入字段或自定义组件的字段时编辑器 UI 会弹出搜索框让你按关键字搜索并选择商品/分类搜索能力由 service.ts 的search方法驱动它向 Magento GraphQL 发出products(search: ...)查询。当被 API、SDK 或 Builder.io UI 消费时字段值会自动解析为一个 Builder.io 标准的Request对象{ yourFieldName: { type: builder.io/core:Request, request: { url: ... }, data: { // API 请求返回的数据例如 product: { /* ... */ } } } }这个对象结构对应 builder-request.ts 中定义的BuilderRequest接口type恒为builder.io/core:Requestrequest描述实际请求url、query、headers、method、bodyoptions可携带插件自定义信息。Magento 插件在 service.ts 的getRequestObject(id)中正是这样构造的getRequestObject(id: string) { return { type: builder.io/core:Request as const, request: { // 商品公开 URL 暂未实现留空 url: , }, options: { product: id, pluginId: pkg.name, // builder.io/plugin-magento2 }, }; }options中保留了product/category的 id 以及插件 idbuilder.io/plugin-magento2即 package.json 中的name字段渲染时 SDK 可据此再次请求对应资源的数据。数据获取原理GraphQL 查询 Builder 代理插件与 Magento 商店的通信全部通过 Magento 2 的 GraphQL 接口完成核心代码在 service.ts。整体数据流如下构建查询商品查询模板productSearchGql支持可选的搜索关键字与url_key过滤{ products(search: filter: { url_key: { eq: some-key }}) { items { name url_key uid image { url } } } }分类查询模板categoriesSearchGql与之类似返回image、name、uid、url_key字段。源码中的 TODO 注释// TODO: search is not possible, figure out workarounds表明当前分类搜索能力受限分类搜索字段目前实际上并未参与过滤。代理转发请求地址统一走 Builder.io 的代理接口避免跨域与密钥暴露const proxyUrl (endUrl: string) { return https://builder.io/api/v1/proxy-api?url${encodeURIComponent(endUrl)}; }; const endpoint proxyUrl(${storeUrl}/graphql);字段映射transformProduct/transformCategory把 Magento 返回的数据标准化为 Builder.io 插件通用的资源形状——title取name、handle与id取url_key、image.src取商品图片 URL 或分类图片字段。这种统一形状与 plugin-tools 示例中 Swell 插件的transformProduct完全一致说明该结构是 plugin-tools 数据源插件的通用约定。本地开发克隆、安装、运行与加载如果你想为插件贡献代码或调试仓库根目录下就能直接开发安装依赖git clone https://gitcode.com/GitHub_Trending/bu/builder cd plugins/magento2 npm install启动开发服务npm start该命令对应 package.json 中的脚本SERVEtrue rollup -c rollup.config.ts -w。在 rollup.config.ts 中可以看到当SERVE为真时Rollup 会启用rollup-plugin-serve在1268 端口提供构建产物并设置Access-Control-Allow-Origin: *与Access-Control-Allow-Private-Network: true响应头以支持浏览器跨域加载本地插件。将本地插件加入 Builder.io打开 Builder.io 账户组织页面的插件设置在插件列表中添加本地开发地址http://localhost:1268/plugin.system.js?pluginIdbuilder.io/ecom-magento2-is注意pluginId中的builder.io/ecom-magento2-is是插件加载标识构建产物文件名plugin.system.js与 package.json 中的main/unpkg字段dist/plugin.system.js对应Rollup 以system格式输出见 rollup.config.ts。本地开发注意事项在 https 站点上加载 http 内容会触发浏览器警告。开发时请点击浏览器右上角的盾牌图标选择“加载不安全的脚本”load unsafe scripts允许 Builder 的 https 站点加载本地 http 内容。开发过程中重启 Builder 即可看到插件的最新版本如需卸载插件直接在插件的 UI 中移除即可。另外需要留意 rollup.config.ts 中声明的external列表react、builder.io/react、builder.io/app-context、material-ui/core、emotion/core、emotion/styled、mobx、react-dom、mobx-react都被标记为外部依赖不打包进产物。注释强调这些共享引用“绝不能更改”因为 Builder 插件运行时需要与宿主共享同一份 React 与 SDK 实例否则会导致插件无法正常运行。在编辑器中验证插件效果完成连接与字段注册后你可以新建一个自定义模型Model添加Magento Product/Magento Category等字段并保存观察字段 UI 是否弹出商品/分类搜索创建一个自定义组件Custom Component在其 props 中使用 Magento 字段在编辑器中体验选择器交互创建一个符号Symbol把Magento Product/Magento Category作为输入验证值被解析为builder.io/core:Request对象的过程在组件模型上添加Magento Product Preview/Magento Category Preview确认预览 URL 中的 handle 是否随所选资源动态变化。技术栈与开发约定Builder.io 插件 UI 统一基于React与Material UI构建样式使用Emotion。插件内部通过builder.io/plugin-tools见 package.json 的 dependencies获得registerCommercePlugin、BuilderRequest等基础设施typings.d.ts中声明了builder.io/app-context模块它提供了访问用户组织设置、触发设置对话框等宿主能力见 commerce.tsx。沿用这套框架开发 Builder 插件可以保证插件与 Builder 编辑器之间的最佳体验与性能表现。小结本文以仓库内 plugins/magento2/README.md 为主线完整还原了 Magento 2 插件的启用流程、六种字段类型在三类上下文自定义定向、组件模型字段、Symbol 输入中的用法并深入到 plugin.ts 与 service.ts 的源码解释了storeUrl连接参数、GraphQL 查询构造、Builder 代理转发、资源字段标准化以及Request对象生成等底层机制最后给出了从零开始本地开发插件的完整命令与配置说明。无论你是想直接在 Builder.io 中接入 Magento 数据做电商内容还是打算基于 plugin-tools 生态开发自己的数据源插件这条链路都值得作为起点参考。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Builder.io Magento 2 电商插件实战：连接商品数据、构建定向内容与本地开发指南
Builder.io Magento 2 电商插件实战连接商品数据、构建定向内容与本地开发指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io 官方仓库中的plugins/magento2是一个面向电商场景的集成插件它让 Magento 2 商店的数据商品、分类可以被 Builder.io 的内容模型、符号Symbol与自定义组件直接引用。本文以该插件的 README 为骨架结合仓库内的源码与构建配置完整讲解插件的安装启用、六种 Magento 字段类型的使用场景、自定义定向配置方法以及如何在本地拉取源码开发并调试插件。读完本文你将掌握把 Magento 2 数据接入 Builder.io 的完整链路并理解其底层 GraphQL 数据获取与字段注册机制。插件能做什么一次连接三种使用上下文启用 Magento 集成后Builder.io 中会新增六种字段类型它们可以分别用在三种不同的上下文中覆盖从「内容定向」到「模板预览」再到「数据选择器」的完整电商场景字段类型适用上下文作用Magento Product自定义定向、Symbol 输入、自定义组件字段按商品ID / uid定位内容或弹出商品搜索选择器Magento Product Handle自定义定向按商品 handleurl_key定向内容Magento Product Preview组件模型字段在组件模型上绑定商品预览动态拼接模板编辑 URLMagento Category自定义定向、Symbol 输入、自定义组件字段按分类ID / uid定位内容或弹出分类搜索选择器Magento Category Handle自定义定向按分类 handleurl_key定向内容Magento Category Preview组件模型字段在组件模型上绑定分类预览动态拼接模板编辑 URL这六种字段类型并非手工注册而是由 plugin-tools 中的registerCommercePlugin根据插件返回的数据操作能力自动生成的。在 commerce.tsx 中可以看到它会为每个资源product / category依次注册${name}${Resource}数据资源选择器对应Magento Product、Magento Category${name}${Resource}Preview预览字段对应Magento Product Preview、Magento Category Preview${name}${Resource}Handlehandle 定向字段对应Magento Product Handle、Magento Category Handle${name}${Plural(Resource)}List可枚举的列表选择器对应Magento ProductsList、Magento CategoriesList。只要apiOperations[resourceName].findByHandle存在handle 类型的编辑器就会被注册——这正是 Magento 插件把url_key同时用作 id 与 handle 的原因之一。安装与连接启用集成并配置商店地址安装只需在 Builder.io 后台完成打开 Builder.io 账户组织页面中的 Integrations集成列表在集成列表中启用 Magento 集成点击保存保存时系统会提示你输入 store URL商店地址。从源码看连接参数正是 plugin.ts 中定义的settings数组插件声明了一个名为storeUrl、类型为string、required: true的必填配置项。保存连接时插件会对storeUrl做一次 URL 规范化const storeUrl new URL(settings.get(storeUrl)).origin;即只保留协议的源origin例如输入https://www.mystore.com/xxx会归一化为https://www.mystore.com后续所有 GraphQL 请求都基于这个源发起。连接成功回调中registerCommercePlugin会把hasConnected: true写入插件设置并注册上述全部编辑器见 commerce.tsx同时插件被注册为isSourcePlugin: true的数据源插件。若插件从未连接过Builder.io 会在应用加载时自动弹出设置对话框引导你完成连接见 commerce.tsx。自定义定向按商品与分类精准投放内容Builder.io 的自定义定向Custom targeting允许按多种属性为访客展示不同内容。启用 Magento 插件后你可以按具体的商品或分类定向投放内容。第一步是在宿主站点上设置对应的定向属性target attributes有两种方式方式一客户端渲染时通过userAttributes设置builder.setUserAttributes({ product: currentProduct.url_key, });方式二通过请求参数传入将属性作为 query param 传给内容 APIcontent API或在 Gatsby、Next.js 等场景下作为 targeting 参数放进 GraphQL 查询。设置好宿主端属性后即可使用如下定向字段Magento Product作为自定义定向类型使用时它定向「字段值等于某个商品 ID」的上下文。你需要用上述方法之一把商品 ID 设置到宿主环境中。若想按商品 handle 定向改用Magento Product Handle类型。Magento Category作为自定义定向属性可按分类 ID 定向到特定分类。同样需要在宿主环境设置分类 ID若想按分类 handle 定向改用Magento Category Handle。从实现上看这些定向类型之所以能工作是因为 service.ts 提供了findByHandle能力它会把 handle 翻译成 Magento 的 GraphQL 过滤条件filter: { url_key: { eq: ... } }去查询商品分类侧service.ts则使用categories(filters: { url_key: { eq: ... } })查询分类。handle 与 id 在这里被统一为url_key正如源码注释所说“No clear way to get a product by ID, opted to make urlKey both the id and the handle”Magento GraphQL 没有清晰的按 ID 查商品的途径因此将 url_key 同时用作 id 与 handle。组件模型字段为商品/分类页面模板提供实时预览组件模型Component Model可以用来为全部或某一特定集合的商品/分类构建页面模板。使用下面两个字段可以让模板在编辑器中随时预览任意商品或分类的实际效果Magento Product Preview在组件模型上添加Magento Product Preview类型自定义字段后你可以为模型设置带模板变量的编辑 URL例如https://www.mystore.com/product/${previewProduct.handle}当创建新条目时previewProduct.handle会根据所选的预览商品被动态替换进预览 URL。建议为Magento Product Preview字段设置默认值这样开发者打开模板组件时会默认落到一个具体商品页面上而不是空页面。Magento Category Preview同理在组件模型上添加Magento Category Preview类型字段可设置如下的分类模板编辑 URLhttps://www.mystore.com/category/${previewCategory.handle}创建新条目时previewCategory.handle会被替换为所选预览分类的 handle。同样建议设置默认值让模板开发时默认落在某个分类页。预览字段的底层实现是 plugin-tools 中独立的编辑器注册registerCommercePlugin会在noPreviewTypes为假时为每个资源额外注册${name}${Resource}Preview编辑器见 commerce.tsx并把isPreview: true传给选择器组件从而在字段 UI 上呈现“预览资源”的交互形态。Symbol 输入与自定义组件字段值为 Builder Request 对象把Magento Product和Magento Category用作 Symbol 的输入字段或自定义组件的字段时编辑器 UI 会弹出搜索框让你按关键字搜索并选择商品/分类搜索能力由 service.ts 的search方法驱动它向 Magento GraphQL 发出products(search: ...)查询。当被 API、SDK 或 Builder.io UI 消费时字段值会自动解析为一个 Builder.io 标准的Request对象{ yourFieldName: { type: builder.io/core:Request, request: { url: ... }, data: { // API 请求返回的数据例如 product: { /* ... */ } } } }这个对象结构对应 builder-request.ts 中定义的BuilderRequest接口type恒为builder.io/core:Requestrequest描述实际请求url、query、headers、method、bodyoptions可携带插件自定义信息。Magento 插件在 service.ts 的getRequestObject(id)中正是这样构造的getRequestObject(id: string) { return { type: builder.io/core:Request as const, request: { // 商品公开 URL 暂未实现留空 url: , }, options: { product: id, pluginId: pkg.name, // builder.io/plugin-magento2 }, }; }options中保留了product/category的 id 以及插件 idbuilder.io/plugin-magento2即 package.json 中的name字段渲染时 SDK 可据此再次请求对应资源的数据。数据获取原理GraphQL 查询 Builder 代理插件与 Magento 商店的通信全部通过 Magento 2 的 GraphQL 接口完成核心代码在 service.ts。整体数据流如下构建查询商品查询模板productSearchGql支持可选的搜索关键字与url_key过滤{ products(search: filter: { url_key: { eq: some-key }}) { items { name url_key uid image { url } } } }分类查询模板categoriesSearchGql与之类似返回image、name、uid、url_key字段。源码中的 TODO 注释// TODO: search is not possible, figure out workarounds表明当前分类搜索能力受限分类搜索字段目前实际上并未参与过滤。代理转发请求地址统一走 Builder.io 的代理接口避免跨域与密钥暴露const proxyUrl (endUrl: string) { return https://builder.io/api/v1/proxy-api?url${encodeURIComponent(endUrl)}; }; const endpoint proxyUrl(${storeUrl}/graphql);字段映射transformProduct/transformCategory把 Magento 返回的数据标准化为 Builder.io 插件通用的资源形状——title取name、handle与id取url_key、image.src取商品图片 URL 或分类图片字段。这种统一形状与 plugin-tools 示例中 Swell 插件的transformProduct完全一致说明该结构是 plugin-tools 数据源插件的通用约定。本地开发克隆、安装、运行与加载如果你想为插件贡献代码或调试仓库根目录下就能直接开发安装依赖git clone https://gitcode.com/GitHub_Trending/bu/builder cd plugins/magento2 npm install启动开发服务npm start该命令对应 package.json 中的脚本SERVEtrue rollup -c rollup.config.ts -w。在 rollup.config.ts 中可以看到当SERVE为真时Rollup 会启用rollup-plugin-serve在1268 端口提供构建产物并设置Access-Control-Allow-Origin: *与Access-Control-Allow-Private-Network: true响应头以支持浏览器跨域加载本地插件。将本地插件加入 Builder.io打开 Builder.io 账户组织页面的插件设置在插件列表中添加本地开发地址http://localhost:1268/plugin.system.js?pluginIdbuilder.io/ecom-magento2-is注意pluginId中的builder.io/ecom-magento2-is是插件加载标识构建产物文件名plugin.system.js与 package.json 中的main/unpkg字段dist/plugin.system.js对应Rollup 以system格式输出见 rollup.config.ts。本地开发注意事项在 https 站点上加载 http 内容会触发浏览器警告。开发时请点击浏览器右上角的盾牌图标选择“加载不安全的脚本”load unsafe scripts允许 Builder 的 https 站点加载本地 http 内容。开发过程中重启 Builder 即可看到插件的最新版本如需卸载插件直接在插件的 UI 中移除即可。另外需要留意 rollup.config.ts 中声明的external列表react、builder.io/react、builder.io/app-context、material-ui/core、emotion/core、emotion/styled、mobx、react-dom、mobx-react都被标记为外部依赖不打包进产物。注释强调这些共享引用“绝不能更改”因为 Builder 插件运行时需要与宿主共享同一份 React 与 SDK 实例否则会导致插件无法正常运行。在编辑器中验证插件效果完成连接与字段注册后你可以新建一个自定义模型Model添加Magento Product/Magento Category等字段并保存观察字段 UI 是否弹出商品/分类搜索创建一个自定义组件Custom Component在其 props 中使用 Magento 字段在编辑器中体验选择器交互创建一个符号Symbol把Magento Product/Magento Category作为输入验证值被解析为builder.io/core:Request对象的过程在组件模型上添加Magento Product Preview/Magento Category Preview确认预览 URL 中的 handle 是否随所选资源动态变化。技术栈与开发约定Builder.io 插件 UI 统一基于React与Material UI构建样式使用Emotion。插件内部通过builder.io/plugin-tools见 package.json 的 dependencies获得registerCommercePlugin、BuilderRequest等基础设施typings.d.ts中声明了builder.io/app-context模块它提供了访问用户组织设置、触发设置对话框等宿主能力见 commerce.tsx。沿用这套框架开发 Builder 插件可以保证插件与 Builder 编辑器之间的最佳体验与性能表现。小结本文以仓库内 plugins/magento2/README.md 为主线完整还原了 Magento 2 插件的启用流程、六种字段类型在三类上下文自定义定向、组件模型字段、Symbol 输入中的用法并深入到 plugin.ts 与 service.ts 的源码解释了storeUrl连接参数、GraphQL 查询构造、Builder 代理转发、资源字段标准化以及Request对象生成等底层机制最后给出了从零开始本地开发插件的完整命令与配置说明。无论你是想直接在 Builder.io 中接入 Magento 数据做电商内容还是打算基于 plugin-tools 生态开发自己的数据源插件这条链路都值得作为起点参考。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考