Gutenberg core/video 视频块源码级指南：Attributes 体系、Hybrid 渲染与文本轨道

Gutenberg core/video 视频块源码级指南Attributes 体系、Hybrid 渲染与文本轨道【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读core/video是 GutenbergWordPress 块编辑器中负责视频内容的核心媒体块允许用户从媒体库嵌入视频或上传新文件。本文以 packages/block-library/src/video/README.md 为主体骨架结合该目录下block.json、edit.jsx、save.jsx、index.php等源码实现系统讲解视频块的全部 13 个属性、支持的编辑器能力anchor/align/spacing/interactivity、Hybrid 混合渲染机制、GIF 变体以及字幕/说明等文本轨道tracks的完整工作方式。读完本文你将能基于core/video的既有设计深入理解并二次开发自定义视频块。一、块概览core/video在 Gutenberg 中的定位根据自动生成的块 API 文档core/video的核心元信息如下项目值块名称Namecore/video类别Categorymedia媒体API 版本3块类型Hybrid混合块静态保存static save 服务端增强server enhancements关键词KeywordsmovieAPI Version 3块遵循 block.json 元数据规范$schema指向https://schemas.wp.org/trunk/block.json见 block.json使用apiVersion: 3与register_block_type_from_metadata注册。Hybrid 块这是理解视频块的关键。它在编辑器中以 React 组件edit.jsx编辑前端保存为静态 HTML 标记save.jsx同时在渲染阶段由 PHP 服务端index.php中的render_block_core_video对输出进行增强——例如根据附件元数据补充width/height与aspect-ratio样式。这意味着视频块不依赖服务端动态渲染才能显示静态标记在无 PHP 处理时也能正常播放。块本身在 index.js 中通过initBlock({ name, metadata, settings })完成注册settings中定义了图标、示例一段中央公园画眉鸟歌声的 webm 视频、transforms、variations、deprecated、edit与save。二、Attributes 完整解析13 个属性逐一拆解2.1 属性总表继承自官方文档所有属性均通过 block.json 的attributes字段定义。下表为完整清单AttributeTypeDefaultDescriptionautoplayboolean—Source:attribute。Selector:video。HTML attr:autoplaycaptionrich-text—Source:rich-text。Selector:figcaption。Role:contentcontrolsbooleantrueSource:attribute。Selector:video。HTML attr:controlsidnumber—Role:content媒体库附件 IDloopboolean—Source:attribute。Selector:video。HTML attr:loopmutedboolean—Source:attribute。Selector:video。HTML attr:mutedposterstring—Source:attribute。Selector:video。HTML attr:poster封面图 URLpreloadstringmetadataSource:attribute。Selector:video。HTML attr:preloadblobstring—Role:local临时 blob URL仅存在于编辑会话srcstring—Source:attribute。Selector:video。HTML attr:src。Role:contentwidthnumber—视频显示宽度无 source 映射纯存储值heightnumber—视频显示高度无 source 映射纯存储值playsInlineboolean—Source:attribute。Selector:video。HTML attr:playsinlinetracksarray[]Role:contentWebVTT 文本轨道数组注原文档表格中部分链接指向 block-attributes 文档本文以 block.json 的实际 JSON 定义为准进行讲解。2.2 从源码看属性分类三种取值来源将block.json中的定义归类属性通过三种机制与保存的 HTML 绑定① attribute source从 HTML 属性取值——autoplay、controls、loop、muted、poster、preload、src、playsInline。它们的解析路径完全一致muted: { type: boolean, source: attribute, selector: video, attribute: muted }即编辑器会从video元素上读取/写入对应 HTML 属性autoplay、controls、loop、muted、poster、preload、src、playsinline这些属性在保存时被序列化进静态标记。② rich-text source富文本内容——captioncaption: { type: rich-text, source: rich-text, selector: figcaption, role: content }caption对应figcaption元素内的富文本被标记为role: content意味着它是块内容的组成部分参与内容检查、模板锁定等逻辑。③ role 驱动的本地/内容属性idnumberRole:content媒体库附件的数字 ID保存时不直接映射为 HTML 属性而是供服务端渲染与媒体替换流程使用。blobstringRole:local本地临时对象 URL。当用户拖拽/上传本地文件时浏览器生成blob:开头的临时地址编辑器用Spinner展示上传中的转圈状态待上传完成后再替换为正式src。tracksarrayRole:content默认[]WebVTT 文本轨道列表保存在内容中详见第六节。width/heightnumber纯存储的尺寸数值没有 source 映射由编辑器的尺寸处理逻辑写入。2.3 默认值设计要点三个属性带有默认值其余为可选controls默认true常规视频默认显示播放控件符合大多数使用场景GIF 变体会显式覆盖为false。preload默认metadata仅预加载元数据而非整个视频兼顾性能与首屏体验。tracks默认[]空轨道数组。三、Supports视频块支持的编辑器能力原文档列出的supports配置同样定义在 block.jsonSupport配置说明anchortrue允许为块设置 HTML 锚点 ID便于站内跳转aligntrue支持宽对齐、全宽等对齐方式spacingmargin: true,padding: true支持外边距与内边距控制__experimentalDefaultControls将两者的默认控件关闭interactivityclientNavigation: true启用客户端导航interactivity API 支持使视频块在无刷新页面导航场景下正常工作此外block.json末尾还声明了样式句柄editorStyle: wp-block-video-editor, style: wp-block-video前端与编辑器样式分别由 style.scss 与 editor.scss 提供另有 theme.scss 处理主题化外观。四、Block Markup 与 Hybrid 混合渲染机制4.1 保存的静态标记结构原文档给出的core/video保存标记范例如下block comment 形式!-- wp:core/video -- figure classwp-block-video video controls srcdata:video/mp4;base64,AAAAH…/video figcaption classwp-element-captionMy video/figcaption /figure !-- /wp:core/video --示例中src使用了一段 base64 编码的极短视频数据仅为演示属性结构实际发布内容会使用媒体库的正式 URL。标记结构包含三层figure classwp-block-video——由useBlockProps.save()生成的根容器自动带上wp-block-video类名与对齐等类名video——承载src、controls、poster、preload、width、height、autoplay、loop、muted、playsinline等媒体属性figcaption classwp-element-caption——字幕/说明文本。wp-element-caption类名来自__experimentalGetElementClassName(caption)是 #41140 PR 引入的全局样式 caption 元素支持见 deprecated.jsx 中的注释。4.2 save.jsx静态保存逻辑源码剖析save.jsx 是 Hybrid 块的“静态”半边关键实现细节export default function save( { attributes } ) { const { autoplay, caption, controls, loop, muted, poster, preload, src, playsInline, tracks, width, height } attributes; // 显式非 auto宽高比避免 GIF 转视频时前端出现瞬时布局抖动 const aspectRatio width height ? ${ width } / ${ height } : undefined; return ( figure { ...useBlockProps.save() } { src ( video autoPlay{ autoplay } controls{ controls } loop{ loop } muted{ muted } poster{ poster } preload{ preload ! metadata ? preload : undefined } src{ src } playsInline{ playsInline } width{ width } height{ height } style{ aspectRatio ? { aspectRatio } : undefined } Tracks tracks{ tracks } / /video ) } { ! RichText.isEmpty( caption ) ( RichText.Content className{ __experimentalGetElementClassName( caption ) } tagNamefigcaption value{ caption } / ) } /figure ); }值得注意的工程细节src为空则不渲染video占位状态下仅保留figure容器。preload的默认值省略preload ! metadata ? preload : undefined——默认值metadata不写入标记保持输出干净。aspect-ratio 样式这是 6.9.0 起引入的优化。仅设置width/height属性时CSS 计算出的aspect-ratio: auto W/H在加载期间并不可靠Chrome 会先算出数万像素的瞬时高度造成 GIF 转视频切换时的“图像闪烁”与布局偏移因此在编辑器与保存端都显式输出styleaspect-ratio: W / H;详见 save.jsx 与 edit.jsx 的注释。4.3 index.php服务端增强Hybrid 的“动态”半边lib 侧服务端文件 中的render_block_core_video()是服务端增强的入口职责是从附件元数据补全宽高与宽高比执行一系列防御性校验内容中无video标签则直接返回原内容stripos大小写不敏感id属性缺失、非正整数或对应文章类型不是attachment则放弃增强调用wp_get_attachment_metadata()取附件元数据若width/height缺失或非正整数则放弃用WP_HTML_Tag_Processor定位video标签写入width/height属性计算并写入styleaspect-ratio: W / H;前置追加到原有 style 之前。PHP 注释中解释了为何不能直接用attr()的 CSS 规则aspect-ratio: attr(width type(number)) / attr(height type(number));目前仅 Chromium 实现CSSWG issue #7524因此采用服务端写内联样式的方式保证跨浏览器一致。块的 PHP 注册通过register_block_type_from_metadata(__DIR__ . /video, [render_callback render_block_core_video])完成挂在init钩子上自 WordPress 6.9.0 起生效。五、编辑器行为深度剖析edit.jsx 与设置面板5.1 三种媒体来源的完整流程edit.jsx 定义了编辑体验围绕onSelectVideo与onSelectURL两个核心回调展开① 上传 / 媒体库选择onSelectVideo无有效媒体时清空全部相关属性src、id、poster、caption、blob若 URL 是blob:临时地址isBlobURL仅设置temporaryURL并显示Spinner实际上传由useUploadMediaFromBlobURLHook 完成限定allowedTypes: [video]上传成功后再触发onSelectVideo正式媒体则写入src、id、poster封面取media.image?.src若与图标相同则置空、caption。② 直接输入 URLonSelectURL用prependHTTPS补齐协议头调用createUpgradedEmbedBlock检查该 URL 是否可升级为嵌入块Embed 块若是则调用onReplace直接替换为嵌入块否则作为普通视频 URL 写入src。③ 占位状态当src与temporaryURL均为空时渲染MediaPlaceholderacceptvideo/*、allowedTypes{[video]}提示语为 Drag and drop a video, upload, or choose from your library.选中状态下工具栏BlockControls提供Text tracks文本轨道编辑见第六节与MediaReplaceFlow替换媒体支持选择/上传/URL/重置四种操作varianttoolbar。5.2 设置面板InspectorControls常规视频非 GIF 变体的侧栏设置面板基于ToolsPanel构建resetAll将属性恢复为autoplay: false、controls: true、loop: false、muted: false、playsInline: false、preload: metadata、poster: undefined。面板内各控件见 edit-common-settings.jsx及其联动逻辑控件默认显示关键行为Autoplay是开启自动播放时强制联动muted: true与playsInline: true后者为支持 iOS 内联播放关闭时同步muted: false帮助文案提示“自动播放可能对部分用户造成可用性问题”Loop是切换loopMuted是当autoplay开启时控件被禁用并提示 Muted because of Autoplay.Playback controls是切换controlsPlay inline是autoplay开启时禁用并提示 Play inline enabled because of Autoplay.否则解释在移动浏览器上网页内播放、不进入全屏Preload是SelectControl选项为autoAuto/metadataMetadata/noneNone仅当值非metadata时视为“有值”此外面板还包含PosterImage封面图设置将选择的封面 URL 写入poster。编辑器内播放体验编辑态video仅应用controls与poster未选中时设置inerttrue阻止交互。aspectRatio逻辑与 save 端一致保证编辑与前端行为统一。useEffect在poster变化时调用videoPlayer.current.load()刷新预览。六、GIF 变体animated GIF 的自动视频化core/video通过 variations.js 定义了两种变体export const isGifVariation ( { controls, loop, autoplay, muted, playsInline } {} ) ! controls !! loop !! autoplay !! muted !! playsInline;video 变体常规视频attributes: { controls: true }isActive为!isGifVariation(...)不直接出现在插入器中scope: [block, transform]用于标识普通视频或把 GIF 变体切回常规视频。gif 变体描述“像动图一样自动播放的静音循环视频”属性组合为controls: false, loop: true, autoplay: true, muted: true, playsInline: true关键词含animated、gif。工作机制用户在编辑器中上传的 animated GIF 会被转换为视频参考 docs/how-to-guides/client-side-media.md 所述的客户端媒体处理管线并以gif变体属性呈现从而在行为上完全还原 GIF 的动图效果。编辑态下edit.jsx检测isGifVariation后对预览video应用autoPlay/loop/muted/playsInline浏览器允许程序化播放静音视频并在源/封面变化后主动调用videoPlayer.current?.play()隐藏 InspectorControls 中的常规设置面板GIF 变体无需用户干预。七、Transforms三种来源向视频块的转换transforms.js 定义了从三类输入转换为core/video的规则文件files单个video/*类型文件被拖入编辑器时通过createBlobURL(file)生成临时 blob 地址存入blob属性实际上传交由块的挂载逻辑完成。短代码shortcode兼容传统[video]短代码映射src依次回退src/mp4/m4v/webm/ogv/flv命名参数、poster、loop、autoplay、preload。原始 HTMLraw当粘贴内容为pvideo …/video/p结构时提取autoplay、controls、loop、muted、preload、playsinline、poster、src若src是 blob URL 则转入blob属性。八、文本轨道Tracks字幕、说明、章节的完整编辑器支持tracks属性配合 tracks.jsx 与 tracks-editor.jsx 实现 WebVTT 文本轨道的添加与管理是视频块在无障碍a11y与多语言场景下的核心能力。保存端Tracks组件将每个轨道对象渲染为track子元素key取id ?? src保留除id外的全部属性export default function Tracks( { tracks [] } ) { return tracks.map( ( track ) { const { id, ...trackAttrs } track; return track key{ id ?? trackAttrs.src } { ...trackAttrs } /; } ); }编辑端TracksEditor通过工具栏 “Text tracks” 按钮打开 Dropdown添加来源媒体库选择MediaUploadallowedTypes: [text/vtt]支持多选或本地上传FormFileUploadaccept.vtt,text/vtt。已存在的轨道按id复用保留用户配置的元数据。轨道默认结构{ src: , label: , srcLang: en, kind: subtitles, default: false }其中kind可选subtitles字幕/captions说明/descriptions描述/chapters章节/metadata元数据。编辑单条轨道可修改 Label标题、Source language语言标签如en、fr、Kind、是否设为默认轨道default移除轨道与 “Apply” 确认。系统会保证同时只存在一个默认轨道allowSettingDefault逻辑。九、向后兼容deprecated 版本deprecated.jsx 中保留了一个v1历史版本用于自动迁移旧内容。其与当前 save 的差异正是wp-element-caption类名的引入#41140 为全局样式 caption 元素增加了该类名见文件头部注释。旧版本保存的figcaption不带该类名因此需要 deprecation 机制在用户重新保存时升级标记。十、实操速查常见使用方式与验证路径在编辑器中使用在块插入器搜索 “Video”或 “movie” 关键词→ 拖拽/上传视频、从媒体库选择或直接粘贴视频 URL可识别可升级为嵌入块的链接→ 在侧栏调整 Autoplay/Loop/Muted/Playback controls/Play inline/Preload 与封面图 → 通过工具栏 “Text tracks” 添加字幕与说明。手动编写块标记可直接粘贴到代码编辑器或作为模板参考!-- wp:core/video {id:123,loop:true,muted:true} -- figure classwp-block-videovideo srchttps://example.com/video.mp4 loop muted width1280 height720 styleaspect-ratio: 1280 / 720;/videofigcaption classwp-element-caption产品演示视频/figcaption/figure !-- /wp:core/video --深入验证的源码路径属性与支持定义block.json编辑组件edit.jsx、edit-common-settings.jsx保存组件save.jsx、deprecated.jsx服务端渲染index.php变体与转换variations.js、transforms.js文本轨道tracks.jsx、tracks-editor.jsx变体测试test/variations.js面向二次开发者的要点若需基于core/video构建自定义视频块应保持attributes的 source/role 分层设计attribute 直出、content 参与序列化、local 仅存临时态、在save端输出显式aspect-ratio以规避加载抖动并复用Tracks/TracksEditor以低成本获得无障碍字幕能力。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考