Builder Widgets 实战指南:为 Builder.io 编辑器接入 Carousel、Tabs、Accordion 与 Masonry 组件

原创2026-09-15 19:35:191,351 阅读
文章标签:前端低代码CMS

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 消费为准。

五、服务端渲染与包体优化要点

  1. SSR 安全:Carousel 与 Masonry 在非浏览器环境下都会对渲染内容做裁剪(如 Carousel 只渲染第一张 slide),避免服务端输出过大或产生与客户端不一致的布局,保证首屏 HTML 稳定输出;
  2. 样式注入:Carousel 组件内置了完整的 slick 样式(Carousel.tsx 中的 slickStyles),服务端以 <style type="text/css"> 形式内联输出,客户端同样通过 <style> 注入,无需额外引入 slick 的 CSS 文件;
  3. 事件驱动扩展:三个组件(Carousel/Accordion/Masonry)都会在挂载时派发带 detail 的冒泡自定义事件,可结合 Builder 的交互/动画能力做进一步定制;
  4. 版本与依赖前提:当前仓库中该包版本为 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 逐组件注册。结合本文整理的参数表,你可以在编辑器中直接配置轮播的自动播放与响应式断点、标签页的默认激活项与对齐方式、手风琴的单开/网格模式,以及瀑布流的列宽与间距,实现“内容编辑零代码、交互能力开箱即用”。

登录后查看全文
builder