Builder.io 自定义组件 Input 接口完全指南：从基础字段到高级验证与可视化编辑

Builder.io 自定义组件 Input 接口完全指南从基础字段到高级验证与可视化编辑【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本篇技术指南围绕 Builder.io 核心包中用于声明自定义组件可编辑属性的Input接口展开系统讲解如何通过Builder.registerComponent为 React、Vue、Svelte、Qwik 等前端项目的自定义组件声明可视化编辑所需的输入字段。读完本文你将掌握 Input 接口的全部字段语义、各输入类型text、number、enum、reference、file、object 等的配置方式以及 required、regex、min/max 等校验与高级编辑能力的实战用法。Input 接口是什么自定义组件与可视化编辑器的桥梁在 Builder.io 的视觉开发体系中你通过Builder.registerComponent将自定义组件注册进可视化编辑器。而inputs数组就是声明该组件的哪些 prop 可以由用户在编辑器中编辑、以及如何编辑的配置清单。Input接口正是这个数组中每个元素的类型定义其源码位于 packages/core/src/builder.class.ts对应的 TypeDoc 文档为 packages/core/docs/interfaces/Input.md。接口文档给出的最简用法如下Builder.registerComponent(MyComponent, { inputs: [{ name: title, type: text }] // - Input[] })这行代码的含义是注册MyComponent组件并声明它有一个名为title的 prop在可视化编辑器中以文本输入框的形式呈现。组件注册后该配置会通过window.parent.postMessage以builder.registerComponent消息的形式同步给编辑器宿主页面从而驱动选项编辑器的渲染见 packages/core/src/builder.class.ts 中registerComponent的实现。在仓库的示例中可以看到非常贴近实战的注册写法例如 examples/next-js-builder-site/src/components/code-block.config.tsexport const codeBlockConfig { name: Code Block, inputs: [ { name: code, type: longText, defaultValue: const incr num num 1 }, { name: language, type: string, defaultValue: javascript }, { name: dark, type: boolean, defaultValue: false }, ], };再如 examples/embed-starter-kit/site/blocks/page/hero/hero.builder.ts 中的 Hero 区块完整展示了friendlyName、type: file、allowedFileTypes与required的组合用法。本文后续将逐个拆解 Input 接口的每一个属性。必填属性name 与 typeInput 接口中有且仅有两个必填属性name必填stringThis is the name of the component prop this input representsname是当前输入所对应的组件 prop 名称。它必须与组件接收的 props 保持一致否则编辑器写入的值无法正确传递到组件。例如上面 Code Block 示例中的name: code、name: language、name: dark分别对应组件内部读取的props.code、props.language、props.dark。type必填stringThe type of input to use, such as texttype决定编辑器为该 prop 渲染何种输入控件。常见的内置类型包括text、longText、html、url、number、boolean、enum、file、reference、object、list等本文涉及的示例中已出现text/string、longText、boolean、file。此外你可以通过 Builder.io 的插件机制创建自定义输入类型及其配套的编辑器 UI详见 packages/core/src/builder.class.ts 中对type的源码注释。展示与提示类属性让编辑器对使用者更友好friendlyName可选stringA friendlier name to show in the UI if the component prop name is not ideal for end users当 prop 名如imageSrc不适合直接暴露给非技术用户时用friendlyName提供更友好的展示名称。Hero 示例中name: imageSrc, friendlyName: Hero Image即为此用途——编辑器界面显示 Hero Image而组件仍接收imageSrcprop。helperText可选stringAdditional text to render in the UI to give guidance on how to use this在输入控件下方渲染额外的引导文案。文档给出了官方示例helperText: Be sure to use a proper URL, starting with https://这在需要提示用户填写格式时非常实用。对应源码见 packages/core/src/builder.class.ts。advanced可选booleanSet this totrueto put this under the show more section of the options editor. Useful for things that are more advanced or more rarely used and dont need to be too prominent置为true后该输入会被折叠到选项编辑器的show more显示更多区域。适合那些高级的、低频使用、不需要太显眼的配置项见 packages/core/src/builder.class.ts。required可选booleanIs this input mandatory or not标记该输入是否为必填项。Hero 示例中imageSrc输入即设置required: true强制使用者在可视化编辑器中为该字段提供值源码位置packages/core/src/builder.class.ts。defaultValue可选anyA default value to use为 prop 指定默认值。任何类型都可以作为默认值any例如 Code Block 中的defaultValue: const incr num num 1与defaultValue: false。当使用者新建组件实例时这些默认值会预先填充到 prop 中源码位置packages/core/src/builder.class.ts。输入类型专用配置enum、min/max/step 与 modelenum可选string[] 或对象数组For text input type, specifying an enum will show a dropdown of options instead针对text类型的输入提供enum后编辑器会渲染为下拉选择框而不是自由文本框。enum有两种形式源码见 packages/core/src/builder.class.ts纯字符串数组enum: [small, medium, large]对象数组可自定义显示标签、值与辅助说明enum: [ { label: Small, value: s, helperText: 适合紧凑布局 }, { label: Large, value: l }, ]对象形式中label用于展示、value为实际写入 prop 的值支持 string、number、boolean、helperText可选用于补充说明。min / max / step可选number这三个属性专门作用于数字输入类型max数字字段校验所允许的最大输入值packages/core/src/builder.class.tsmin数字字段校验所允许的最小输入值packages/core/src/builder.class.tsstep使用箭头按钮调整数字时的步长packages/core/src/builder.class.ts组合示例{ name: columns, type: number, defaultValue: 3, min: 1, max: 12, step: 1 }model可选stringUse optionally with inputs of typereference. Restricts the content entry picker to a specific model by name.当输入类型为reference内容引用时model用于按名称将内容条目选择器限定到某个特定模型见 packages/core/src/builder.class.ts。例如声明一个只允许引用 blog-post 模型内容的输入{ name: relatedPost, type: reference, model: blog-post }校验机制regex 字段验证regex用于对所有字符串类型text、longText、html、url 等的输入做正则校验其类型结构如下packages/core/src/builder.class.ts属性类型必填说明patternstring是用于测试的正则模式如^\/[a-z]$optionsstring否传给RegExp构造函数的标志位如gimessagestring是校验失败时展示给最终用户的友好提示如You must use a relative url starting with /...典型用法示例{ name: slug, type: url, regex: { pattern: ^\\/[a-z0-9-]$, message: 请输入以 / 开头的相对路径如 /about-us, }, }当用户在编辑器中输入的字符串不匹配pattern配合options标志时界面会展示message中定义的提示文案。选择器联动与多语言broadcast、bubble 与 localizedbroadcast可选booleanSet this totrueto show the editor for this input when children of this component are selected. This is useful for things like Tabs, such that users may not always select the Tabs component directly but will still be looking for how to add additional tabs置为true后当选中该组件的子组件时此输入对应的编辑器依然会显示。典型场景是 Tabs标签页这类容器组件用户常常直接选中内部的 Tab 子元素而非最外层的 Tabs 容器但此时用户仍期望能添加新的 Tab。broadcast让这类隐藏在一层之下的重要输入始终可见源码见 packages/core/src/builder.class.ts。bubble可选booleanSet this totrueto show the editor for this input when group locked parents of this component are selected. This is useful to bubble up important inputs for locked groups, like text and images与broadcast方向相反置为true后当选中该组件的被锁定的父级分组时此输入的编辑器会冒泡显示。这对锁定的分组locked groups中那些重要输入如文本、图片很有用源码见 packages/core/src/builder.class.ts。localized可选booleanSet this totrueif you want this component to be translatable置为true表示该输入支持多语言翻译即该组件可以被本地化见 packages/core/src/builder.class.ts。在启用多语言的站点中localized: true的字段会进入翻译流程让内容团队可以为不同语言环境维护不同的值。进阶输入组织subFields 与类型扩展subFields可选Input[]subFields本身是Input类型的数组即嵌套的输入定义用于声明复合类型的子字段。接口定义见 packages/core/src/builder.class.ts。配合object/list等复合输入类型可以让一个输入项承载结构化的数据。例如为一个 hero 区块声明结构化的链接对象{ name: link, type: object, subFields: [ { name: label, type: text, defaultValue: 了解更多 }, { name: href, type: url, required: true }, { name: newTab, type: boolean, defaultValue: false }, ], }从源码结构看subFields采用递归引用自身类型readonly Input[]这意味着理论上可以构建任意深度的嵌套输入结构且编辑器会为每个子字段递归渲染对应的输入控件。Input接口中还包含folded与keysHelperText两个对object类型输入友好的字段folded让编辑器默认折叠该对象输入以节省画布空间keysHelperText则提供编辑该对象内容的引导文案见 packages/core/src/builder.class.ts。仓库中的实战用例汇总仓库内多个示例与模板项目都在真实使用 Input 接口可对照学习不同字段的组合方式examples/next-js-builder-site/src/components/code-block.config.tslongText、string、boolean三种输入类型与默认值的组合examples/embed-starter-kit/site/blocks/page/hero/hero.builder.tsfriendlyName、file类型、allowedFileTypes与required组合examples/embed-starter-kit/site/blocks/page/double-columns/double-columns.builder.ts 与 examples/embed-starter-kit/site/blocks/page/dynamic-columns/dynamic-columns.builder.ts布局类组件的多输入声明examples/gatsby-minimal-starter/src/components/Hero/Hero.builder.jsGatsby 项目中的组件注册与输入声明examples/angular-gen1/src/app/app.component.ts、examples/angular-universal/src/app/app.component.tsAngular 项目中的输入声明examples/astro-solidjs/src/components/App.jsxAstro SolidJS 项目中的输入声明packages/cli/src/templates/nextjs/[...page].jsx 与 packages/cli/src/templates/nextjs/[...page].tsxCLI 脚手架模板中自定义组件title/description输入与自定义插入菜单的注册示例。另外核心包的测试 packages/core/src/builder.class.test.ts 验证了registerComponent注册的组件规格component spec会被完整保留在Builder.components中可作为理解注册链路registerComponent→prepareComponentSpecToSend→ postMessage 同步给编辑器的参考。快速上手为你的第一个自定义组件声明输入综合以上全部字段一个覆盖常用能力的完整注册示例Builder.registerComponent(MyHero, { name: MyHero, inputs: [ { name: title, type: text, defaultValue: Hello World, required: true, helperText: 输入主标题 }, { name: subtitle, type: longText, defaultValue: 欢迎来到我的站点 }, { name: ctaLabel, type: text, enum: [了解更多, 立即购买, 联系我们], defaultValue: 了解更多 }, { name: ctaUrl, type: url, regex: { pattern: ^https://, message: 请输入以 https:// 开头的完整 URL } }, { name: columns, type: number, defaultValue: 2, min: 1, max: 6, step: 1 }, { name: darkMode, type: boolean, defaultValue: false, advanced: true }, { name: image, type: file, friendlyName: 背景图, required: true, allowedFileTypes: [png, jpg, svg, webp] }, { name: showCta, type: boolean, defaultValue: true }, { name: link, type: object, subFields: [ { name: label, type: text, defaultValue: Learn more }, { name: href, type: url, required: true }, ]}, ], });核心要点回顾name与type是必填项defaultValue、friendlyName、helperText、required决定输入的基础行为与展示enum、min/max/step、model按输入类型提供下拉、数值区间与内容引用限定regex为字符串类型提供带友好提示的正则校验broadcast、bubble、localized、advanced控制输入的可见范围、层级联动与多语言能力subFields支持构建结构化嵌套输入。掌握这些字段后你可以让任何前端框架React、Vue、Svelte、Qwik、Angular、Astro 等中的自定义组件在 Builder.io 可视化编辑器中获得一致、可校验、对内容编辑者友好的配置体验。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考