Elementorelementor/wp-media包完全指南WordPress 媒体库适配器的能力演进与源码剖析【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor本指南以 Elementor 前端拖拽页面构建器仓库中的elementor/wp-media包路径 packages/packages/libs/wp-media为对象从它的 CHANGELOG.md 版本演进出发结合源码与测试系统讲解该包如何封装 WordPress 的wp.media函数、打开媒体弹窗、选择/上传图片、读取附件数据以及支持 SVG 上传、限制图片类型、URL 导入等能力的实现原理。读完本文你将掌握这个包从 0.1.0 到 0.6.1 每个版本能力的用法、底层调用链与约束条件并能在自己的 Elementor 编辑器扩展中正确接入它。一、包定位WordPresswp.media的前端适配层elementor/wp-media在仓库中位于packages/packages/libs/wp-media其 README.md 明确指出This package is an adapter for WordPresswp.mediafunction. It allows you to open the WordPress media modal, select or upload images from the media library, and get attachment data.它假设wp.media存在于全局作用域否则会抛出异常。因此使用方必须把media-modelshandle 加入自身脚本的 dependencies 数组确保在 WordPress 后台环境中加载了媒体库模型脚本。从 package.json 可以看到该包的发布形态名称elementor/wp-media描述 An adapter for WordPress media utils通过tsup构建同时输出dist/index.jsCommonJS、dist/index.mjsESM与dist/index.d.ts类型声明exports字段按import/require分别指向对应产物依赖elementor/query4.4.0与elementor/utils4.4.0peerDependency 为react^18.3.1发布包仅包含README.md、CHANGELOG.md、/dist与/src测试目录__tests__不随包发布。包的公开 API 极简见 src/index.tsexport type { Attachment } from ./types/attachment; export type { OpenOptions, MediaType } from ./hooks/use-wp-media-frame; export { default as useWpMediaAttachment } from ./hooks/use-wp-media-attachment; export { default as useWpMediaFrame } from ./hooks/use-wp-media-frame; export { getMediaAttachment } from ./get-media-attachment;对外总共暴露两个 React HookuseWpMediaFrame、useWpMediaAttachment、一个命令式函数getMediaAttachment以及若干类型。下面结合 CHANGELOG 的版本脉络逐一深入。二、CHANGELOG 版本演进图谱0.1.0 → 0.6.1CHANGELOG.md 记录了该包从诞生到当前包内 package.json 版本为 4.4.0CHANGELOG 则记录早期独立发版历程的全部功能变更。将各版本的核心变更整理如下版本类型核心变更对应能力0.1.0 (2024-08-14)Feature新增与 wp-media 交互的 utilsEDS-324包首次发布提供媒体交互基础能力0.1.1 (2024-08-14)Bug Fix关闭时清理cleanup on closeEDS-365修复媒体弹窗关闭后的资源泄漏0.1.2 (2024-08-20)—仅版本号升级无功能变更0.2.0MinorImageControl支持 inner props内部控件能力扩展0.2.1Patch修复 package.json 的exports字段升级elementor/query与elementor/utils包导出解析修正0.2.2Patch升级elementor/utils0.3.0依赖同步0.2.3Patch更新并锁定依赖版本依赖固化0.3.0Minor支持 SVG 上传4e5ea74MediaType引入svg0.4.0Minor将getMediaAttachment从 React hook 中分离af5fa42支持限制上传图片类型a2f5096命令式 API 与类型过滤0.4.1Patch升级elementor/utils0.3.1依赖同步0.4.2Patch升级elementor/utils0.4.0依赖同步0.5.0Minor新增 API client 与 hooks用于启用 unfiltered files 上传f6a4d4f非过滤文件上传能力0.6.0Minor新增 settings transformersb8a7725设置转换能力0.6.1Patch升级elementor/utils0.5.0依赖同步值得注意的是后续版本号虽然继续增长但包内 version 已并入 Elementor 主仓库的 monorepo 版本当前为 4.4.0CHANGELOG 中的 0.x 记录是该包独立发版时期的历史。这张表既是包的能力时间线也是本文随后逐项深入的主线。三、核心一useWpMediaFrame——打开并控制媒体弹窗useWpMediaFrame是包的主入口定义于 src/hooks/use-wp-media-frame.ts。它接收一个配置对象返回{ open }由调用方在用户交互时触发弹窗。3.1 配置项完整说明Hook 的Options类型如下带注释为源码未标注、由实现推断的默认行为type Options { mediaTypes: MediaType[]; // 允许的媒体类型image | svg | video title?: string; // 弹窗标题 allowUrlImport?: boolean; // 是否允许 URL 导入开启后使用 post 型 frame onSelectUrl?: ( url: string, alt?: string ) void; // URL 导入回调 } ( | { multiple: true; selected: Array number | null ; // 多选时预选中附件 id 数组 onSelect: ( val: Attachment[] ) void; // 多选回调返回附件数组 } | { multiple: false; selected: number | null; // 单选时预选中附件 id onSelect: ( val: Attachment ) void; // 单选回调返回单个附件 } );而每次调用open( openOptions )时还可传入OpenOptions覆盖打开时的行为export type OpenOptions { mode?: upload | browse | url; // 默认 browse currentUrl?: string; // mode 为 url 时预填的 URL currentAlt?: string; // mode 为 url 时预填的 alt 文本 };3.2 弹窗创建与生命周期createFrame是核心工厂函数它做了以下几件事调用media()( { title, multiple, library } )创建 framelibrary.type由getMimeTypes( mediaTypes )根据媒体类型映射为 MIME 数组见下文 3.4。allowUrlImport时改用frame: postWordPress 的 post frame 自带从 URL 插入面板。监听open事件设置上传参数uploadTypeCaller标记为elementor-wp-media-upload便于服务端识别来源、应用 mode、并预选已选附件。监听insert select事件统一走select函数分发结果。处理扩展名白名单见 3.3。生命周期清理策略非常明确不在 close 时销毁 frame而是在下次open()或组件卸载时统一清理。cleanupFrame依次调用frame.detach()与frame.remove()。这一设计避免了与 WordPress 内部媒体生命周期发生竞态race condition对应 CHANGELOG 0.1.1 的 cleanup on close [EDS-365] 修复——它把清理时机从 close 推迟到了更安全的节点。3.3 上传扩展名的临时接管与还原handleExtensions利用全局_wpPluploadSettings实现打开期间限制可上传类型、关闭后恢复默认ready时把_wpPluploadSettings.defaults.filters.mime_types替换为按mediaTypes计算出的扩展名列表close时恢复打开前保存的默认扩展名列表。这正是 CHANGELOG 0.4.0 中 support restricting uploaded image type (a2f5096) 的实现。读取全局设置的行为封装在 src/wp-plupload-settings.ts若window._wpPluploadSettings不存在即从未打开过 WP 上传器会抛出WpPluploadSettingsNotAvailableError错误提示明确要求先确保一个 wp media uploader 处于打开状态。3.4 媒体类型 → MIME / 扩展名映射源码中维护了两张静态映射表图片imageavif, bmp, gif, ico, jpe, jpeg, jpg, png, webpMIME 为对应的image/*。SVGsvg扩展名svgMIME 为image/svgxmlCHANGELOG 0.3.0 新增。视频video扩展名mp4, webm, ogg, mov, m4v, avi, wmv, mpg, mpeg, 3gp, 3g2MIME 为video/mp4, video/webm, video/ogg, video/quicktime, video/x-m4v, video/avi, video/x-ms-wmv, video/mpeg, video/3gpp, video/3gpp2。getMimeTypes用于限定媒体库浏览范围library.typegetExtensions用于生成上传时的扩展名白名单。二者都由mediaTypes.reduce(...)累加生成因此传入[image, svg]即可同时允许位图与 SVG。3.5 三种 mode 的行为差异browse默认frame.content.mode(browse)展示媒体库浏览界面uploadframe.content.mode(upload)直接展示上传标签页urlframe.setState(embed)切换到 embed 状态并若传入currentUrl/currentAlt通过setTimeout(..., 0)延迟写入url/alt属性。延迟原因在源码注释中有明确说明需要等 toolbar 区域初始化完成后再触发change:url的刷新回调。select分发时若state.get(id) embed则走onSelectUrl(url, alt)分支仅当 URL 非空否则把 selection 序列化后经normalize转换按multiple决定回传数组还是单个附件。3.6 测试印证src/hooks/tests/use-wp-media-frame.test.ts 用 mock frame 覆盖了关键行为打开时传入title、multiple、mediaTypes: [image]断言library.type恰好等于 9 个图片 MIME 的数组单选触发select/insert事件各回调一次多选回传附件数组mode: upload时 frame 的 content mode 为upload再次open()会先detachremove旧 frame组件卸载同样清理仅触发close不会触发清理避免 WP 生命周期竞态验证了 0.1.1 的修复策略。四、核心二getMediaAttachment与useWpMediaAttachment——按 ID 读取附件CHANGELOG 0.4.0 的 SeparategetMediaAttachmentfrom react hook 正是把附件读取逻辑从 hook 中抽离为可独立使用的命令式 API。4.1fetchAttachmentFromWP的读取策略src/get-media-attachment.ts 中的核心流程export async function fetchAttachmentFromWP( id: number ) { const model media().attachment( id ); const wpAttachment model.toJSON(); const isFetched url in wpAttachment; // 已加载过的模型带 url 字段 if ( isFetched ) { return normalize( wpAttachment ); // 命中模型内存缓存直接返回 } try { return normalize( await model.fetch() ); // 否则走 REST 拉取 } catch { return null; // 失败返回 null 而非抛错 } }关键判断是url是否已存在于模型 JSON 中WordPress 的 Backbone attachment 模型一旦被 fetch 过就会带url字段据此判断缓存命中避免重复请求。4.2 与elementor/query的缓存集成getMediaAttachment通过getQueryClient()获取全局 QueryClient用ensureQueryData以[wp-attachment, id]作为 queryKey 写入缓存。这样同一附件 id 的并发请求会被去重get-media-attachment.test.ts 中should deduplicate concurrent fetches用例验证attachment只被调用一次二次读取直接命中缓存不再触碰wp.mediashould return cached attachment without fetching wp.media again用例验证id为null时直接返回null不上发请求。4.3 Hook 封装src/hooks/use-wp-media-attachment.ts 只是useQuery的一层薄封装export default function useWpMediaAttachment( id: number | null ) { return useQuery( { queryKey: [ wp-attachment, id ], queryFn: () fetchAttachmentFromWP( id as number ), enabled: !! id, // id 为空时不发起请求 } ); }返回值即elementor/query的标准查询结果data、isLoading、isError等可直接用于 React 组件渲染。五、核心三normalize与Attachment类型——统一附件数据结构wp.media返回的附件 JSON 字段与包内定义的Attachment类型并不一致src/normalize.ts 负责转换export default function normalize( attachment: WpAttachmentJSON ): Attachment { const { filesizeInBytes, filesizeHumanReadable, author, authorName, ...rest } attachment; return { ...rest, filesize: { inBytes: filesizeInBytes, // 扁平字段 → 嵌套对象 humanReadable: filesizeHumanReadable, }, author: { id: parseInt( author ), // 字符串 id → number name: authorName, }, }; }归一化后的 Attachment 类型包含id、url、height、width、alt、filename、title、mime、type、subtype、uploadedTo以及嵌套的filesize: { inBytes, humanReadable }、author: { id, name }和sizes: Recordstring, { width, height, url }。所有选中附件与getMediaAttachment的返回值都经过该函数保证下游消费的是统一、可预测的结构。六、错误模型两个全局依赖的前置校验包对 WordPress 全局对象的依赖通过两个工厂函数显式校验src/media.ts检查window.wp?.media是否存在否则抛出WpMediaNotAvailableErrorcodewp_media_not_available错误消息明确指出需要在 dependencies 数组中包含media-modelshandle。src/wp-plupload-settings.ts检查window._wpPluploadSettings是否存在否则抛出WpPluploadSettingsNotAvailableErrorcodewp_plupload_settings_not_available。两个错误均通过elementor/utils的createError工厂创建见 src/errors.ts携带稳定错误码便于上层统一捕获与上报。src/tests/media.test.ts 验证了三种场景window.wp不存在时抛错、window.wp.media不存在时抛错、存在时原样返回wp.media。这提醒接入方该包只能在 WordPress 后台脚本环境中使用前端公共页面没有wp.media全局对象。七、实战示例在 Elementor 编辑器扩展中接入媒体选择综合以上 API一个典型的选择一张图片可选 URL 导入用法如下import { useWpMediaFrame, type Attachment } from elementor/wp-media; function ImagePicker( { value, onChange }: { value: number | null; onChange: ( attachment: Attachment ) void; } ) { const { open } useWpMediaFrame( { mediaTypes: [ image, svg ], // 允许位图与 SVG依赖 0.3.0 title: Select an image, multiple: false, selected: value, // 预选中当前值 allowUrlImport: true, // 允许粘贴图片 URL onSelect: ( attachment ) onChange( attachment ), onSelectUrl: ( url, alt ) onChange( { /* 以 url 构造的附件 */ } ), } ); return button onClick{ () open( { mode: browse } ) }Select Image/button; }接入时务必满足两个前置条件在你的脚本注册中把media-models加入 dependencies否则WpMediaNotAvailableError会被抛出包依赖 React 18 与elementor/query的 QueryClient 环境getMediaAttachment依赖全局 query client 做缓存。若要限制用户只能上传而不能浏览已有库可将open( { mode: upload } )若要允许直接粘贴外链图片则使用mode: url并配合currentUrl/currentAlt预填。八、小结从 CHANGELOG 反推包的能力边界把 CHANGELOG 与源码对照可以清晰还原elementor/wp-media的能力边界它做什么封装wp.media弹窗浏览/上传/URL 三种模式、按类型image/svg/video过滤媒体库与上传扩展名、返回归一化的Attachment结构、按 ID 读取附件并做查询缓存同时提供 React hook 与命令式两种调用形态。它不做什么不做服务端上传鉴权uploadTypeCaller只是给服务端一个标识、不渲染任何 UI弹窗完全由 WordPress 原生媒体库提供、不脱离 WordPress 后台运行强依赖wp.media与_wpPluploadSettings两个全局对象。对于在 Elementor 生态内开发编辑器扩展、需要与 WordPress 媒体库深度集成的开发者而言这个包把繁琐的 Backbone frame 生命周期、MIME 过滤、数据归一化全部封装完毕通过两个 hook 与一个函数即可获得完整、可测试、带缓存能力的媒体能力层。进一步阅读包 README、CHANGELOG、frame hook 测试、附件读取测试。【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Elementor `@elementor/wp-media` 包完全指南：WordPress 媒体库适配器的能力演进与源码剖析
Elementorelementor/wp-media包完全指南WordPress 媒体库适配器的能力演进与源码剖析【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor本指南以 Elementor 前端拖拽页面构建器仓库中的elementor/wp-media包路径 packages/packages/libs/wp-media为对象从它的 CHANGELOG.md 版本演进出发结合源码与测试系统讲解该包如何封装 WordPress 的wp.media函数、打开媒体弹窗、选择/上传图片、读取附件数据以及支持 SVG 上传、限制图片类型、URL 导入等能力的实现原理。读完本文你将掌握这个包从 0.1.0 到 0.6.1 每个版本能力的用法、底层调用链与约束条件并能在自己的 Elementor 编辑器扩展中正确接入它。一、包定位WordPresswp.media的前端适配层elementor/wp-media在仓库中位于packages/packages/libs/wp-media其 README.md 明确指出This package is an adapter for WordPresswp.mediafunction. It allows you to open the WordPress media modal, select or upload images from the media library, and get attachment data.它假设wp.media存在于全局作用域否则会抛出异常。因此使用方必须把media-modelshandle 加入自身脚本的 dependencies 数组确保在 WordPress 后台环境中加载了媒体库模型脚本。从 package.json 可以看到该包的发布形态名称elementor/wp-media描述 An adapter for WordPress media utils通过tsup构建同时输出dist/index.jsCommonJS、dist/index.mjsESM与dist/index.d.ts类型声明exports字段按import/require分别指向对应产物依赖elementor/query4.4.0与elementor/utils4.4.0peerDependency 为react^18.3.1发布包仅包含README.md、CHANGELOG.md、/dist与/src测试目录__tests__不随包发布。包的公开 API 极简见 src/index.tsexport type { Attachment } from ./types/attachment; export type { OpenOptions, MediaType } from ./hooks/use-wp-media-frame; export { default as useWpMediaAttachment } from ./hooks/use-wp-media-attachment; export { default as useWpMediaFrame } from ./hooks/use-wp-media-frame; export { getMediaAttachment } from ./get-media-attachment;对外总共暴露两个 React HookuseWpMediaFrame、useWpMediaAttachment、一个命令式函数getMediaAttachment以及若干类型。下面结合 CHANGELOG 的版本脉络逐一深入。二、CHANGELOG 版本演进图谱0.1.0 → 0.6.1CHANGELOG.md 记录了该包从诞生到当前包内 package.json 版本为 4.4.0CHANGELOG 则记录早期独立发版历程的全部功能变更。将各版本的核心变更整理如下版本类型核心变更对应能力0.1.0 (2024-08-14)Feature新增与 wp-media 交互的 utilsEDS-324包首次发布提供媒体交互基础能力0.1.1 (2024-08-14)Bug Fix关闭时清理cleanup on closeEDS-365修复媒体弹窗关闭后的资源泄漏0.1.2 (2024-08-20)—仅版本号升级无功能变更0.2.0MinorImageControl支持 inner props内部控件能力扩展0.2.1Patch修复 package.json 的exports字段升级elementor/query与elementor/utils包导出解析修正0.2.2Patch升级elementor/utils0.3.0依赖同步0.2.3Patch更新并锁定依赖版本依赖固化0.3.0Minor支持 SVG 上传4e5ea74MediaType引入svg0.4.0Minor将getMediaAttachment从 React hook 中分离af5fa42支持限制上传图片类型a2f5096命令式 API 与类型过滤0.4.1Patch升级elementor/utils0.3.1依赖同步0.4.2Patch升级elementor/utils0.4.0依赖同步0.5.0Minor新增 API client 与 hooks用于启用 unfiltered files 上传f6a4d4f非过滤文件上传能力0.6.0Minor新增 settings transformersb8a7725设置转换能力0.6.1Patch升级elementor/utils0.5.0依赖同步值得注意的是后续版本号虽然继续增长但包内 version 已并入 Elementor 主仓库的 monorepo 版本当前为 4.4.0CHANGELOG 中的 0.x 记录是该包独立发版时期的历史。这张表既是包的能力时间线也是本文随后逐项深入的主线。三、核心一useWpMediaFrame——打开并控制媒体弹窗useWpMediaFrame是包的主入口定义于 src/hooks/use-wp-media-frame.ts。它接收一个配置对象返回{ open }由调用方在用户交互时触发弹窗。3.1 配置项完整说明Hook 的Options类型如下带注释为源码未标注、由实现推断的默认行为type Options { mediaTypes: MediaType[]; // 允许的媒体类型image | svg | video title?: string; // 弹窗标题 allowUrlImport?: boolean; // 是否允许 URL 导入开启后使用 post 型 frame onSelectUrl?: ( url: string, alt?: string ) void; // URL 导入回调 } ( | { multiple: true; selected: Array number | null ; // 多选时预选中附件 id 数组 onSelect: ( val: Attachment[] ) void; // 多选回调返回附件数组 } | { multiple: false; selected: number | null; // 单选时预选中附件 id onSelect: ( val: Attachment ) void; // 单选回调返回单个附件 } );而每次调用open( openOptions )时还可传入OpenOptions覆盖打开时的行为export type OpenOptions { mode?: upload | browse | url; // 默认 browse currentUrl?: string; // mode 为 url 时预填的 URL currentAlt?: string; // mode 为 url 时预填的 alt 文本 };3.2 弹窗创建与生命周期createFrame是核心工厂函数它做了以下几件事调用media()( { title, multiple, library } )创建 framelibrary.type由getMimeTypes( mediaTypes )根据媒体类型映射为 MIME 数组见下文 3.4。allowUrlImport时改用frame: postWordPress 的 post frame 自带从 URL 插入面板。监听open事件设置上传参数uploadTypeCaller标记为elementor-wp-media-upload便于服务端识别来源、应用 mode、并预选已选附件。监听insert select事件统一走select函数分发结果。处理扩展名白名单见 3.3。生命周期清理策略非常明确不在 close 时销毁 frame而是在下次open()或组件卸载时统一清理。cleanupFrame依次调用frame.detach()与frame.remove()。这一设计避免了与 WordPress 内部媒体生命周期发生竞态race condition对应 CHANGELOG 0.1.1 的 cleanup on close [EDS-365] 修复——它把清理时机从 close 推迟到了更安全的节点。3.3 上传扩展名的临时接管与还原handleExtensions利用全局_wpPluploadSettings实现打开期间限制可上传类型、关闭后恢复默认ready时把_wpPluploadSettings.defaults.filters.mime_types替换为按mediaTypes计算出的扩展名列表close时恢复打开前保存的默认扩展名列表。这正是 CHANGELOG 0.4.0 中 support restricting uploaded image type (a2f5096) 的实现。读取全局设置的行为封装在 src/wp-plupload-settings.ts若window._wpPluploadSettings不存在即从未打开过 WP 上传器会抛出WpPluploadSettingsNotAvailableError错误提示明确要求先确保一个 wp media uploader 处于打开状态。3.4 媒体类型 → MIME / 扩展名映射源码中维护了两张静态映射表图片imageavif, bmp, gif, ico, jpe, jpeg, jpg, png, webpMIME 为对应的image/*。SVGsvg扩展名svgMIME 为image/svgxmlCHANGELOG 0.3.0 新增。视频video扩展名mp4, webm, ogg, mov, m4v, avi, wmv, mpg, mpeg, 3gp, 3g2MIME 为video/mp4, video/webm, video/ogg, video/quicktime, video/x-m4v, video/avi, video/x-ms-wmv, video/mpeg, video/3gpp, video/3gpp2。getMimeTypes用于限定媒体库浏览范围library.typegetExtensions用于生成上传时的扩展名白名单。二者都由mediaTypes.reduce(...)累加生成因此传入[image, svg]即可同时允许位图与 SVG。3.5 三种 mode 的行为差异browse默认frame.content.mode(browse)展示媒体库浏览界面uploadframe.content.mode(upload)直接展示上传标签页urlframe.setState(embed)切换到 embed 状态并若传入currentUrl/currentAlt通过setTimeout(..., 0)延迟写入url/alt属性。延迟原因在源码注释中有明确说明需要等 toolbar 区域初始化完成后再触发change:url的刷新回调。select分发时若state.get(id) embed则走onSelectUrl(url, alt)分支仅当 URL 非空否则把 selection 序列化后经normalize转换按multiple决定回传数组还是单个附件。3.6 测试印证src/hooks/tests/use-wp-media-frame.test.ts 用 mock frame 覆盖了关键行为打开时传入title、multiple、mediaTypes: [image]断言library.type恰好等于 9 个图片 MIME 的数组单选触发select/insert事件各回调一次多选回传附件数组mode: upload时 frame 的 content mode 为upload再次open()会先detachremove旧 frame组件卸载同样清理仅触发close不会触发清理避免 WP 生命周期竞态验证了 0.1.1 的修复策略。四、核心二getMediaAttachment与useWpMediaAttachment——按 ID 读取附件CHANGELOG 0.4.0 的 SeparategetMediaAttachmentfrom react hook 正是把附件读取逻辑从 hook 中抽离为可独立使用的命令式 API。4.1fetchAttachmentFromWP的读取策略src/get-media-attachment.ts 中的核心流程export async function fetchAttachmentFromWP( id: number ) { const model media().attachment( id ); const wpAttachment model.toJSON(); const isFetched url in wpAttachment; // 已加载过的模型带 url 字段 if ( isFetched ) { return normalize( wpAttachment ); // 命中模型内存缓存直接返回 } try { return normalize( await model.fetch() ); // 否则走 REST 拉取 } catch { return null; // 失败返回 null 而非抛错 } }关键判断是url是否已存在于模型 JSON 中WordPress 的 Backbone attachment 模型一旦被 fetch 过就会带url字段据此判断缓存命中避免重复请求。4.2 与elementor/query的缓存集成getMediaAttachment通过getQueryClient()获取全局 QueryClient用ensureQueryData以[wp-attachment, id]作为 queryKey 写入缓存。这样同一附件 id 的并发请求会被去重get-media-attachment.test.ts 中should deduplicate concurrent fetches用例验证attachment只被调用一次二次读取直接命中缓存不再触碰wp.mediashould return cached attachment without fetching wp.media again用例验证id为null时直接返回null不上发请求。4.3 Hook 封装src/hooks/use-wp-media-attachment.ts 只是useQuery的一层薄封装export default function useWpMediaAttachment( id: number | null ) { return useQuery( { queryKey: [ wp-attachment, id ], queryFn: () fetchAttachmentFromWP( id as number ), enabled: !! id, // id 为空时不发起请求 } ); }返回值即elementor/query的标准查询结果data、isLoading、isError等可直接用于 React 组件渲染。五、核心三normalize与Attachment类型——统一附件数据结构wp.media返回的附件 JSON 字段与包内定义的Attachment类型并不一致src/normalize.ts 负责转换export default function normalize( attachment: WpAttachmentJSON ): Attachment { const { filesizeInBytes, filesizeHumanReadable, author, authorName, ...rest } attachment; return { ...rest, filesize: { inBytes: filesizeInBytes, // 扁平字段 → 嵌套对象 humanReadable: filesizeHumanReadable, }, author: { id: parseInt( author ), // 字符串 id → number name: authorName, }, }; }归一化后的 Attachment 类型包含id、url、height、width、alt、filename、title、mime、type、subtype、uploadedTo以及嵌套的filesize: { inBytes, humanReadable }、author: { id, name }和sizes: Recordstring, { width, height, url }。所有选中附件与getMediaAttachment的返回值都经过该函数保证下游消费的是统一、可预测的结构。六、错误模型两个全局依赖的前置校验包对 WordPress 全局对象的依赖通过两个工厂函数显式校验src/media.ts检查window.wp?.media是否存在否则抛出WpMediaNotAvailableErrorcodewp_media_not_available错误消息明确指出需要在 dependencies 数组中包含media-modelshandle。src/wp-plupload-settings.ts检查window._wpPluploadSettings是否存在否则抛出WpPluploadSettingsNotAvailableErrorcodewp_plupload_settings_not_available。两个错误均通过elementor/utils的createError工厂创建见 src/errors.ts携带稳定错误码便于上层统一捕获与上报。src/tests/media.test.ts 验证了三种场景window.wp不存在时抛错、window.wp.media不存在时抛错、存在时原样返回wp.media。这提醒接入方该包只能在 WordPress 后台脚本环境中使用前端公共页面没有wp.media全局对象。七、实战示例在 Elementor 编辑器扩展中接入媒体选择综合以上 API一个典型的选择一张图片可选 URL 导入用法如下import { useWpMediaFrame, type Attachment } from elementor/wp-media; function ImagePicker( { value, onChange }: { value: number | null; onChange: ( attachment: Attachment ) void; } ) { const { open } useWpMediaFrame( { mediaTypes: [ image, svg ], // 允许位图与 SVG依赖 0.3.0 title: Select an image, multiple: false, selected: value, // 预选中当前值 allowUrlImport: true, // 允许粘贴图片 URL onSelect: ( attachment ) onChange( attachment ), onSelectUrl: ( url, alt ) onChange( { /* 以 url 构造的附件 */ } ), } ); return button onClick{ () open( { mode: browse } ) }Select Image/button; }接入时务必满足两个前置条件在你的脚本注册中把media-models加入 dependencies否则WpMediaNotAvailableError会被抛出包依赖 React 18 与elementor/query的 QueryClient 环境getMediaAttachment依赖全局 query client 做缓存。若要限制用户只能上传而不能浏览已有库可将open( { mode: upload } )若要允许直接粘贴外链图片则使用mode: url并配合currentUrl/currentAlt预填。八、小结从 CHANGELOG 反推包的能力边界把 CHANGELOG 与源码对照可以清晰还原elementor/wp-media的能力边界它做什么封装wp.media弹窗浏览/上传/URL 三种模式、按类型image/svg/video过滤媒体库与上传扩展名、返回归一化的Attachment结构、按 ID 读取附件并做查询缓存同时提供 React hook 与命令式两种调用形态。它不做什么不做服务端上传鉴权uploadTypeCaller只是给服务端一个标识、不渲染任何 UI弹窗完全由 WordPress 原生媒体库提供、不脱离 WordPress 后台运行强依赖wp.media与_wpPluploadSettings两个全局对象。对于在 Elementor 生态内开发编辑器扩展、需要与 WordPress 媒体库深度集成的开发者而言这个包把繁琐的 Backbone frame 生命周期、MIME 过滤、数据归一化全部封装完毕通过两个 hook 与一个函数即可获得完整、可测试、带缓存能力的媒体能力层。进一步阅读包 README、CHANGELOG、frame hook 测试、附件读取测试。【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考