Builder Widgets 实战指南:为 Builder.io 编辑器接入 Carousel、Tabs、Accordion 与 Masonry 组件
Builder Widgets 实战指南:为 Builder.io 编辑器接入 Carousel、Tabs、Accordion 与 Masonry 组件
@builder.io/widgets 是 Builder.io 官方维护的交互组件包,为可视化编辑器注入 Carousel(轮播图)、Tabs(标签页)、Accordion(手风琴)、Masonry(瀑布流)等开箱即用的高级组件。本文以 packages/widgets/README.md 为骨架,结合本仓库源码,完整讲解从安装、同步注册到 Next.js 与其他框架下的懒加载接入方案,并逐项剖析四个组件的可配置参数,帮助你在任何渲染 <BuilderComponent /> 的应用中快速复用这些组件。
一、Widgets 是什么:一个包,四个可编辑组件
Widgets 包的定位非常明确:为 Builder.io 的可视化编辑体验提供交互型 UI 组件。从 src/builder-widgets.ts 可以看到,该包共注册了四个组件:
- Carousel(
Builder:Carousel):基于react-slick的轮播图,支持自动播放、分页圆点、响应式断点; - Tabs(
Builder: Tabs):标签页切换,支持默认激活项、可折叠、表头对齐方式; - Accordion(
Builder:Accordion):手风琴折叠面板,支持每次只展开一项、网格布局; - Masonry(
Builder:Masonry):基于react-masonry-component的瀑布流网格。
每个组件的“配置描述文件”(*.config.ts)定义了它在编辑器中的名称、默认样式、输入参数(inputs)以及可编辑选项,这些配置会通过 Builder.registerComponent() 注册到 Builder 运行时,因此这些组件既能在可视化编辑器的组件面板中出现,也能在页面渲染(包括服务端渲染)时按配置输出真实 DOM。
二、安装与同步注册:三行代码接入
首先安装包:
npm install @builder.io/widgets
当使用 React SDK 时,在你渲染 <BuilderComponent /> 的任意位置导入根入口:
import '@builder.io/widgets';
导入发生的那一刻,四个组件即完成注册,之后便可在 Visual Editor 中使用,并且能正常参与渲染(包括服务端渲染)。
这一“副作用导入”背后的原理在 src/builder-widgets.ts 中一目了然——它同步引入了四个组件实现与四份配置,并依次调用 Builder.registerComponent:
Builder.registerComponent(CarouselComponent, carouselConfig);
Builder.registerComponent(TabsComponent, tabsConfig);
Builder.registerComponent(AccordionComponent, accordionConfig);
Builder.registerComponent(MasonryComponent, masonryConfig);
注意,同步导入会一次性把四个组件(连同 react-slick、react-masonry-component 等依赖)全部打进包体,即使页面只用到其中一个。如果你的内容是动态获取的,更推荐采用下面的懒加载方案。
官方示例对照
仓库中有一个可直接运行的示例 examples/next-js-simple(页面实现),它演示了在 Next.js 页面中通过 getStaticProps 拉取 Builder 内容并渲染 <BuilderComponent model="page" content={page} /> 的完整流程,是验证 Widgets 集成效果的理想起点。
三、懒加载:按需加载你用到的组件
同步导入会注册全部组件,而懒加载方案只在你实际使用到某个组件时才异步加载它的实现。根据运行框架的不同,有两种接入方式。
3.1 Next.js:官方异步入口
Next.js 用户可以直接导入包提供的异步入口:
import '@builder.io/widgets/dist/lib/builder-widgets-async'
该入口的实现在 src/builder-widgets-async.tsx:它依然同步注册四个组件,但每个组件的实现都改由 next/dynamic 包装,组件代码被拆分为独立 chunk,只有内容中真正渲染该组件时才会被请求加载:
import dynamic from 'next/dynamic';
import { Builder } from '@builder.io/react';
Builder.registerComponent(
dynamic(() => import('./components/Carousel').then(mod => mod.CarouselComponent as any)),
carouselConfig
);
// Tabs、Accordion、Masonry 同理
官方示例 examples/next-js-simple/pages/[[...page]].tsx 的第 7-8 行正是按此方式接入的,注释明确写道:"loading widgets dynamically to reduce bundle size, will only be included in bundle when is used in the content"(动态加载 widgets 以减小包体积,仅在内容使用到时才进入打包产物)。
3.2 其他框架:配合任意懒加载库
对于非 Next.js 框架,README 给出的思路是:用你熟悉的懒加载库(如 react-loadable)显式注册单个组件,只加载内容中实际使用到的组件。以 Accordion 为例:
import { Builder } from '@builder.io/react';
import { accordionConfig } from '@builder.io/widgets/dist/lib/components/Accordion.config';
import loadable from '@loadable/component';
Builder.registerComponent(
loadable(() =>
import('@builder.io/widgets/dist/lib/components/Accordion').then(mod => mod.AccordionComponent)
),
accordionConfig
);
这段代码的关键在于:
accordionConfig从独立的Accordion.config模块导入,它只包含轻量的描述数据(名称、默认样式、inputs),不会拖入组件实现;- 组件实现通过
loadable()异步加载,Builder.registerComponent拿到的是加载器而非组件本身; - 每个组件都有对应的独立模块路径(
Accordion、Carousel、Tabs、Masonry),按需组合即可。
同理,你也可以用 React 内置的 Suspense + lazy 实现同样的效果,README 明确指出该方法与 Suspense 兼容。
仓库中还保留了一个 react-loadable 的封装示例 src/functions/async-component.tsx,虽然其主体目前处于注释状态,但它展示了统一的 Loading 占位与出错重载(reload())处理思路,可作为自定义懒加载封装的参考。
四、四个组件的可配置参数详解
以下参数来自各组件独立的配置文件,均可在 Builder 可视化编辑器的属性面板中直接调整,也可在代码中通过组件输入覆盖。
4.1 Carousel 轮播图(Carousel.config.ts)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
slides |
list | 两个默认 slide | 幻灯片数组,每项包含可编辑的 content(uiBlocks),showIf 未开启 useChildrenForSlides 时生效 |
hideDots |
boolean | false |
是否隐藏分页圆点 |
autoplay |
boolean | false |
是否每隔几秒自动切换到下一张 |
autoplaySpeed |
number | 5 |
自动播放间隔(秒),仅在 autoplay 开启时显示 |
prevButton / nextButton |
uiBlocks | 默认箭头图片 | 自定义上/下一张按钮(编辑器内可编辑) |
useChildrenForSlides |
boolean | false |
改用子元素作为每个 slide(对动态循环的 slide 很有用);开启时会清空 slides 数组 |
responsive |
array | [{width:3000,slidesToShow:2,...},{width:400,...}] |
响应式断点设置,字段与 slick 一致(breakpoint、slidesToShow、slidesToScroll、infinite、dots) |
accessibility |
boolean | false |
为屏幕阅读器与键盘导航启用无障碍特性 |
focusOnSelect |
boolean | false |
切换后聚焦当前 slide,提升无障碍体验 |
实现细节(Carousel.tsx):
autoplaySpeed在传给 slick 前会被乘以 1000 转换为毫秒;- 组件挂载后会派发
builder:carousel:load自定义事件,slide 切换后派发builder:carousel:change,可通过事件detail中的block、carousel等字段与页面其他逻辑交互; - 服务端渲染(非浏览器)时只渲染第一张 slide(
slides.slice(0, 1)),保证首屏输出稳定。
4.2 Tabs 标签页(Tabs.config.ts)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
tabs |
list | 两个默认标签 | 每个 tab 包含 label(标签头)与 content(内容区),均为可编辑 uiBlocks |
activeTabStyle |
uiStyle | { backgroundColor: 'rgba(0,0,0,0.1)' } |
当前激活 tab 的 CSS 样式 |
defaultActiveTab |
number | 1 |
默认打开的 tab:1 为第一个、2 为第二个,0 表示默认不打开 |
collapsible |
boolean | false |
开启后点击已打开的 tab 可将其关闭(无激活 tab 状态) |
tabHeaderLayout |
enum | flex-start |
表头对齐方式:center / space-between / space-around / flex-start / flex-end,实现为 justify-content |
实现细节(Tabs.tsx):defaultActiveTab 在 componentWillMount 中被减 1 作为内部索引(即配置里写 1 对应第一项);激活 tab 的 activeTabStyle 以行内样式注入;表头容器支持横向滚动(overflow: auto + 触屏惯性滚动)。
4.3 Accordion 手风琴(Accordion.config.ts)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items |
list | 两个默认条目 | 每项包含 title(标题)与 detail(详情),均为可编辑 uiBlocks |
oneAtATime |
boolean | false |
只允许同时展开一项,打开新项时折叠其他项 |
grid |
boolean | false |
以网格形式展示条目 |
gridRowWidth |
string | '25%' |
网格模式下每个标题的宽度,仅在 grid 开启时显示 |
useChildrenForItems |
boolean | false |
改用子元素作为条目,便于动态循环生成 |
实现细节(Accordion.tsx):grid 或 oneAtATime 任一开启时内部均按“每次只开一项”处理(onlyOneAtATime = Boolean(grid || oneAtATime));网格模式下会用 order 属性将展开项详情排到当前行之后,实现“展开后当前行自动右移”的布局效果;挂载后派发 builder:accordion:load 事件。
4.4 Masonry 瀑布流(Masonry.config.ts)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columnWidth |
string | '200px' |
每个瓦片的宽度(CSS 值),如 "200px" 或 "50%" |
gutterSize |
number | 0 |
瓦片之间的水平间距(像素) |
tiles |
list | [] |
瓦片数组,每项为可编辑的 content(uiBlocks) |
useChildrenForTiles |
boolean | true |
默认使用子元素作为瓦片;关闭后改用 tiles 数组 |
实现细节(Masonry.tsx):配置中 columnWidth 以 % 或 . 开头时会启用 percentPosition,以 % 结尾时关闭 fitWidth(其余情况自动居中适应容器宽度);布局完成后容器透明度从 0 过渡到 1,避免瀑布流布局计算期间内容闪跳;挂载后派发 builder:masonry:load 事件。注意该组件的 gutterSize 在组件接口中声明为 string 类型(配置中为 number),以实际传递值被 react-masonry-component 消费为准。
五、服务端渲染与包体优化要点
- SSR 安全:Carousel 与 Masonry 在非浏览器环境下都会对渲染内容做裁剪(如 Carousel 只渲染第一张 slide),避免服务端输出过大或产生与客户端不一致的布局,保证首屏 HTML 稳定输出;
- 样式注入:Carousel 组件内置了完整的 slick 样式(Carousel.tsx 中的
slickStyles),服务端以<style type="text/css">形式内联输出,客户端同样通过<style>注入,无需额外引入 slick 的 CSS 文件; - 事件驱动扩展:三个组件(Carousel/Accordion/Masonry)都会在挂载时派发带
detail的冒泡自定义事件,可结合 Builder 的交互/动画能力做进一步定制; - 版本与依赖前提:当前仓库中该包版本为
2.1.3(见 packages/widgets/package.json),要求@builder.io/react >= 5.0.11作为 peer 依赖,next >= 12.3.5可选(用于next/dynamic异步入口),react/react-dom支持>=16及^19.0.0-rc,Node 环境要求>=10。安装前请确认你的 SDK 版本满足这些范围。
六、小结
@builder.io/widgets 用一个包解决了 Builder.io 页面中四类高频交互组件的可视化编辑问题:同步导入一行代码即可全部注册;Next.js 场景使用 builder-widgets-async 入口配合 next/dynamic 按需拆包;其他框架则可用 react-loadable 或 Suspense 逐组件注册。结合本文整理的参数表,你可以在编辑器中直接配置轮播的自动播放与响应式断点、标签页的默认激活项与对齐方式、手风琴的单开/网格模式,以及瀑布流的列宽与间距,实现“内容编辑零代码、交互能力开箱即用”。