企业官网建设流程全解析

Builder.io 商城插件实战：接入 Virto Commerce 商品目录实现内容定向与模板预览

【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder

本篇文章围绕 plugins/virtocommerce/README.md 展开，完整讲解如何将 Virto Commerce 的商品目录接入 Builder.io 可视化内容体系：从插件安装、五项连接参数配置，到自定义定向（Custom Targeting）、组件模型预览字段与 Symbol 输入字段三类核心应用场景，再到 CORS 配置与本地插件开发调试流程。读完本文，你将掌握@builder.io/plugin-virtocommerce的完整接入方案，并能基于仓库源码理解插件底层如何通过 GraphQL 请求 Virto Commerce 数据、如何在 Builder.io 中注册资源编辑器。

插件能做什么

Virto Commerce 是一款开源的 .NET 电商平台。@builder.io/plugin-virtocommerce是一个 Commerce Source Plugin，它把 Virto Commerce 的**商品（Product）与分类（Category）**资源注册进 Builder.io，从而让你在 Builder.io 的以下场景中直接选取 Virto Commerce 数据：

• 自定义定向（Custom Targeting）：按商品 ID、商品 Handle、分类 ID、分类 Handle 定向投放内容；
• 组件模型字段（Component Model Fields）：在商品/分类页模板中按具体商品或分类动态生成预览 URL；
• Symbol 输入字段（Symbol Inputs）：在输入框里搜索并选择商品或分类，保存后自动解析为 Builder.ioRequest对象，供 API、SDK 或 Builder.io UI 消费。

插件本身是 TypeScript 编写、以 Rollup 打包为 SystemJS 模块的独立 npm 包，入口文件为 plugins/virtocommerce/src/plugin.ts，通过registerCommercePlugin完成注册。

安装插件

在 Builder.io 控制台完成插件安装即可，无需改动任何前端代码：

1. 打开 Builder.io 账户的组织设置页（builder.io/account/organization）；
2. 在插件输入框中输入包名@builder.io/plugin-virtocommerce；
3. 点击保存，页面会刷新并弹出凭据填写表单。

安装成功后，Builder.io 会自动弹出连接配置对话框。这一行为由底层插件运行时保证：在 packages/plugin-tools/src/commerce.tsx 中，registerCommercePlugin注册了app.onLoad钩子，当组织设置中该插件的hasConnected标记不存在时，会自动触发设置对话框；保存配置时（onSave）会写入hasConnected: true并注册资源编辑器（commerce.tsx）。

连接参数详解

插件需要填写以下连接参数，与 plugin.ts 中声明的 settings 一一对应：

源码层面的处理细节：

• URL 尾斜杠归一化：代码会对virtoCommerceUrl做endsWith('/')检查并去掉尾部斜杠（plugin.ts），因此地址末尾带不带/都可以；
• OAuth 令牌：当login与password均存在时，插件会先向${virtoCommerceUrl}/connect/token发送grant_type=password的 POST 请求换取access_token，再以Authorization: Bearer <token>访问后续接口；留空则直接匿名请求（plugin.ts）；
• locale 映射：locale 会被作为 GraphQL 变量cultureName传入查询（见下文）。

三类核心应用场景

插件安装并连接成功后，会在 Builder.io 中新增若干字段类型（field types）和自定义定向属性（custom targeting attributes），可用于三类上下文：模型（Model）字段、Symbol 输入、自定义组件字段，以及自定义定向。这些字段类型由 packages/plugin-tools/src/commerce.tsx 中的registerEditors统一注册：对每个资源（product、category），依次注册${name}${Resource}（选择器）、${name}${Resource}Preview（预览选择器）与${name}${Resource}sList（列表枚举）三类编辑器。

1. 自定义定向（Custom Targeting）

自定义定向让你按丰富的属性维度给内容打标签。使用本插件时，你可以在定向属性中选择以下类型，将特定内容投放给特定 Virto Commerce 商品或分类：

