Gutenberg wordpress/components Guide 组件在模态框中实现分步用户指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergGuide是wordpress/components包中用于渲染用户指南user guide的 React 组件它以模态框Modal的形式承载若干页内容用户可以逐页翻阅点击最后一页的 Finish 按钮或关闭模态框时即完成整个指南。本文基于仓库中 Guide 组件文档 与完整源码实现讲清它的 API、行为边界与可访问性设计帮助你在 WordPress 插件、块编辑器扩展或仪表盘工具中快速搭建可交互的分步引导流程。组件定位与导出方式Guide从wordpress/components包的入口统一导出插件代码中直接import { Guide } from wordpress/components即可使用。导出声明位于 包入口文件export { default as Guide } from ./guide;组件源文件全部集中在 packages/components/src/guide 目录下结构清晰文件职责index.tsx主组件状态管理、按钮布局、键盘导航types.tsGuideProps、Page、PageControlProps类型定义page-control.tsx页码圆点导航控件page.tsx已废弃的GuidePage组件icons.tsx圆点导航用的PageControlIconSVGstyle.scss全部样式规则test/index.jsdom.test.tsx行为测试用例从源码结构看Guide完全构建在对Modal与Button两个基础组件的复用之上见 index.tsx 的 import 语句因此它继承了 Modal 的焦点圈闭、Esc 关闭、遮罩层等全部能力自身只负责翻页这一层逻辑。完整使用示例以下示例完整继承自官方 README用useState控制指南的显隐pages数组描述每一页其中第二页额外携带一张image展示操作截图。function MyTutorial() { const [ isOpen, setIsOpen ] useState( true ); if ( ! isOpen ) { return null; } return ( Guide onFinish{ () setIsOpen( false ) } pages{ [ { content: pWelcome to the ACME Store!/p, }, { image: img srchttps://acmestore.com/add-to-cart.png /, content: ( p Click iAdd to Cart/i to buy a product. /p ), }, ] } / ); }这个示例体现了典型的生命周期管理方式父组件持有isOpen状态onFinish回调将其置为false组件随即从渲染树中卸载。指南的完成只由两条路径触发——关闭模态框Esc、点击关闭按钮或点击最后一页的 Finish 按钮——两条路径最终都会调用onFinish因此父组件无需区分用户以何种方式结束。Props 完整参考Guide接受以下 props与 types.ts 中的 GuideProps 一一对应className类型string非必填作用附加到模态框根节点的自定义类名。在 源码 中通过clsx( components-guide, className )与组件内部类名合并可放心用于覆盖定位或主题定制。contentLabel类型string必填作用作为模态框的无障碍标签accessibility label。由于Guide内部渲染的是带roledialog的模态框屏幕阅读器需要一个可读名称来标识对话框因此该属性被标记为必填。finishButtonText类型string非必填默认值Finish作用自定义最后一页上 Finish 按钮的文案。源码中通过__( Finish )提供默认值意味着默认文案已经过了 i18n 翻译函数处理如果你传入自定义文案应自行对传入值做国际化。nextButtonText类型string非必填默认值Next作用自定义每一页上的 Next 按钮文案最后一页除外最后一页显示的是 Finish。previousButtonText类型string非必填默认值Previous作用自定义除第一页外各页上的 Previous 按钮文案。onFinish类型( event?: KeyboardEvent HTMLDivElement | SyntheticEvent ) void必填作用指南结束时回调。该类型直接复用自ModalProps[onRequestClose]见 types.ts事件参数可能是键盘事件如按 Esc 时或合成事件如点击关闭按钮时因此参数声明为可选——回调实现中通常并不依赖事件对象本身。pages类型{ content: ReactNode; image?: ReactNode }[]非必填默认值[]作用描述指南每一页的对象数组。每个对象必须包含content属性可选包含image属性。渲染时image位于页面内容上方index.tsx 中的渲染顺序div classNamecomponents-guide__page { pages[ currentPage ].image } {/* 图片在上 */} { pages.length 1 PageControl ... / } {/* 多页时显示页码圆点 */} { pages[ currentPage ].content } {/* 内容在下 */} /divPage类型定义位于 types.ts其中image字段注释明确写着 Image displayed above the page content与上述渲染顺序一致。源码深度解析分页状态与导航逻辑单状态驱动的翻页模型Guide的全部翻页逻辑只依赖一个 state——当前页索引const [ currentPage, setCurrentPage ] useState( 0 ); const canGoBack currentPage 0; const canGoForward currentPage pages.length - 1; const goBack () { if ( canGoBack ) { setCurrentPage( currentPage - 1 ); } }; const goForward () { if ( canGoForward ) { setCurrentPage( currentPage 1 ); } };见 index.tsx由此可推导出三个按钮的条件渲染规则Previous仅当canGoBack即不在第一页时渲染varianttertiary绝对定位在页脚左侧Next仅当canGoForward即不在最后一页时渲染variantprimary绝对定位在页脚右侧Finish仅当! canGoForward即最后一页时渲染点击后直接调用onFinish。页脚按钮采用position: absoluteleft/right: $grid-unit-30的定位方式见 style.scss使 Previous 与 Next/Finish 始终分居左右两端。空指南与单页指南的边界行为两个值得注意的边界行为均在源码与测试中得到印证pages为空时渲染nullindex.tsx 中if ( pages.length 0 ) { return null; }即默认值[]不会弹出任何模态框调用方可安全地用条件数据生成 pages 数组而不必额外判空。isDismissible随页数变化模态框的isDismissible属性被设置为pages.length 1index.tsx。可以推断其设计意图是多页指南允许用户随时中途退出而单页指南本质上只是一段说明则不允许直接关闭引导用户点击 Finish 来显式结束流程。键盘导航方向键翻页Modal的onKeyDown回调实现了左右方向键翻页onKeyDown{ ( event ) { if ( event.code ArrowLeft ) { goBack(); // Do not scroll the modals contents. event.preventDefault(); } else if ( event.code ArrowRight ) { goForward(); // Do not scroll the modals contents. event.preventDefault(); } } }见 index.tsx两个细节goBack/goForward内部已有边界检查所以方向键在首尾页按下是无害的空操作event.preventDefault()用于阻止方向键滚动模态框内部内容保证翻页的视觉体验稳定。测试用例 allows navigating through the pages with the left and right arrows 精确验证了这一行为包括在边界页反复按方向键时页面索引保持不变。焦点管理翻页即重新聚焦每次currentPage变化后组件将焦点重新放置到.components-guide框体上useEffect( () { // Place focus at the top of the guide on mount and when the page changes. const frame ref.current?.querySelector( .components-guide ); if ( frame instanceof HTMLElement ) { frame.focus(); } }, [ currentPage ] );见 index.tsx这是模态框场景下关键的无障碍实践——翻页后 DOM 内容整体替换若焦点落在已卸载的按钮上键盘用户就会迷路。依赖数组[ currentPage ]同时覆盖了首次挂载与后续翻页两种时机。页码圆点导航PageControl 的实现当pages.length 1时内容区会渲染一个PageControl圆点导航index.tsx允许用户点击任意圆点直接跳转到对应页而不必逐页翻。其实现要点见 page-control.tsx列表结构外层是ul aria-labelGuide controls每个圆点是一个sizesmall的Button内部渲染 PageControlIcon——一个 8×8 的实心圆 SVG无障碍标记当前页的li携带aria-currentstep符合 WAI-ARIA 对步骤指示器的规范源码注释中明确引用了该规范每个按钮的aria-label由sprintf( __( Page %1$d of %2$d ), page 1, numberOfPages )生成即第 n 页共 m 页测试中正是用name: /page \d of \d/i这类模式定位按钮的当前页高亮样式规则li[aria-currentstep] .components-button { color: $components-color-accent; }style.scss让当前页圆点变为主题强调色而非默认灰色$gray-200。测试用例 renders a button for each page 与 sets the current page when a button is clicked 分别验证了页数与圆点数一致和点击圆点即切换当前页含回跳两个行为。已废弃 APIchildren 与 GuidePage在wordpress/components5.5 之前指南页面以 React children 的形式传入并配有一个包装用的GuidePage组件。现在这两者均已被废弃children 方式index.tsx 中若检测到children非空会通过wordpress/deprecated打印Passing children to Guide的警告since: 5.5替代方案为pagesprop并做向后兼容转换——把每个 child 包装成{ content: child }对象再拼成 pages 数组GuidePage组件page.tsx 中每次挂载都会调用deprecated( GuidePage, { since: 5.5, alternative: thepagesprop in Guide } )其渲染体只剩div { ...props } /。从源码结构看这些兼容代码的存在意味着旧版插件不会直接报错但会在控制台留下弃用提示——新代码应一律使用pagesprop。样式结构一览style.scss 定义了组件的全部视觉规则关键点容器尺寸.components-modal__frame.components-guide设定min-width: 312px; max-height: 575px无 border在break-small断点以上宽度固定为 600px头部.components-modal__header去除下边框与内边距position: sticky保持关闭按钮常驻关闭按钮本身被重置为左上角对齐页脚.components-guide__footer是按钮的定位参照系position: relativeheight: $button-size三个导航按钮通过绝对定位分居左右$grid-unit-30即 30px 边距内容区.components-guide__page以 flex 纵向布局并垂直居中小屏下设置min-height: 300px与图片高度变量对齐。测试验证的行为清单测试文件 完整覆盖了组件的行为契约可作为 API 的权威参照无 pages 时不渲染 dialogrenders nothing when there are no pages一次只渲染一页其他页内容不存在于 DOMrenders one page at a time第一页隐藏 Previous、显示 Next、无 Finish最后一页反向两条按钮态测试单页指南不渲染页码圆点列表点击 Finish 触发onFinish按 Escape 触发onFinish验证了模态框关闭路径也走同一回调。小结Guide是一个职责单一、边界清晰的引导组件pages数组描述内容、onFinish统一收口结束逻辑、contentLabel保证对话框可访问性三个按钮文案 props 支持本地化定制。从源码实现看它在状态管理单一currentPage索引、键盘导航方向键 preventDefault、焦点管理翻页后重新聚焦与 ARIA 标注aria-currentstep、第 n 页共 m 页 标签上都做了细致的无障碍处理同时通过deprecated机制平滑迁移了 5.5 之前的children/GuidePage旧 API。在构建 WordPress 插件引导、编辑器新手教程或功能巡览时按 README 示例 组装pages数据即可直接使用。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gutenberg @wordpress/components Guide 组件：在模态框中实现分步用户指南
Gutenberg wordpress/components Guide 组件在模态框中实现分步用户指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergGuide是wordpress/components包中用于渲染用户指南user guide的 React 组件它以模态框Modal的形式承载若干页内容用户可以逐页翻阅点击最后一页的 Finish 按钮或关闭模态框时即完成整个指南。本文基于仓库中 Guide 组件文档 与完整源码实现讲清它的 API、行为边界与可访问性设计帮助你在 WordPress 插件、块编辑器扩展或仪表盘工具中快速搭建可交互的分步引导流程。组件定位与导出方式Guide从wordpress/components包的入口统一导出插件代码中直接import { Guide } from wordpress/components即可使用。导出声明位于 包入口文件export { default as Guide } from ./guide;组件源文件全部集中在 packages/components/src/guide 目录下结构清晰文件职责index.tsx主组件状态管理、按钮布局、键盘导航types.tsGuideProps、Page、PageControlProps类型定义page-control.tsx页码圆点导航控件page.tsx已废弃的GuidePage组件icons.tsx圆点导航用的PageControlIconSVGstyle.scss全部样式规则test/index.jsdom.test.tsx行为测试用例从源码结构看Guide完全构建在对Modal与Button两个基础组件的复用之上见 index.tsx 的 import 语句因此它继承了 Modal 的焦点圈闭、Esc 关闭、遮罩层等全部能力自身只负责翻页这一层逻辑。完整使用示例以下示例完整继承自官方 README用useState控制指南的显隐pages数组描述每一页其中第二页额外携带一张image展示操作截图。function MyTutorial() { const [ isOpen, setIsOpen ] useState( true ); if ( ! isOpen ) { return null; } return ( Guide onFinish{ () setIsOpen( false ) } pages{ [ { content: pWelcome to the ACME Store!/p, }, { image: img srchttps://acmestore.com/add-to-cart.png /, content: ( p Click iAdd to Cart/i to buy a product. /p ), }, ] } / ); }这个示例体现了典型的生命周期管理方式父组件持有isOpen状态onFinish回调将其置为false组件随即从渲染树中卸载。指南的完成只由两条路径触发——关闭模态框Esc、点击关闭按钮或点击最后一页的 Finish 按钮——两条路径最终都会调用onFinish因此父组件无需区分用户以何种方式结束。Props 完整参考Guide接受以下 props与 types.ts 中的 GuideProps 一一对应className类型string非必填作用附加到模态框根节点的自定义类名。在 源码 中通过clsx( components-guide, className )与组件内部类名合并可放心用于覆盖定位或主题定制。contentLabel类型string必填作用作为模态框的无障碍标签accessibility label。由于Guide内部渲染的是带roledialog的模态框屏幕阅读器需要一个可读名称来标识对话框因此该属性被标记为必填。finishButtonText类型string非必填默认值Finish作用自定义最后一页上 Finish 按钮的文案。源码中通过__( Finish )提供默认值意味着默认文案已经过了 i18n 翻译函数处理如果你传入自定义文案应自行对传入值做国际化。nextButtonText类型string非必填默认值Next作用自定义每一页上的 Next 按钮文案最后一页除外最后一页显示的是 Finish。previousButtonText类型string非必填默认值Previous作用自定义除第一页外各页上的 Previous 按钮文案。onFinish类型( event?: KeyboardEvent HTMLDivElement | SyntheticEvent ) void必填作用指南结束时回调。该类型直接复用自ModalProps[onRequestClose]见 types.ts事件参数可能是键盘事件如按 Esc 时或合成事件如点击关闭按钮时因此参数声明为可选——回调实现中通常并不依赖事件对象本身。pages类型{ content: ReactNode; image?: ReactNode }[]非必填默认值[]作用描述指南每一页的对象数组。每个对象必须包含content属性可选包含image属性。渲染时image位于页面内容上方index.tsx 中的渲染顺序div classNamecomponents-guide__page { pages[ currentPage ].image } {/* 图片在上 */} { pages.length 1 PageControl ... / } {/* 多页时显示页码圆点 */} { pages[ currentPage ].content } {/* 内容在下 */} /divPage类型定义位于 types.ts其中image字段注释明确写着 Image displayed above the page content与上述渲染顺序一致。源码深度解析分页状态与导航逻辑单状态驱动的翻页模型Guide的全部翻页逻辑只依赖一个 state——当前页索引const [ currentPage, setCurrentPage ] useState( 0 ); const canGoBack currentPage 0; const canGoForward currentPage pages.length - 1; const goBack () { if ( canGoBack ) { setCurrentPage( currentPage - 1 ); } }; const goForward () { if ( canGoForward ) { setCurrentPage( currentPage 1 ); } };见 index.tsx由此可推导出三个按钮的条件渲染规则Previous仅当canGoBack即不在第一页时渲染varianttertiary绝对定位在页脚左侧Next仅当canGoForward即不在最后一页时渲染variantprimary绝对定位在页脚右侧Finish仅当! canGoForward即最后一页时渲染点击后直接调用onFinish。页脚按钮采用position: absoluteleft/right: $grid-unit-30的定位方式见 style.scss使 Previous 与 Next/Finish 始终分居左右两端。空指南与单页指南的边界行为两个值得注意的边界行为均在源码与测试中得到印证pages为空时渲染nullindex.tsx 中if ( pages.length 0 ) { return null; }即默认值[]不会弹出任何模态框调用方可安全地用条件数据生成 pages 数组而不必额外判空。isDismissible随页数变化模态框的isDismissible属性被设置为pages.length 1index.tsx。可以推断其设计意图是多页指南允许用户随时中途退出而单页指南本质上只是一段说明则不允许直接关闭引导用户点击 Finish 来显式结束流程。键盘导航方向键翻页Modal的onKeyDown回调实现了左右方向键翻页onKeyDown{ ( event ) { if ( event.code ArrowLeft ) { goBack(); // Do not scroll the modals contents. event.preventDefault(); } else if ( event.code ArrowRight ) { goForward(); // Do not scroll the modals contents. event.preventDefault(); } } }见 index.tsx两个细节goBack/goForward内部已有边界检查所以方向键在首尾页按下是无害的空操作event.preventDefault()用于阻止方向键滚动模态框内部内容保证翻页的视觉体验稳定。测试用例 allows navigating through the pages with the left and right arrows 精确验证了这一行为包括在边界页反复按方向键时页面索引保持不变。焦点管理翻页即重新聚焦每次currentPage变化后组件将焦点重新放置到.components-guide框体上useEffect( () { // Place focus at the top of the guide on mount and when the page changes. const frame ref.current?.querySelector( .components-guide ); if ( frame instanceof HTMLElement ) { frame.focus(); } }, [ currentPage ] );见 index.tsx这是模态框场景下关键的无障碍实践——翻页后 DOM 内容整体替换若焦点落在已卸载的按钮上键盘用户就会迷路。依赖数组[ currentPage ]同时覆盖了首次挂载与后续翻页两种时机。页码圆点导航PageControl 的实现当pages.length 1时内容区会渲染一个PageControl圆点导航index.tsx允许用户点击任意圆点直接跳转到对应页而不必逐页翻。其实现要点见 page-control.tsx列表结构外层是ul aria-labelGuide controls每个圆点是一个sizesmall的Button内部渲染 PageControlIcon——一个 8×8 的实心圆 SVG无障碍标记当前页的li携带aria-currentstep符合 WAI-ARIA 对步骤指示器的规范源码注释中明确引用了该规范每个按钮的aria-label由sprintf( __( Page %1$d of %2$d ), page 1, numberOfPages )生成即第 n 页共 m 页测试中正是用name: /page \d of \d/i这类模式定位按钮的当前页高亮样式规则li[aria-currentstep] .components-button { color: $components-color-accent; }style.scss让当前页圆点变为主题强调色而非默认灰色$gray-200。测试用例 renders a button for each page 与 sets the current page when a button is clicked 分别验证了页数与圆点数一致和点击圆点即切换当前页含回跳两个行为。已废弃 APIchildren 与 GuidePage在wordpress/components5.5 之前指南页面以 React children 的形式传入并配有一个包装用的GuidePage组件。现在这两者均已被废弃children 方式index.tsx 中若检测到children非空会通过wordpress/deprecated打印Passing children to Guide的警告since: 5.5替代方案为pagesprop并做向后兼容转换——把每个 child 包装成{ content: child }对象再拼成 pages 数组GuidePage组件page.tsx 中每次挂载都会调用deprecated( GuidePage, { since: 5.5, alternative: thepagesprop in Guide } )其渲染体只剩div { ...props } /。从源码结构看这些兼容代码的存在意味着旧版插件不会直接报错但会在控制台留下弃用提示——新代码应一律使用pagesprop。样式结构一览style.scss 定义了组件的全部视觉规则关键点容器尺寸.components-modal__frame.components-guide设定min-width: 312px; max-height: 575px无 border在break-small断点以上宽度固定为 600px头部.components-modal__header去除下边框与内边距position: sticky保持关闭按钮常驻关闭按钮本身被重置为左上角对齐页脚.components-guide__footer是按钮的定位参照系position: relativeheight: $button-size三个导航按钮通过绝对定位分居左右$grid-unit-30即 30px 边距内容区.components-guide__page以 flex 纵向布局并垂直居中小屏下设置min-height: 300px与图片高度变量对齐。测试验证的行为清单测试文件 完整覆盖了组件的行为契约可作为 API 的权威参照无 pages 时不渲染 dialogrenders nothing when there are no pages一次只渲染一页其他页内容不存在于 DOMrenders one page at a time第一页隐藏 Previous、显示 Next、无 Finish最后一页反向两条按钮态测试单页指南不渲染页码圆点列表点击 Finish 触发onFinish按 Escape 触发onFinish验证了模态框关闭路径也走同一回调。小结Guide是一个职责单一、边界清晰的引导组件pages数组描述内容、onFinish统一收口结束逻辑、contentLabel保证对话框可访问性三个按钮文案 props 支持本地化定制。从源码实现看它在状态管理单一currentPage索引、键盘导航方向键 preventDefault、焦点管理翻页后重新聚焦与 ARIA 标注aria-currentstep、第 n 页共 m 页 标签上都做了细致的无障碍处理同时通过deprecated机制平滑迁移了 5.5 之前的children/GuidePage旧 API。在构建 WordPress 插件引导、编辑器新手教程或功能巡览时按 README 示例 组装pages数据即可直接使用。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考