# Breadcrumb 面包屑展示页面层级路径。末项为当前页（`aria-current="page"`）。 ## 基础用法

## 项图标 `items` 项的 `icon` 字段传入图标名（与 `oas-icon` 同源注册表），在文本前渲染前置图标。

## 自定义分隔符 `separator` 支持任意文本；值匹配图标注册表名时渲染为图标分隔符（如 `chevron-right`）。

## 项级分隔符 `items` 项的 `separator` 字段可单独覆盖该项之后的分隔符（同样支持图标名）。

## 真实链接有 `href` 的项渲染为原生 `` 链接：点击不阻止默认行为（浏览器原生跳转），同时照常派发 `oas-select`（SPA 宿主可拦截做路由）。`target` 支持新窗口打开，`_blank` 自动补 `noopener noreferrer`。

尚未点击

## 点击事件 `oas-select` 事件：`detail: { value: href }`。本示例用 `href="#"` 占位，点击可见反馈且页面不跳转。

尚未点击

## 禁用项 `items` 项的 `disabled: true` 渲染为非交互文本（`aria-disabled="true"`），点击不派发事件。

## 折叠模式 `collapsed` + `max-items`：items 数量超过 `max-items`（默认 `4`）时，中间项折叠为 `…`，点击 `…` 展开下拉查看全部折叠项。

尚未点击

## 折叠保留数 `items-before-collapse` / `items-after-collapse` 控制折叠省略号前后各保留几项（默认前 `1`、后 `max-items - 2`）。

## 自定义省略号 `collapse-text` 替换折叠省略号的默认 `…` 文本。

## 折叠展开事件点击折叠省略号**展开**下拉时派发 `oas-collapse-click`，`detail: { collapsedItems }` 携带被折叠的原始项数组——宿主可据此自绘折叠面板；收起时不派发。

尚未展开

## 子元素声明式通道除 `items` JSON 外，可用 `` 子元素声明式书写（`items` 属性**显式设置时优先**）。默认插槽文本为 label，属性对齐 `items` 字段：`href`/`target`/`icon`/`disabled`/`max-width`/`separator`/`dropdown`/`active`。子元素增删、属性与文本变化会自动重渲染。

### 自定义分隔符（子元素） `` 置于两个项之间，内容为任意节点（文本 / 图标 / 内联元素）；项级 `separator` 属性支持文本或图标名，`slot="separator"` 子元素可传任意节点。

## 层级缩进视觉面包屑默认平铺；纯 CSS 即可做出「逐级缩进」的层级视觉（分隔符隐藏 + 项按序缩进，不进 API）。思路：`::part(nav)` 改纵向排列、`::part(separator)` 隐藏、`::part(item):nth-child()` 按出现次序递增缩进。

## 项挂菜单（oas-dropdown 组合） `oas-breadcrumb-item` 的 `dropdown` 属性把该项渲染为下拉触发器（链接列表菜单，点击项派发 `oas-select`）；与 `oas-dropdown` 组合可实现更丰富的菜单内容，两个通道的选中反馈可联动到同一状态。

首页

面包屑

oas-dropdown 组合菜单

## 单行省略 `ellipsis`：面包屑不换行，容器过窄时链接文本以省略号截断，链接保留全文 `title`（悬停可见完整名称）。

## 单项宽度截断 `max-item-width`（px）按全局对单项截断，超出省略号 + `title` 悬停全文；项的 `maxWidth` 字段可逐项覆盖。

## 尺寸 `size` 档位：`small` / `medium`（默认）/ `large`。

## 项带下拉菜单 `items` 项的 `dropdown` 数组把该项渲染为下拉触发器（点击展开子项菜单，菜单项点击派发 `oas-select`）。

## 末项可点击 / 当前项语义 - `items` 项的 `active: true` 显式标记当前项（`aria-current="page"` 迁移到该项），其余带 `href` 项照常可点。 - `active-last`：末项（当前页）即使带 `href` 也保持可点击，同时保留 `aria-current="page"`。

尚未点击

## 键盘方向键导航聚焦任一链接或省略号按钮后，`←` / `→` 在项之间循环移动焦点，`Home` / `End` 跳到首尾。下拉触发器 `Esc` 收起菜单。