• Virto Commerce Product：按商品 ID 定向。需要先在宿主环境中把当前商品的 ID 传给 Builder.io；
• Virto Commerce Product Handle：按商品 Handle 定向；
• Virto Commerce Category：按分类 ID 定向；
• Virto Commerce Category Handle：按分类 Handle 定向。

传递当前上下文的方式有两种：

方式一：客户端渲染时设置userAttributes，例如在商品详情页：

builder.setUserAttributes({ product: currentProduct.id, });

方式二：通过 API 查询参数传递。把userAttributes作为查询参数拼进 content API 的请求 URL，或在 Gatsby、Next.js 等场景的 GraphQL 查询中携带该定向参数（即 Query API 的 userAttributes / GraphQL API 的 targeting 用法）。

2. 组件模型字段（Component Model Fields）

如果你想为全部商品或某一批商品创建统一的商品页模板（对分类同理），可以用这两个预览字段：

• Virto Commerce Product Preview：作为组件模型的自定义字段。它让组件模型拥有一个与「被预览商品」挂钩的模板化编辑 URL。例如在模型 URL 中写：

  https://www.mystore.com/product/${previewProduct.handle}

  然后给该模型添加一个类型为Virto Commerce Product Preview的自定义字段。之后每次新建条目时，handle会根据所选的预览商品动态填充到预览 URL 中。建议为该字段设置默认值，这样开发者打开模板组件时能直接落在某个具体商品页。

• Virto Commerce Category Preview：用法与上面完全对称，URL 示例：

  https://www.mystore.com/category/${previewCategory.handle}

  同样建议设置默认值，让开发者在构建分类模板时直接落到某个具体分类页。

3. Symbol 输入字段（Symbol Inputs）

把Virto Commerce Product、Virto Commerce Category作为 Symbol 的输入字段类型时，Builder.io 编辑器会弹出资源搜索选择器，允许你搜索并选择商品/分类。选中后，该字段的值会自动解析为一个 Builder.ioRequest对象，供 API、SDK 或 Builder.io UI 消费：

