Navigator 是一组组件的集合，允许通过 Navigator.Screen 组件渲染嵌套的视图/面板/菜单，并通过 Navigator.Button 和 Navigator.BackButton 组件在这些视图之间进行导航。

用法

import { Navigator } from '@wordpress/components';

const MyNavigation = () => (
    <Navigator initialPath="/">
        <Navigator.Screen path="/">
            <p>这是主屏幕。</p>
            <Navigator.Button path="/child">
                导航到子屏幕。
            </Navigator.Button>
        </Navigator.Screen>
        <Navigator.Screen path="/child">
            <p>这是子屏幕。</p>
            <Navigator.BackButton>返回</Navigator.BackButton>
        </Navigator.Screen>
    </Navigator>
);

层级路径

Navigator 假设屏幕根据其 path 以层级方式组织，该路径应遵循类似 URL 的方案，其中每个路径段都以 / 字符开头并由其分隔。

Navigator 将“后退”导航视为前往父级屏幕——因此，创建正确屏幕层级结构是组件使用者的责任。

例如：

  • / 是所有路径的根。始终应该有一个 path="/" 的屏幕；
  • /parent/child 是 /parent 的子级；
  • /parent/child/grand-child 是 /parent/child 的子级；
  • /parent/:param 也是 /parent 的子级；
  • 如果当前屏幕具有 path="/parent/child/grand-child"，则在执行“后退”操作时，Navigator 将尝试递归遍历路径层级，直到找到匹配的屏幕（或根目录 /）。

高度和动画

由于 Navigator.Screen 动画的工作原理，建议为 Navigator 组件分配一个 height，以防止在屏幕间切换时出现一些潜在的 UI 跳动。

独立组件

Navigator 由四个独立的组件组成：

  • Navigator：包装器组件和上下文提供者。它包含隐藏和显示屏幕的主要逻辑。
  • Navigator.Screen：表示单个视图/屏幕/面板；
  • Navigator.Button：渲染一个按钮，允许导航到不同的 Navigator.Screen；
  • Navigator.BackButton：渲染一个按钮，允许导航到父级 Navigator.Screen（参见上面关于层级路径的部分）。

对于高级用法，使用者可以使用 useNavigator hook。

Navigator

属性
initialPath: string

初始激活的路径。

  • 必需：是
children: string

子元素。

  • 必需：是

Navigator.Screen

属性
path: string

屏幕的路径，与 navigator 中存储的当前路径进行匹配。

Navigator 假设屏幕根据其 path 以层级方式组织，该路径应遵循类似 URL 的方案，其中每个路径段都以 / 字符开头并由其分隔。

Navigator 将“后退”导航视为前往父级屏幕——因此，创建正确屏幕层级结构是组件使用者的责任。

例如：

  • / 是所有路径的根。始终应该有一个 path="/" 的屏幕。
  • /parent/child 是 /parent 的子级。
  • /parent/child/grand-child 是 /parent/child 的子级。
  • /parent/:param 也是 /parent 的子级。
  • 如果当前屏幕的 path 值为 /parent/child/grand-child，则在执行“后退”操作时，Navigator 将尝试递归遍历路径层级，直到找到匹配的屏幕（或根目录 /）。

  • 必需：是

children: string

子元素。

  • 必需：是

Navigator.Button

属性
path: string

要导航到的屏幕的路径。此属性的值需要是 HTML 属性的有效值。

  • 必需：是
attributeName: string

用于标识 Navigator.Button 的 HTML 属性，Navigator 使用它来恢复焦点。

  • 必需：否
  • 默认值：id
children: string

子元素。

  • 必需：否
继承的属性

Navigator.Button 还继承了所有 Button 属性，除了 href 和 target。

Navigator.BackButton

属性
children: string

子元素。

  • 必需：否
继承的属性

Navigator.BackButton 还继承了所有 Button 属性，除了 href 和 target。

useNavigator

你可以使用 useNavigator hook 来获取 navigator 实例。

属性

navigator 实例具有几个属性：

goTo: ( path: string, options: NavigateOptions ) => void

goTo 函数允许导航到给定路径。第二个参数可以通过不同的选项来增强导航操作。

可用的选项有：

  • focusTargetSelector: string。可选属性，用于指定用于在后退导航时恢复匹配元素焦点的 CSS 选择器；
  • isBack: boolean。可选属性，用于指定是否应将导航视为向后（从而在可能时启用焦点恢复，并使动画也向后播放）；
  • skipFocus: boolean。可选属性，用于选择不使用 Navigator 的焦点管理，当组件使用者希望自行管理焦点时很有用；
goBack: ( path: string, options: NavigateOptions ) => void

goBack 函数允许导航到父级屏幕。父子导航仅在定义的路径是层级化的时才有效（参见上面的说明）。

当未找到匹配项时，该函数将尝试递归遍历路径层级，直到找到匹配的屏幕（或根目录 /）。

可用的选项与 goTo 方法相同，但 isBack 属性除外，该属性在 goBack 方法中不可用。

location: NavigatorLocation

location 对象表示当前位置，并具有几个属性：

  • path: string。与该位置关联的路径。
  • isBack: boolean。当通过向后导航到达当前位置时为 true 的标志。
  • isInitial: boolean。仅对初始位置为 true 的标志。
params: Record< string, string | string[] >

来自当前位置的解析后的参数记录。例如，如果当前屏幕路径为 /product/:productId 且位置为 /product/123，则 params 将为 { productId: '123' }。