## 颜色变体 `color` 指定当前项与链接 hover 的语义色（`primary` / `success` / `warning` / `danger` / `info`），颜色走 token（含 dark 变体）。

## 下划线变体 `variant="underline"`：链接与当前项常驻下划线。

## 结构化数据组件自动向宿主注入 schema.org BreadcrumbList JSON-LD（` ## 字号定制字号默认跟随外层 `font-size`（继承），可用 CSS 变量 `--oas-breadcrumb-font` 显式定制（如 `18px`）。 ## API ### oas-breadcrumb #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `active-last` | 末项保持可点击：当前页（末项）带 `href` 时渲染为链接（仍带 `aria-current="page"`） | `boolean` | — | | `collapse-text` | 自定义折叠省略号的文本（默认 `…`） | `string` | `…` | | `collapsed` | 折叠模式：items 数量超过 `max-items` 时中间项折叠为 `…`，点击展开下拉 | `boolean` | — | | `color` | 视觉变体：当前项与链接 hover 使用指定语义色（`primary`/`success`/`warning`/`danger`/`info`） | `string` | — | | `ellipsis` | 单行省略：面包屑不换行，超宽时链接文本以省略号截断 | `boolean` | — | | `items` | 面包屑项 JSON：`label`/`href`/`icon`/`disabled`/`target`/`separator`/`dropdown`/`maxWidth`/`active` | `string` | `[]` | | `items-after-collapse` | 折叠省略号之后保留的项数（默认 `max-items - 2`） | `string` | — | | `items-before-collapse` | 折叠省略号之前保留的项数（默认 `1`） | `string` | — | | `max-item-width` | 全局单项最大宽度（px）：超出省略号截断 + `title` 悬停提示；项级 `maxWidth` 可覆盖 | `string` | — | | `max-items` | 折叠模式下最多可见的项数（含 `…`），非法值回退 `4` | `string` | `4` | | `separator` | 分隔符（支持图标名，如 `chevron-right`） | `string` | `/` | | `size` | 尺寸档位：`small`/`medium`（默认）/`large` | `string` | `medium` | | `variant` | 样式变体：`underline`（链接与当前项常驻下划线） | `string` | — | #### 事件 | 事件 | 说明 | | --- | --- | | `oas-collapse-click` | 折叠省略号被点击展开下拉（收起不派发），`detail: { collapsedItems }`（被折叠的原始项数组，宿主可自定义折叠面板） | | `oas-select` | 点击链接项、折叠下拉项或项下拉菜单项；`detail: { value: href }`（真实链接不阻止默认跳转，宿主可拦截做路由） | #### 插槽 | 名称 | 说明 | | --- | --- | | `separator` | 自定义分隔符内容（文本或图标，替代 separator 属性） | #### CSS 变量 | CSS 变量 | 默认值 | | --- | --- | | `--oas-breadcrumb-font` | `inherit` | ### oas-breadcrumb-item #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `active` | 显式标记当前项（`aria-current="page"`），默认取末项 | — | — | | `disabled` | 禁用项：渲染为非交互文本（aria-disabled） | — | — | | `dropdown` | 项带下拉菜单：链接列表 JSON（如 `[{"label":"子项","href":"/a"}]`），项渲染为下拉触发器 | — | — | | `href` | 链接地址：有 href 时渲染为原生 ``（真实跳转 + 照常派发 `oas-select`） | — | — | | `icon` | 前置图标（`@oas-ui/icons` 内置图标名） | — | — | | `max-width` | 单项最大宽度（px）：超出省略号截断 + `title` 悬停提示 | — | — | | `separator` | 项级分隔符：覆盖全局 `separator`（支持文本或图标名）；亦可用 `slot="separator"` 子元素传任意节点 | — | — | | `target` | 链接 target（`_blank` 时自动补 `noopener noreferrer`） | — | — | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 面包屑项 label 内容（默认插槽文本） | ### oas-breadcrumb-separator #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 分隔符内容：任意节点（文本 / 图标 / 内联元素） | `nav` + `aria-label="面包屑"`，末项 `aria-current="page"` 且不可点击。