Builder Localized Preview 插件实战:在 Builder.io 编辑器中实现多语言可视化预览

原创2026-09-15 16:54:341,873 阅读
文章标签:前端低代码CMS

Builder Localized Preview 插件实战:在 Builder.io 编辑器中实现多语言可视化预览

导读

本文围绕 Builder 官方仓库中的 localized-preview 插件,讲解如何为 Builder.io 可视化编辑器搭建一套"路径前缀式"(如 /fr)的多语言预览方案:从本地安装、开发调试,到在 Builder.io 控制台注入插件、配置默认与备用 locale,再到编辑器顶部工具栏的语言切换器原理拆解。读完本文,你将能够独立运行、配置并理解该插件的完整工作机制,并据此扩展出适合自己站点的多语言预览能力。

该插件适用于 Builder.io 的可视化内容编辑场景:编辑者在编辑页面内容时,可以直接在编辑器中切换不同语言的前缀,实时预览 /fr、/de 等路径下的渲染效果,而无需离开 Builder 编辑器。

插件定位与工作原理

localized-preview(包名 @builder.io/plugin-localized-preview,详见 package.json)是一个运行在 Builder.io Web 应用内部的插件,其核心职责是:在 Builder 编辑器顶部工具栏中注入一个语言切换器(Language Switcher),并在切换语言时修改编辑预览 iframe 的 URL,从而实现按路径前缀切换多语言预览。

从仓库代码看,它依赖两个 Builder 官方包:

  • @builder.io/app-context:提供编辑器的应用上下文(当前用户、当前编辑的内容模型、设计器 iframe 引用、snackBar 提示等);
  • @builder.io/sdk:提供 Builder.register API,用于向 Builder Web 应用注册插件能力。

插件入口文件是 src/plugin.ts,其中通过三条 Builder.register 调用完成了插件的"注册三连":

  1. Builder.register('editor.toolbarButton', ...) —— 把语言切换器组件挂到编辑器顶部工具栏;
  2. Builder.register('plugin', ...) —— 声明插件元信息与可配置的 settings(locale 列表);
  3. Builder.register('app.onLoad', ...) —— 应用加载时读取组织级插件设置,若未配置 locales 则自动弹出设置对话框,并把"打开设置"的触发器暴露到 window.languageSettingsTrigger 上。

值得注意的限制(README 原文明确说明):当前只支持基于路径的本地化(path based localization,如 /fr),且所配置的默认与备用 locale 必须同时在你自己的 Next.js i18n 配置中定义好,插件本身不会创建路由,只是切换预览 URL 前缀。

一、安装与本地开发

1. 克隆仓库并安装依赖

README 给出了从 Builder 主仓库克隆并进入插件目录安装的流程(注意:README 中的目录名 plugins/localization 为历史笔误,仓库中实际路径为 plugins/localized-preview):

git clone https://github.com/BuilderIO/builder.git
cd plugins/localized-preview
npm install

安装完成后,插件目录下会包含如下核心源码文件:

2. 启动开发服务器

npm start

该命令对应 package.json 中的 webpack serve --mode development,由 webpack.config.js 驱动:

  • 入口为 ./src/plugin.ts,产物文件名取自定义包 output 字段,即 plugin.system.js,输出到 dist/ 目录;
  • 输出使用 libraryTarget: 'system'(SystemJS 模块格式),以便被 Builder.io Web 应用作为插件加载;
  • 开发服务器默认运行在 端口 1268,并设置了 Access-Control-Allow-Origin: * 跨域响应头,允许 Builder 站点从 https 环境跨域加载本地脚本。

webpack 配置中通过 externals 将 react、react-dom、@builder.io/sdk、@builder.io/app-context、@material-ui/core 等声明为共享依赖,这些模块由 Builder.io Web 应用运行时提供,不会重复打进插件包——这也是插件体积小、能与宿主应用无缝协作的关键设计。

二、在 Builder.io 中加载插件

1. 通过浏览器控制台注入

从 builder.io 打开任意页面,进入浏览器开发者工具的 JavaScript 控制台,执行以下代码即可把本地开发中的插件加载进编辑器:

// Adds the plugin
builder.plugins.replace(['http://localhost:1268/plugin.system.js'])
// Saves for all in your organization and reloads the browser
builder.savePlugins().then(() => location.reload())

执行后 Builder 会保存插件配置并刷新浏览器,随后编辑器顶部工具栏即可看到语言切换器。

注意(HTTP 混合内容警告):在 https 的 Builder 站点上加载 http://localhost:1268/plugin.system.js 会触发浏览器的混合内容警告。本地开发时需要在浏览器地址栏右侧点击"盾牌"图标,选择"加载不安全的脚本(Load unsafe scripts)",允许 https 页面加载本地 http 内容,否则插件脚本不会生效。

之后每次修改源码,webpack-dev-server 都会热更新,你只需重启/刷新 Builder 编辑器即可看到最新版本的插件效果。

2. 配置默认与备用 Locale

插件首次加载时,会在 app.onLoad 钩子中读取当前组织的插件设置(源码见 src/plugin.ts):

const currentOrg = appState.user.organization
const pluginSettings = currentOrg.value.settings.plugins.get(pluginId)
const locales = pluginSettings?.get('locales')
if (typeof locales === 'string' || !locales) {
  pluginSettings?.set('locales', [])
  await triggerSettingsDialog(pluginId)
}
window.languageSettingsTrigger = async () =>
  await triggerSettingsDialog(pluginId)

也就是说:如果检测到 locales 尚未配置,会自动弹出插件设置对话框;同时把 window.languageSettingsTrigger 暴露为全局函数,供 UI 上的设置按钮随时再次唤起该对话框。

插件的 settings 声明定义了 locale 列表的结构(每个 locale 由两个字符串子字段组成):

settings: [
  {
    name: 'locales',
    type: 'list',
    defaultValue: [],
    subFields: [
      { name: 'localeCode', type: 'string' }, // 如 fr
      { name: 'localeName', type: 'string' }, // 如 Français
    ],
  },
],

填写示例:

localeCode localeName
en English
fr Français
de Deutsch

其中列表中的第一个 locale 被插件视为默认语言,切换回第一个时不会在 URL 中附加前缀;其余 locale 则以 /{localeCode} 路径前缀形式拼接到预览 URL 中。如前所述,这些 locale 必须与你的 Next.js i18n 配置中启用的语言保持一致。

三、插件工作流程与源码解析

1. 语言切换器组件如何读取配置

工具栏组件 src/components/language-switcher.tsx 在挂载时(useEffect + onLoad)同样从组织设置中读取 locales,并将其映射为 { name, code } 数组供下拉菜单渲染,同时把第一个 locale 设为默认选中项:

const localesMap = pluginSettings?.get('locales')
const locales = localesMap.map((l: any) => ({
  name: l.get('localeName'),
  code: l.get('localeCode'),
}))
setLocales(locales)
setSelectedLocale(locales[0].code)

组件 UI 由两部分组成:一个 Settings 图标按钮(点击后调用 window.languageSettingsTrigger() 重新打开配置对话框)和一个 Material UI 的 Select 下拉框(列出所有已配置的 locale)。

2. 切换语言时如何改变预览 URL

核心逻辑在 handleLocaleChange 函数中。它通过 context.designerState.editingIframeRef 拿到当前编辑预览 iframe,读取其当前 src 的 origin 与 search(查询字符串),再结合 context.designerState.editingContentModel?.url(当前正在编辑内容的 URL 路径),重新拼接出目标 URL 并写回 iframe:

const { origin, search } = new URL(context.designerState.editingIframeRef.src)
let finalUrl = ''
if (locales?.length && code === locales[0].code) {
  // 默认语言:不添加前缀
  finalUrl = origin + context.designerState.editingContentModel?.url + search
} else {
  // 非默认语言:在路径前插入 /{localeCode}
  finalUrl =
    origin + '/' + code + context.designerState.editingContentModel?.url + search
}
context.designerState.editingIframeRef.src = finalUrl
const preview = locales?.find((locale) => locale.code === code)
context.snackBar.show(`Previewing ${preview?.name || code}`)

切换完成后,还会通过 context.snackBar.show(...) 在编辑器底部弹出提示,例如 Previewing Français,让编辑者明确当前预览的语言环境。

从源码注释可以了解到一个已知的局限性:直接修改 editingContentModel.previewUrl 的方式"不可靠",且会覆盖默认预览路径,因此插件最终选择了直接改写 iframe 的 src 这一更稳妥的做法。这意味着切换是"临时预览",不会污染内容模型本身的预览 URL 配置。

3. 配套的数据模型

src/models/localization.ts 中定义了一个名为 localization 的模型(kind: 'data',hideFromUI: true)。这是一个在后台自动创建、不在内容列表中展示的数据模型,用于承载与本地化相关的数据;在 src/plugin.ts 中,它还通过 addModel 动作(OnSaveActions 接口)在保存插件设置时被注册,保证该模型在组织内可用。

四、卸载插件

如需移除插件,在 builder.io 的浏览器控制台中执行:

// Removes all plugins
builder.plugins.replace([])
// Saves for all in your organization and reloads the browser
builder.savePlugins().then(() => location.reload())

执行后所有插件(包括本地化的语言切换器)都会被移除并刷新页面。

五、类型约定与二次开发指引

如果你希望基于该插件扩展自己的本地化工具,理解其类型设计会很有帮助。插件通过 src/interfaces/application-context.ts 对 @builder.io/app-context 的类型做了扩展(对应宿主类型定义见 packages/app-context/index.d.ts),关键扩展点包括:

  • ExtendedContentModel:在 ContentModel 基础上增加了 data: Map<string, any>、url?、previewUrl?、allBlocks? 等字段,其中 url 正是本插件拼接预览地址所依赖的属性;
  • designerState.editingIframeRef:HTMLIFrameElement | null,即当前可视化编辑器的预览 iframe,本插件改写 URL 的目标;
  • snackBar.show(str):用于在编辑器内弹出轻量提示,反馈当前预览的语言;
  • user.organization:读取组织级设置(currentOrg.value.settings.plugins.get(pluginId))的入口,插件配置存储的落点。

这套约定同样适用于编写其他 Builder.io 插件——凡是需要感知"当前正在编辑哪个页面、当前预览 iframe 是什么"的场景,都可以复用 designerState 与 editingContentModel 这两个上下文入口。

六、已知限制与使用提示

  • 仅支持路径前缀本地化:插件按 /{localeCode} 拼接预览 URL,不支持子域或 cookie/header 类的本地化方案;站点侧的路由仍需由你的 Next.js i18n 配置保证与插件 locale 列表一致;
  • 默认语言无前缀:列表中第一个 locale 视为默认语言,切换回它时 URL 不带前缀;因此在配置顺序上,请把默认语言放在第一位;
  • HTTP 混合内容:本地开发时需手动放行 http 脚本,否则插件无法在 https 的 Builder 站点上加载;
  • 预览切换是临时行为:插件通过改写 iframe src 实现预览,不修改内容模型的 previewUrl,从而避免污染默认预览路径;
  • 配置与开发环境以本仓库为准:上述命令、端口(1268)与文件结构均来自仓库中的 package.json 与 webpack.config.js,若版本演进请以对应版本源码为准。

结语

localized-preview 是一个小而精的 Builder.io 插件范例:它用约百行源码完成了"读取组织级配置 → 注入工具栏组件 → 拼接多语言预览 URL → 反馈切换结果"的完整闭环,展示了 Builder.register、@builder.io/app-context 与 webpack SystemJS 产物在 Builder 插件体系中的协作方式。无论你是想直接使用它解决多语言预览问题,还是把它当作编写自定义 Builder 插件的参考模板,本文覆盖的安装、配置与源码解析都足以支撑你在此基础上继续深入。

登录后查看全文
builder