{ "yourFieldName": { "@type": "@builder.io/core:Request", "request": { "url": "..." }, "data": { // Response data from the API request, e.g.: "product": { /* ... */ } } } }

这正是 plugin.ts 中getRequestObject(id)的产物：它返回@type: '@builder.io/core:Request'结构，request.url指向经由 Builder.io 代理的商品/分类接口地址，options中携带资源 ID。商品与分类的getRequestObject分别位于 plugin.ts 与 plugin.ts。

数据请求链路：源码级原理

理解插件内部如何取数，有助于排查连接问题与定制行为。整体链路如下：

Builder.io 编辑器 │ 输入搜索关键字 / 选中资源 ID ▼ registerCommercePlugin 注册的资源选择器 │ findById / search ▼ 请求转发到 https://cdn.builder.io/api/v1/proxy-api?url=<编码后的目标URL> │ POST {graphql 查询} ▼ Virto Commerce GraphQL 端点（/graphql）

关键实现集中在 plugin.ts：

• 代理转发：所有请求先经 Builder.io 的proxy-api转发，规避浏览器跨域限制（plugin.ts）。baseUrl(url)将目标 URL 编码后拼接到代理端点；
• 统一请求入口：requestData向${virtoCommerceUrl}/graphql发送 POST 请求（plugin.ts）；
• 响应归一化：transformResource把 Virto Commerce 返回的资源映射为统一结构 ——id取resource.id、title取resource.name、handle取resource.customUrl?.url、image.src取resource.imgSrc（plugin.ts）；
• 结果缓存：basicCache（Map）以资源ID + 操作名为键缓存findById结果，避免重复请求（plugin.ts 及 product/category 的findById实现）。

插件使用的 GraphQL 查询

四个查询文件分别对应商品详情、商品搜索、分类详情、分类搜索：

值得注意的细节：

• 商品详情查询（GetProduct）返回非常丰富的字段：name/id/code/slug/outline、是否多规格hasVariations、最小/最大购买量minQuantity/maxQuantity、主图imgSrc、图片列表images、资产assets、描述description(s)、属性properties（含name/value/type/hidden/valueType/label）以及变体variations（见 product.query.ts）；
• 商品搜索默认first: 5，即编辑器下拉最多展示 5 条商品；分类搜索默认first: 10，且强制filter: 'status:visible'，只返回可见分类（见 products-search.query.ts 与 categories-search.query.ts）；
• currencyCode固定为'USD'（product.query.ts），即商品价格以美元货币代码请求。

CORS 配置

出于安全考虑，Virto Commerce 默认关闭 CORS。如果你不使用插件内置的 proxy-api 代理、而是让前端直接访问 Virto Commerce 端点，就需要在 Virto Commerce 的环境配置中添加如下响应头：

Access-Control-Allow-Origin: * Access-Control-Allow-Headers: Content-Type Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS Access-Control-Allow-Credentials: true

其中Access-Control-Allow-Methods覆盖了插件用到的 GET/POST（GraphQL 与 token 请求）以及电商场景常见的 PUT/DELETE。

本地开发插件

插件源码位于仓库 plugins/virtocommerce，开发环境依赖 Node.js（package.json声明node >= 6.0.0）。

安装与启动

git clone https://github.com/BuilderIO/builder.git cd plugins/virtocommerce npm install npm start

npm start实际执行rollup -c rollup.config.ts -w（见 package.json），即用 Rollup 以监听模式打包。构建入口是 src/plugin.ts，输出为dist/plugin.system.js（SystemJS 格式，带 sourcemap），同时 Rollup 内置的serve插件会在1268 端口起一个本地静态服务，并主动返回Access-Control-Allow-Origin: *等 CORS 头（见 rollup.config.ts）。

在 Builder.io 中加载本地插件

1. 打开 builder.io/account/organization 的插件设置；

2. 在插件设置中添加本地 URL：

   http://localhost:1268/plugin.system.js?pluginId=@builder.io/plugin-virtocommerce

注意：在https://站点上加载http://内容会触发浏览器警告。本地开发时需要点击浏览器右上角的盾牌图标，选择「加载不安全脚本」（Load unsafe scripts），允许 Builder 的 HTTPS 页面加载本地 HTTP 内容。

之后每次修改源码，Rollup 监听模式会自动重新打包；重启 Builder 即可看到插件最新版本。卸载插件只需在插件的 UI 中移除它即可。

验证插件效果

连接成功后，可以按 README 的指引做一次冒烟验证：创建一个自定义模型（Model）、自定义组件（Custom Component）或 Symbol，在字段类型中选择 Virto Commerce 相关字段（例如商品选择器），即可在编辑器中搜索并选用真实商品数据。

插件工程结构一览

底层框架方面，Builder.io 插件 UI 基于 React 与 Material UI 构建，并使用 Emotion 做样式；插件在打包时会将react、@builder.io/react、@builder.io/app-context、@material-ui/core、@emotion/core、@emotion/styled、mobx、react-dom、mobx-react声明为 external，与宿主共享同一份运行时（见 rollup.config.ts），这是保证插件与 Builder.io 编辑器稳定协作的关键。

小结

接入@builder.io/plugin-virtocommerce后，你的 Virto Commerce 商品目录就与 Builder.io 的内容体系打通了：既能按商品/分类做精准内容定向，也能为商品/分类页模板提供所见即所得的预览，还能在 Symbol 中输入商品/分类并拿到可直接消费的Request对象。若需二次开发，仓库中的 plugin.ts 与四个 GraphQL 查询文件提供了完整的参考实现，本地通过npm start即可在 1268 端口迭代调试。

【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder