Builder Localized Preview 插件实战:在 Builder.io 编辑器中实现多语言可视化预览
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.registerAPI,用于向 Builder Web 应用注册插件能力。
插件入口文件是 src/plugin.ts,其中通过三条 Builder.register 调用完成了插件的"注册三连":
Builder.register('editor.toolbarButton', ...)—— 把语言切换器组件挂到编辑器顶部工具栏;Builder.register('plugin', ...)—— 声明插件元信息与可配置的settings(locale 列表);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
安装完成后,插件目录下会包含如下核心源码文件:
- src/plugin.ts —— 插件主入口与配置声明;
- src/components/language-switcher.tsx —— 工具栏语言切换器 UI 组件;
- src/interfaces/application-context.ts —— 对
ApplicationContext的扩展类型定义; - src/models/localization.ts ——
localization数据模型定义; - src/constants.ts —— 插件 ID 常量
@builder.io/plugin-localized-preview。
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 插件的参考模板,本文覆盖的安装、配置与源码解析都足以支撑你在此基础上继续深入。