Builder.io Cloudinary 图片插件实战从自定义组件注册到本地开发与发布【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本篇文章围绕 Builder.io 官方仓库中的 Cloudinary 图片插件plugins/cloudinary展开系统讲解如何将该插件接入 Builder.io Visual Editor、如何通过cloudinaryImageEditor自定义输入类型注册组件并在可视化编辑器中选图以及如何基于仓库源码理解其底层实现并完成插件的本地开发、调试与发布。读完本文你将掌握 Builder.io 插件体系中自定义编辑器类型的完整落地套路并能在自己的项目中直接复刻这一选图体验。插件能做什么Builder.io Cloudinary 插件的作用是让你在 Builder.io 的 Visual Editor可视化编辑器中直接使用 Cloudinary 官方 Media Library媒体库组件来访问和管理 Cloudinary 上的图片内容而不必离开 Builder 的编辑界面、手动拷贝图片 URL。也就是说内容编辑者可以在搭建页面时通过一个标准的 Cloudinary 媒体库弹窗浏览、搜索、选中自己云账号里的图片资产选中的图片信息URL、宽高、public_id 等会被写回到 Builder 内容的字段中最终由页面组件渲染输出。插件本身并不直接渲染图片而是提供一个编辑器它注册了一个名为cloudinaryImageEditor的自定义输入类型custom type任何在 Builder.io 中注册的自定义组件只要把某个 input 的类型声明为cloudinaryImageEditor在 Visual Editor 中编辑该组件时就会自动出现 Cloudinary 选图界面。安装插件安装路径在 Builder.io 控制台的Integrations集成选项卡中登录 Builder.io 并进入你的 dashboard打开Integrations选项卡在插件列表中找到 Cloudinary 插件点击Enable启用即可。启用后插件会在你的 Builder 空间内注册cloudinaryImageEditor这个自定义编辑器类型接下来就可以在你的 Web 应用里使用它了。使用插件注册一个 CloudinaryImage 自定义组件要在页面中使用 Cloudinary 图片你需要先注册一个自定义组件并把它的某个输入类型指定为cloudinaryImageEditor。仓库 README 给出的示例基于builder.io/reactimport { Builder } from builder.io/react Builder.registerComponent( (props) { if (!props.cloudinaryOptions) { return Choose an Image } return ( img src{props.cloudinaryOptions.url} width{props.cloudinaryOptions.width} height{props.cloudinaryOptions.height} / ) }, { name: CloudinaryImage, image: https://res.cloudinary.com/cloudinary-marketing/image/upload/v1599098500/creative_source/Logo/Cloud%20Glyph/cloudinary_cloud_glyph_blue_png.png, inputs: [{ name: cloudinaryOptions, type: cloudinaryImageEditor }], } )这段代码做了三件事注册组件Builder.registerComponent把CloudinaryImage注册为一个 Builder 自定义组件声明渲染逻辑组件函数根据props.cloudinaryOptions是否存在决定显示占位文本还是渲染img图片地址、宽高均取自该字段绑定编辑器inputs数组中声明cloudinaryOptions字段的类型为cloudinaryImageEditor这正是插件提供的自定义编辑器类型。完成注册后回到 Visual Editor你会在组件面板中看到名为Cloudinary Image的自定义组件。把它拖拽到内容画布中任意位置即可通过内嵌的 Cloudinary 媒体库为它选择图片。由于插件基于 Builder 的字段体系工作选中图片后生成的字段值会随 Builder 内容一起持久化渲染端无需任何额外逻辑即可直接消费。字段值的实际形态从插件源码可以确认选图后写入字段的是 Cloudinary Media Library 返回的资产对象。插件在 CloudinaryMediaLibraryDialog.tsx 中定义了CloudinaryImage接口export interface CloudinaryImage { context: any; public_id: string; url: string; tags: any[]; derived: any[]; }其中url是图片地址、public_id是资源在 Cloudinary 中的唯一标识、derived通常包含派生经过变换版本的 URL 信息、context可携带自定义元数据如 caption、alt 等。所以上面示例组件中使用的props.cloudinaryOptions.url、.width、.height都有明确的字段依据。第一次使用认证与选图首次在 Visual Editor 中使用该组件时插件会提示你认证 Cloudinary 账号。编辑器界面包含两个按钮对应两种操作SET CREDENTIALS设置凭据点击后弹出凭据设置对话框需要填写两个字段API keyCloudinary 的 API 密钥Cloud nameCloudinary 云名称。需要注意的约束要让该流程正常工作你需要在 Builder.io 中启用 SSO 并保持已登录状态——当前版本的插件不支持其他认证方式源码注释也明确说明No need to use username for cloudinary login if SSO is enabled。凭据只需设置一次。从源码看凭据保存后会写入组织organization级设置CloudinaryImageEditor.tsx中的 getter/setter 把cloudinaryCloud与cloudinaryKey存入this.organization.value.settings.plugins这个 Map并调用this.organization.save()持久化见 CloudinaryImageEditor.tsx。因此同一组织下的编辑会话都无需重复输入凭据对话框内的 helper 文案也明确写着You just have to setup the API key once and it will be linked to your organization。CHOOSE IMAGE选择图片凭据设置完成后点击CHOOSE IMAGE会弹出一个 Cloudinary 媒体库浏览器对话框。在媒体库中选中资产后点击INSERT按钮即可将图片插入页面。两个关键行为每次只能选中一张图片源码中以multiple: false, max_files: 1配置媒体库见 CloudinaryMediaLibraryDialog.tsx选中图片后编辑器底部会显示当前选中资源的Public id方便你确认资源按钮文案也会从CHOOSE IMAGE变为UPDATE IMAGE用于替换当前图片对应 CloudinaryImageEditor.tsx 中的buildChooseImageText逻辑。源码级原理编辑器内部是如何工作的从源码结构看插件由三个 React 组件构成职责非常清晰文件职责CloudinaryImageEditor.tsx主编辑器组件负责状态管理、凭据读写与按钮渲染并在文件底部调用Builder.registerEditor({ name: cloudinaryImageEditor, component: CloudinaryImageEditor })完成注册CloudinaryCredentialsDialog.tsx凭据设置对话框提供 API key 与 Cloud name 两个输入框CloudinaryMediaLibraryDialog.tsx媒体库对话框封装 Cloudinary Media Library 组件并处理选图回调媒体库脚本的加载方式CloudinaryImageEditor在componentDidMount阶段会动态向页面注入 Cloudinary 媒体库脚本private appendMediaLibraryScriptToPlugin() { const previousScript document.getElementById(cloudinaryScript); if (!previousScript) { const script document.createElement(script); script.async true; script.src https://media-library.cloudinary.com/global/all.js; script.id cloudinaryScript; document.head.appendChild(script); } }它通过idcloudinaryScript做去重确保脚本只被注入一次异步加载避免阻塞 Builder 界面。媒体库的创建与选图回调CloudinaryMediaLibraryDialog在对话框渲染完成后onRendered回调打开媒体库创建时把组织级凭据传入mediaLibrary newWindow.cloudinary.createMediaLibrary( { cloud_name: this.props.cloudName ? this.props.cloudName : , api_key: this.props.apiKey ? this.props.apiKey : , inline_container: .cloudinaryContainer, }, { insertHandler: (data) { this.selectImage({ ...data.assets[0] }); }, } );选中资产后insertHandler拿到data.assets[0]即第一张选中的图通过selectImage冒泡给主编辑器最终由主编辑器调用组件 props 上的onChange把图片对象写回 Builder 字段。凭据未设置时的兜底逻辑主编辑器通过areCloudinaryCredentialsNotSet()判断 API key 或 Cloud name 是否为空当凭据缺失时CHOOSE IMAGE按钮会被禁用disabled属性并优先展示凭据设置对话框。这一行为在测试中也有覆盖__tests__/cloudinaryImageEditor.test.tsx验证了无凭据时选图按钮禁用以及凭据写入后 state 被正确更新。测试如何保障插件行为插件附带了一套基于 Jest Enzyme 的单元测试位于 plugins/cloudinary/tests覆盖了三个核心场景cloudinaryImageEditor.test.tsx验证无图时按钮显示CHOOSE IMAGE、有图时显示UPDATE IMAGE、底部展示当前Public id、无凭据时按钮禁用、凭据更新后正确回调、有凭据时渲染媒体库对话框、选图后把资产对象传给onChangecloudinaryCredentialsDialog.test.tsx验证对话框渲染 API key / Cloud name 输入框、输入值写入 state、点击保存时触发updateCloudinaryCredentials与closeDialog回调cloudinaryMediaLibraryDialog.test.tsx通过 mockwindow.cloudinary.createMediaLibrary验证insertHandler会把data.assets[0]作为选中图片、凭据为空时回退为空字符串、点击关闭按钮会触发closeDialog。这些测试很好地展示了自定义编辑器类型插件的可测试性context通过 props 注入、window.cloudinary可 mock因此几乎不需要真实网络请求就能覆盖关键交互路径。运行测试的命令为npm test插件开发本地克隆、调试与发布如果你觉得现成插件不满足需求想针对自己的使用场景改造它可以按下面的流程在本地开发。关于 Builder 插件机制的通用说明可参考仓库内其他插件的组织方式例如 plugins 目录下各插件均采用类似的srcrollup.config.ts结构。1. 安装依赖git clone https://github.com/BuilderIO/builder.git cd plugins/cloudinary npm install2. 启动开发服务器npm start该脚本见 package.json 的start字段会以SERVEtrue运行 rollup 的 watch 模式并在1268 端口启动一个静态服务器。从 rollup.config.ts 可以看到这个开发服务器配置了Access-Control-Allow-Origin: *和Access-Control-Allow-Private-Network: true响应头以便本地开发时被 Builder 的 https 页面跨域加载。3. 把开发版插件挂到 Builder.io进入你的 Account Settings账户设置页面点击Plugins旁边的编辑铅笔按钮输入开发版插件的 URL例如http://localhost:1268/builder-plugin-cloudinary.system.js保存。builder-plugin-cloudinary.system.js对应 package.json 中声明的main/unpkg产物由 rollup 以 SystemJS 格式UMD、ES 与 System 三种格式同时产出打包生成。注意在 https 站点上加载 http 内容会触发混合内容警告。本地开发时需要点击浏览器右上角的盾牌图标选择加载不安全脚本load unsafe scripts允许 Builder 的 https 页面加载本地 http 资源。之后每当你修改源码并重新构建重启 Builder 即可看到插件的最新版本。4. 卸载开发版插件回到 Account Settings点击Plugins旁的编辑按钮从列表中删除你的开发 URL 并保存即可。5. 技术栈与发布插件的 UI 技术栈与 Builder 本身保持一致React组件框架Material UI对话框、按钮、文本输入等界面组件源码中大量使用material-ui/core的Dialog、Button、TextField、TypographyEmotionCSS-in-JS 样式方案源码中的css{...}属性均来自emotion/core。在 Builder 插件中使用这些框架可以保证最佳的体验与性能。注意 rollup.config.ts 中把react、builder.io/sdk、material-ui/core、emotion/core等声明为external注释说明插件必须与宿主页面共享这些依赖的同一份引用才能正常运行——这是开发 Builder 插件时的关键约束。如果你认为自己的插件对 Builder 社区有复用价值可以给本仓库提交 Pull Request维护者会进行评审。否则当插件准备好后你也可以发布 npm 包并把打包后的 JS 链接添加到Account Settings Plugins中该入口仅对企业版用户开放。小结Builder.io Cloudinary 插件是理解 Builder 插件体系的一个极佳范例它通过Builder.registerEditor暴露自定义输入类型借助组织级 settings 持久化凭据再以官方 Media Library 组件提供选图体验。对于要在 Builder 内容中接入任意外部素材库图片、视频、文档等的开发者而言本文介绍的自定义编辑器模式可以直接迁移复用仓库内的源码与测试则为二次开发提供了完整且可验证的参考实现。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考