Gutenberg FontFamilyControl 组件实战基于 typography.fontFamilies 预设的字体族选择器【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读FontFamilyControl是 Gutenberg 块编辑器wordpress/block-editor包提供的一个 React 组件它渲染一个下拉选择控件让用户在编辑器侧边栏或自定义块设置面板中挑选字体族。该组件的核心数据来源是全局样式Global Styles中的typography.fontFamilies预设并允许通过fontFamiliesprop 覆盖预设值。阅读完本文你将掌握该组件的完整 Props 契约、在自定义块与全局样式排版面板中的接入方式以及它在仓库源码中的真实实现与设置解析链路。实验性功能警告该组件当前仍处于实验阶段experimental。“实验性”意味着它是早期实现未来可能发生大幅度的破坏性变更在生产环境中使用时请关注版本升级日志。FontFamilyControl 是什么FontFamilyControl渲染一个用于选择字体族的用户界面用户可以从由typography.fontFamilies预设定义的一组预置字体族中选择其一。可选地你可以通过fontFamiliesprop 传入自定义字体族集合从而覆盖预置字体族。在仓库中该组件位于 packages/block-editor/src/components/font-family/index.jsx并从包入口 packages/block-editor/src/components/index.js 以实验性 API 形式导出export { default as __experimentalFontFamilyControl } from ./font-family;因此在业务代码中通常这样引入import { __experimentalFontFamilyControl as FontFamilyControl } from wordpress/block-editor;基本用法在自定义块Block的edit函数中配合useState使用即可实现一个受控的字体族选择器import { useState } from react; import { __experimentalFontFamilyControl as FontFamilyControl } from wordpress/block-editor; import { __ } from wordpress/i18n; // ... const MyFontFamilyControl () { const [ fontFamily, setFontFamily ] useState( ); return ( FontFamilyControl value{ fontFamily } onChange{ ( newFontFamily ) { setFontFamily( newFontFamily ); } } / ); }; // ... MyFontFamilyControl /核心要点value初始值为空字符串此时下拉框默认显示 “Default”默认选项onChange会在用户选中某个字体族后收到新的字体族值即对应的fontFamilyCSS 值当用户选择 “Default” 时onChange会被调用但不带任何参数见下文 Props 说明业务侧应根据该语义执行“重置”逻辑。Props 契约组件接受以下 PropsonChange必填接收新字体族值的回调函数。类型function必填是如果onChange被调用且未携带任何参数则应当重置该值——具体“重置”的语义由使用场景决定例如将字体族设为undefined或恢复为某个起始值。fontFamilies可选用户提供的字体族集合用于覆盖来自预设presets的预置字体族。类型Array必填否字体族以对象数组形式提供schema 如下属性描述类型fontFamily字体族用法与 CSS 中的取值一致stringname字体族的可选显示名称string例如const fontFamilies [ { fontFamily: Inter, sans-serif, name: Inter }, { fontFamily: -apple-system,system-ui,Segoe UI,Roboto,Oxygen-Sans,Ubuntu,Cantarell,Helvetica Neue,sans-serif, name: System Font, }, ];仓库中的 Storybook 示例 packages/block-editor/src/components/font-family/stories/index.story.jsx 展示了更贴近真实场景的数据结构——除了fontFamily与name外还可以携带slug以及fontFace字面量fontFamily描述 src字体文件地址等例如{ fontFace: [ { fontFamily: Inter, fontStretch: normal, fontStyle: normal, fontWeight: 200 900, src: [ file:./assets/fonts/inter/Inter-VariableFont_slnt,wght.ttf ], }, ], fontFamily: Inter, sans-serif, name: Inter, slug: inter, }value可选当前字体族的值。类型String必填否默认值其他 Props其余所有未列出的 Props 都会被透传spread给底层的CustomSelectControl实例例如label、className、size等均可按需覆盖。源码级实现剖析FontFamilyControl的实现非常精简完整逻辑集中在 packages/block-editor/src/components/font-family/index.jsx 一个文件中可拆解为以下四个步骤1. 读取全局设置中的预设字体族const [ blockLevelFontFamilies ] useSettings( typography.fontFamilies ); if ( ! fontFamilies ) { fontFamilies blockLevelFontFamilies; }组件通过useSettings( typography.fontFamilies )从块编辑上下文中读取设置。useSettings的实现见 packages/block-editor/src/components/use-settings/index.js它会先基于当前块的clientId在块实例层级链中向上查找设置找不到时再回退到块编辑器的全局设置。其底层委托给 store 的私有选择器getBlockSettingspackages/block-editor/src/store/get-block-settings.js后者会沿着块层级向上遍历并收集所有声明了__experimentalSettings块支持的祖先块设置。这也意味着主题或父级块在typography.fontFamilies中定义的预设会自动成为该下拉框的数据源。2. 空数据保护if ( ! fontFamilies || fontFamilies.length 0 ) { return null; }当没有任何预设字体族时组件直接渲染null——因此不会出现一个空的下拉框。3. 组装选项列表const options [ { key: , name: __( Default ), }, ...fontFamilies.map( ( { fontFamily, name } ) ( { key: fontFamily, name: name || fontFamily, style: { fontFamily }, } ) ), ];第一项固定为key: 、显示名 “Default”即“跟随默认/重置”选项每个预设字体族映射为一个选项key使用fontFamily的 CSS 值name优先取name字段、缺省时回退为fontFamily每个选项还附带style: { fontFamily }因此下拉列表中的每一项会以自身字体渲染让用户直观预览字体效果。4. 渲染 CustomSelectControlconst selectedValue options.find( ( option ) option.key value ) ?? ; return ( CustomSelectControl label{ __( Font ) } value{ selectedValue } onChange{ ( { selectedItem } ) onChange( selectedItem.key ) } options{ options } className{ clsx( block-editor-font-family-control, className ) } { ...props } / );底层实际是wordpress/components的CustomSelectControl默认 label 为 “Font”selectedValue根据传入的value在选项中查找对应项若未找到例如value不在预设中回退为选中项通过onChange( selectedItem.key )回传。特别地当选中 “Default” 项时selectedItem.key为即对应 README 中“无参数调用时表示重置”的语义约定在实现层面表现为回调空字符串自定义className会与内置的block-editor-font-family-control合并。在全局样式排版面板中的真实调用FontFamilyControl并非孤立组件它在编辑器内置的“排版Typography”全局样式面板中被实际使用位置在 packages/block-editor/src/components/global-styles/typography-panel.jsxFontFamilyControl fontFamilies{ fontFamilies } value{ fontFamily } onChange{ setFontFamily } /调用上下文要点只有当设置settings.typography.fontFamilies中存在至少一个字体族useHasFontFamilyControl会逐项检查各字体的长度见同文件第 112-115 行时该控件才会渲染它被包裹在InheritanceToolsPanelItem中支持“继承”语义与重置onDeselect{ resetFontFamily }面板通过useMemo将settings.typography.fontFamilies处理成fontFamilies数据含fontFamily与name直接喂给组件。这为自定义块接入提供了范本将组件嵌入你自己的InspectorControls或面板并维护好value/onChange即可。与 theme.json 预设的关联typography.fontFamilies预设通常由主题的theme.json定义。在根目录的 lib/theme.json 中即可找到 Gutenberg 插件自身使用的字体预设配置。数据结构与组件期望的 schema 完全对应typography: { fontFamilies: [ { fontFamily: var(--wp--preset--font-family--system-font), name: 系统字体, slug: system-font } ] }这意味着主题开发者只需在theme.json的settings.typography.fontFamilies中声明字体族fontFamily、name、slug可选fontFaceFontFamilyControl便会自动把这些字体呈现为可选项无需在组件层重复声明——这正是“预设优先、prop 覆盖”设计的意义所在。总结与注意事项接入方式以__experimentalFontFamilyControl命名从wordpress/block-editor导出作为受控组件使用必填onChange可选value与fontFamilies数据流未传fontFamilies时自动读取typography.fontFamilies设置块级覆盖全局回退到编辑器设置为空时渲染null选项语义内置 “Default” 项key 为选中它即代表“重置”onChange回调其余选项 key 为字体族的 CSS 值并以name缺省回退fontFamily为显示名且每项按自身字体族渲染预览透传机制其余 props 直接透传给底层CustomSelectControl可进一步定制 label、className 等实验性风险组件仍为实验性 API未来版本可能调整 Props 或导出命名例如当前实现已移除__next40pxDefaultSize迁移 prop该 prop 自 WordPress 7.1 起已默认生效代码中标记为 deprecated升级依赖时请留意变更日志。仓库内可供进一步研读的相关文件组件实现组件 READMEStorybook 示例包导出入口设置读取 Hook useSettings设置解析选择器 getBlockSettings全局样式排版面板中的调用Gutenberg 插件自身的字体预设配置【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考