面包屑 · Breadcrumbs

面包屑用于导航场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

面包屑 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
面包屑 · 综合展示 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
面包屑 · 基础用法 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
面包屑 · 自定义 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
面包屑 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
面包屑 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
面包屑 · 样式变化 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
面包屑 · 包含图标 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

BreadcrumbItem represents one destination, action, current location, or sibling-menu trigger inside a Breadcrumbs trail.

属性	类型	说明
children *	ReactNode	面包屑项的标签内容。
href	string	面包屑链接的 URL；不可导航的项目请省略。
onClick	(e: MouseEvent) => void	面包屑项的点击处理函数。
isCurrent	boolean	将此项标记为当前页面，应用 aria-current="page"。省略时，如果没有显式的当前项，则自动将最后一项标记为当前项；传入 false 可退出自动检测。
startIcon	ReactNode	在项目标签前渲染的图标。
menu	DropdownMenuOption[] \| ReactNode	激活项目时打开的菜单，使用与 DropdownMenu/MoreMenu/ContextMenu 相同的项目 API（DropdownMenuOption[] 数组或组合的 DropdownMenuItem 子元素）。渲染为带 chevron 和 aria-haspopup="menu" 的链接样式触发器。优先于 href/onClick。
menuSize	'sm' \| 'md' \| 'lg'	传递给菜单项的尺寸。默认根据面包屑变体推断（'supporting' → 'sm'，否则 'md'）。
as	LinkComponentType	自定义链接组件，代替 <a> 渲染。覆盖 LinkProvider 设置的默认值。仅适用于非当前项。

Breadcrumbs

Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.

属性	类型	默认值	说明
children *	ReactNode		BreadcrumbItem elements to render inside the breadcrumb trail.
separator	ReactNode	'/'	Separator rendered between breadcrumb items. The built-in slash mirrors automatically in RTL.
variant	'default' \| 'supporting'	'default'	Visual variant: supporting is smaller with secondary text styling.
label	string	'Breadcrumb'	Accessible label for the nav landmark (aria-label).
xstyle	StyleXStyles		StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.

使用建议

Place breadcrumbs above the page heading so the user sees their location before reading the content.
Keep labels short and match the page titles they link to: "Settings" not "Application Settings Page".
Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.
Make the last item plain text, not a link; it represents the current page. The component does this automatically when you set isCurrent.
The component implements the WAI-ARIA APG Breadcrumb pattern: a labelled nav landmark wrapping an ordered list, with aria-current="page" on the current item. A crumb with a menu additionally implements the APG Menu Button pattern, opening on Enter, Space or ArrowDown and closing on Escape.
Give each trail its own label when a page renders more than one, so the nav landmarks stay distinguishable in a screen reader landmark list.
避免：Use breadcrumbs as the primary navigation. They supplement a sidebar or top nav, not replace it.
避免：Show breadcrumbs on top-level pages that have no parent; they add clutter without helping the user.
避免：Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.
The built-in slash separator mirrors automatically in RTL. For a custom separator, leave Unicode-mirrored angle quotes such as › alone; mirror arrows and Icon separators once with rtlStyles.mirror.
避免：Mirror a separator the bidi algorithm already mirrors. An angle-quote glyph such as › is Bidi_Mirrored, so it flips under RTL on its own and rtlStyles.mirror would flip it back. An arrow glyph such as → and any Icon separator are not, so those do need rtlStyles.mirror through xstyle.

主题 API

{
  "targets": [
    {
      "className": "astryx-breadcrumb-item",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-breadcrumb-item-menu-trigger",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-breadcrumb-menu"
    },
    {
      "className": "astryx-breadcrumbs",
      "visualProps": [
        "variant"
      ]
    }
  ]
}

Individual breadcrumb item. Renders as a link when href is provided, or as plain text for the current page.

属性	类型	说明
children *	ReactNode	Label content for the breadcrumb item.
href	string	URL the breadcrumb links to; omit for non-navigable items.
onClick	(e: MouseEvent) => void	Click handler for the breadcrumb item.
isCurrent	boolean	Marks this item as the current page, applying aria-current="page". When omitted, the last item is auto-detected if no item is explicitly current; pass false to opt out.
startIcon	ReactNode	Icon rendered before the item label.
as	LinkComponentType	Custom link component to render instead of <a>. Overrides the provider-level default from LinkProvider. Only applies to non-current items.
menu	DropdownMenuOption[] \| ReactNode	Menu opened when the item is activated, using the same item API as DropdownMenu/MoreMenu/ContextMenu (a DropdownMenuOption[] array or composed DropdownMenuItem children). Renders a link-styled menu trigger with a chevron and aria-haspopup="menu". Takes precedence over href/onClick.
menuSize	'sm' \| 'md' \| 'lg'	Size passed to the menu items. Defaults from the breadcrumb variant ('supporting' → 'sm', otherwise 'md').

组件结构

Trail: The ordered list of links from root to current page.
Item: A single step in the trail. Renders as a link or plain text for the current page.
Separator: The character between items. Defaults to "/" but can be customized.
Icon: An optional icon before an item label, like a home icon on the first item.

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0

面包屑