面包屑 - Semi Design Next

代码演示

如何引入

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

Breadcrumb.Item 也可以按名导入：BreadcrumbItem。

基本用法

代码

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Breadcrumb>
        <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
        <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
        <Breadcrumb.Item>Default</Breadcrumb.Item>
    </Breadcrumb>
</template>

带图标的

支持标题只显示图标或者同时显示图标和文本。

图标使用 Breadcrumb.Item 的 #icon 插槽。

代码

<script setup lang="ts">
    import { IconArticle, IconHome } from '@fibrous/semi-icons-vue';
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Breadcrumb>
        <Breadcrumb.Item>
            <template #icon>
                <IconHome size="small" />
            </template>
        </Breadcrumb.Item>
        <Breadcrumb.Item>
            <template #icon>
                <IconArticle size="small" />
            </template>
            Breadcrumb
        </Breadcrumb.Item>
        <Breadcrumb.Item>With Icon</Breadcrumb.Item>
    </Breadcrumb>
</template>

尺寸

默认为 compact，设置属性为 false 可使图标和文字尺寸增加。

代码

<script setup lang="ts">
    import { IconHome } from '@fibrous/semi-icons-vue';
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Breadcrumb aria-label="紧凑面包屑" compact>
            <Breadcrumb.Item>
                <template #icon>
                    <IconHome size="small" />
                </template>
            </Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Loose</Breadcrumb.Item>
        </Breadcrumb>
        <br />
        <Breadcrumb aria-label="宽松面包屑" :compact="false">
            <Breadcrumb.Item>
                <template #icon>
                    <IconHome size="small" />
                </template>
            </Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Loose</Breadcrumb.Item>
        </Breadcrumb>
    </div>
</template>

自定义的分隔符

默认为 /。

separator 属性接收文字分隔符；节点形式的分隔符使用 #separator 插槽，插槽优先于 separator。Breadcrumb.Item 同样提供 separator 属性与 #separator 插槽，用来覆盖父级的分隔符。

v>=1.16.0

代码

<script setup lang="ts">
    import { IconArrowRight } from '@fibrous/semi-icons-vue';
    import { Breadcrumb, Tag } from '@fibrous/semi-ui-vue';
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Breadcrumb aria-label="文字分隔符" separator=">">
            <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
        <br />
        <Breadcrumb aria-label="图标分隔符">
            <template #separator>
                <IconArrowRight size="small" />
            </template>
            <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
        <br />
        <Tag>v&gt;=1.16.0</Tag>
        <br />
        <Breadcrumb aria-label="单项分隔符">
            <Breadcrumb.Item separator=":">Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
    </div>
</template>

截断逻辑

当级别名字溢出设定宽度后省略截断。可以通过 showTooltip 属性设置相关参数。默认宽度150px，鼠标悬停时显示 Tooltip 完整显示级别名称。Breadcrumb.Item 的子节点为数字时（含 0）按文字处理，同样参与截断与 Tooltip。

默认行为
省略但不显示Tooltip
不截断
从标题中间开始省略
自定义 Tooltip 参数

代码

<script setup lang="ts">
    import { Breadcrumb, Typography } from '@fibrous/semi-ui-vue';

    const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页'];
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Typography.Text size="small">默认行为</Typography.Text>
        <Breadcrumb aria-label="默认行为" :routes="routes" />
        <br />
        <Typography.Text size="small">省略但不显示Tooltip</Typography.Text>
        <Breadcrumb aria-label="省略但不显示Tooltip" :routes="routes" :showTooltip="false" />
        <br />
        <Typography.Text size="small">不截断</Typography.Text>
        <Breadcrumb aria-label="不截断" :routes="routes" :showTooltip="{ width: 'auto' }" />
        <br />
        <Typography.Text size="small">从标题中间开始省略</Typography.Text>
        <Breadcrumb aria-label="从标题中间开始省略" :routes="routes" :showTooltip="{ ellipsisPos: 'middle' }" />
        <br />
        <Typography.Text size="small">自定义 Tooltip 参数</Typography.Text>
        <Breadcrumb aria-label="自定义 Tooltip 参数" :routes="routes" :showTooltip="{ opts: { position: 'topLeft' } }" />
    </div>
</template>

当路径层级超过 maxItemCount（默认 4）个，默认折叠第 2 项到第 n-m+1 项（n 为层级总数，m 为 maxItemCount，序号从 1 计，最多到倒数第二项），点击省略号展开显示全部级别；如果过长则自动换行。首项、当前项与末项始终可见。activeIndex 指向会被折叠的项时，当前项保持可见：当前项之前与之后各是一段候选折叠项，折叠项更多的一段被折叠（相等时折叠之前的一段），因此始终只有一个省略号；候选为空时不折叠，此时可见的项可能多于 maxItemCount。可以通过 maxItemCount 来控制超过多少个级别进行折叠。

代码

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Breadcrumb>
        <Breadcrumb.Item>首页</Breadcrumb.Item>
        <Breadcrumb.Item>当层级很多的时候</Breadcrumb.Item>
        <Breadcrumb.Item>又一层</Breadcrumb.Item>
        <Breadcrumb.Item>再一层</Breadcrumb.Item>
        <Breadcrumb.Item>上上一层</Breadcrumb.Item>
        <Breadcrumb.Item>上一层</Breadcrumb.Item>
        <Breadcrumb.Item>详情页</Breadcrumb.Item>
    </Breadcrumb>
</template>

自定义省略号区域

组件内部提供了两种省略号区域渲染的类型，可通过 moreType 来设置，moreType 的可选值为 default 和 popover。

代码

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Breadcrumb moreType="popover">
        <Breadcrumb.Item>首页</Breadcrumb.Item>
        <Breadcrumb.Item>当层级很多的时候</Breadcrumb.Item>
        <Breadcrumb.Item>又一层</Breadcrumb.Item>
        <Breadcrumb.Item>再一层</Breadcrumb.Item>
        <Breadcrumb.Item>上上一层</Breadcrumb.Item>
        <Breadcrumb.Item>上一层</Breadcrumb.Item>
        <Breadcrumb.Item>详情页</Breadcrumb.Item>
    </Breadcrumb>
</template>

如果想要为省略号区域自定义其他形式的渲染，则可以使用 #more="{ restItems }" 插槽。restItems 是被折叠的项，已去掉分隔符，可直接用 <component :is> 挂载。

代码

<script setup lang="ts">
    import { IconMore } from '@fibrous/semi-icons-vue';
    import { Breadcrumb, Popover, type BreadcrumbItemInfo } from '@fibrous/semi-ui-vue';

    const separator = '-'; // 拼接 restItems 用的分隔符
    const onClick = (item: BreadcrumbItemInfo, e: MouseEvent) => console.log(item, e);
</script>

<template>
    <Breadcrumb @click="onClick">
        <Breadcrumb.Item>首页</Breadcrumb.Item>
        <Breadcrumb.Item>当层级很多的时候</Breadcrumb.Item>
        <Breadcrumb.Item>又一层</Breadcrumb.Item>
        <Breadcrumb.Item>再一层</Breadcrumb.Item>
        <Breadcrumb.Item>上上一层</Breadcrumb.Item>
        <Breadcrumb.Item>上一层</Breadcrumb.Item>
        <Breadcrumb.Item>详情页</Breadcrumb.Item>
        <template #more="{ restItems }">
            <Popover showArrow :style="{ padding: '12px' }">
                <IconMore tabindex="-1" />
                <template #content>
                    <template v-for="(item, idx) in restItems" :key="idx">
                        <component :is="item" />
                        <span v-if="idx !== restItems.length - 1" :style="{ color: 'var(--semi-color-text-2)', marginRight: '6px' }">{{ separator }}</span>
                    </template>
                </template>
            </Popover>
        </template>
    </Breadcrumb>
</template>

路由对象

Breadcrumb 支持通过 routes 传入路由对象 route: { name, path, href } 或字符串组成的数组。可以配合 #item="{ route, index }" 插槽自定义标题，用 #icon="{ route, index }" 插槽提供图标，插槽渲染为空时该项无图标。通过这样实现的 Breadcrumb 同样会进行截断处理。routes 中只放字符串和不含节点、函数的对象，不支持 routes[].onClick，改用 Breadcrumb 的 @click（Breadcrumb 的 onClick 是函数 prop，监听与否决定没有 href 的项能否用键盘操作），它的第一个参数是原始路由。

name 为展示的名称，不传入时为空字符串。当 route 为字符串时，默认将字符串设置为名称。
path 为路由路径
href 为链接目的地，挂载在 a 标签上。

代码

<script setup lang="ts">
    import { IconArticle, IconHome } from '@fibrous/semi-icons-vue';
    import { Breadcrumb, type Route } from '@fibrous/semi-ui-vue';

    const iconRoutes: (Route | string)[] = [{ path: '/', href: '/' }, { path: '/breadcrumb', href: '/zh-CN/navigation/breadcrumb', name: 'breadcrumb' }, 'with icon'];
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Breadcrumb aria-label="字符串路由" :routes="['Semi-ui', 'Breadcrumb', 'Default']" />
        <br />
        <Breadcrumb aria-label="带图标的路由" :routes="iconRoutes">
            <template #icon="{ index }">
                <IconHome v-if="index === 0" aria-label="首页" size="small" />
                <IconArticle v-else-if="index === 1" size="small" />
            </template>
        </Breadcrumb>
        <br />
        <Breadcrumb aria-label="长标题路由" :routes="['首页', '当这个页面标题很长时需要省略', '详情页']" />
    </div>
</template>

API 参考

Props

属性	说明	类型	默认值
activeIndex	受控使用，当前项的序号（从 0 起）；缺省时最后一项为当前项。	`number`	`semiGlobalDefault("Breadcrumb", "activeIndex")`
autoCollapse	超出 maxItemCount 后是否自动折叠。	`boolean`	`semiDefault("Breadcrumb", "autoCollapse", true)`
compact	是否使用紧凑尺寸。	`boolean`	`semiDefault("Breadcrumb", "compact", true)`
maxItemCount	超出多少个级别后自动折叠。	`number`	`semiDefault("Breadcrumb", "maxItemCount", 4)`
moreType	内置省略号区域的渲染类型，可选 default、popover；提供 more 插槽时以插槽为准。	`MoreType`	`semiDefault("Breadcrumb", "moreType", "default")`
routes	路由信息，由路由对象或字符串组成的数组；不为空时按 routes 渲染，不再渲染默认插槽。	`(string \| Route)[]`	`semiDefault("Breadcrumb", "routes", [])`
separator	文字分隔符；提供 separator 插槽时以插槽为准。	`string`	`semiDefault("Breadcrumb", "separator", "/")`
showTooltip	是否在标题溢出时展示 Tooltip 及相关配置：width 为溢出宽度，ellipsisPos 为截断方式（从末尾或中间），opts 为传给 Tooltip 的属性，不含 content，class 与 style 落在弹层上。	`boolean \| ShowTooltipProps`	`semiDefault("Breadcrumb", "showTooltip", DEFAULT_TOOLTIP)`
onClick	点击时调用。是函数 prop，使用方照常写 @click；传入后没有 href 的项也可以用 Enter 操作。routes 写法收到该项的路由；Breadcrumb.Item 写法收到 `{ name, href }`，name 是该项的文字。第二个参数为原生 MouseEvent。	`BreadcrumbClick`	`undefined`

Events

事件	说明	回调参数
无

Slots

插槽	说明	作用域参数
default	由 Breadcrumb.Item 组成的子项。	`any`
separator	自定义分隔符，优先于 separator 属性。	`any`
item	routes 写法下自定义每一项的标题，作用域参数为该项的路由与序号。	`BreadcrumbRouteSlotProps`
icon	routes 写法下每一项的图标，作用域参数为该项的路由与序号；渲染为空时该项无图标。	`BreadcrumbRouteSlotProps`
more	自定义省略号区域，作用域参数 restItems 是被折叠的项，已去掉分隔符，可直接用 component 挂载。	`BreadcrumbMoreSlotProps`

Exposes

名称	说明	类型
无

class、style、aria-label 与其他原生属性经 attrs 落在根元素 nav 上。

Props

属性	说明	类型	默认值
active	是否为当前项，由 Breadcrumb 注入；当前项带 aria-current="page" 且不渲染为链接。	`boolean`	`undefined`
href	链接的目的地。	`string`	`undefined`
noLink	移除 hover 和 active 的样式。	`boolean`	`undefined`
route	该项对应的路由对象，由 Breadcrumb 的 routes 写法注入；点击时作为回调的第一个参数。	`Route`	`undefined`
separator	文字分隔符，覆盖 Breadcrumb 的分隔符；提供 separator 插槽时以插槽为准。	`string`	`undefined`
shouldRenderSeparator	是否渲染分隔符，由 Breadcrumb 注入。	`boolean`	`true`
onClick	点击时调用，参数同 Breadcrumb 的 onClick。是函数 prop，使用方照常写 @click；传入后没有 href 的该项也可以用 Enter 操作。	`BreadcrumbClick`	`undefined`

Events

事件	说明	回调参数
无

Slots

插槽	说明	作用域参数
default	该项的文字；字符串与数字按文字处理，参与截断与 Tooltip，其他节点原样内联。	`any`
icon	该项的图标。	`any`
separator	自定义该项的分隔符，优先于 separator 属性。	`any`

Exposes

名称	说明	类型
无

class、style 与其他原生属性经 attrs 落在 Item 最外层的 span 上。

使用方给 Breadcrumb.Item 设置的 key 会保留，带 key 的 Item 重排后内部状态跟随 key 移动。只有 Breadcrumb.Item 子节点会收到 active、shouldRenderSeparator，其他元素与文本原样渲染。

Route

属性	说明	类型	默认值
href	链接目的地	`string`	-
name	路由名	`string`	-
path	路由路径	`string`	-
noLink	移除该项 hover 和 active 的样式	`boolean`	-
separator	该项的文字分隔符，可以覆盖父级的分隔符	`string`	-
key	该项的 key	`string \| number`	-

路由的图标由 #icon 插槽渲染，自定义标题由 #item 插槽渲染；data-* 字段会传给对应的项。

Accessibility

Breadcrumb 支持传入 aria-label 来表示该 Breadcrumb 作用
Breadcrumb 会对当前项设置 aria-current='page'

文案规范

每个页面链接都应该很简短，并且清楚地反映它链接到的位置或链接的实体
按句子大小写书写

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-breadcrumb_link-text	var(--semi-transition_duration-none)	面包屑文字-文字-动画持续时间
$transition_function-breadcrumb_link-text	var(--semi-transition_function-easeIn)	面包屑文字-文字-过渡曲线
$transition_delay-breadcrumb_link-text	var(--semi-transition_delay-none)	面包屑文字-文字-延迟时间
$transform_scale-breadcrumb_link-text	var(--semi-transform_scale-none)	面包屑文字-放大
$spacing-breadcrumb_item_wrap-marginY	$spacing-extra-tight
$spacing-breadcrumb_item_wrap-marginRight	$spacing-extra-tight
$spacing-breadcrumb_item-marginRight	$spacing-extra-tight
$spacing-breadcrumb_item_text-marginLeft	$spacing-extra-tight
$spacing-breadcrumb_restItem-marginRight	$spacing-tight
$color-breadcrumb_default-text-default	var(--semi-color-text-2)
$color-breadcrumb_default-text-hover	var(--semi-color-link)
$color-breadcrumb_default-text-active	var(--semi-color-link-hover)
$color-breadcrumb_active-text-default	var(--semi-color-text-0)
$color-breadcrumb_active-text-active	var(--semi-color-text-0)
$color-breadcrumb_sepearator_default-icon-default	var(--semi-color-text-2)
$color-breadcrumb-restItem-text-default	var(--semi-color-text-2)
$font-breadcrumb_default-fontWeight	$font-weight-regular
$font-breadcrumb_active-fontWeight	$font-weight-bold
$font-breadcrumb_compact-fontSize	$font-size-small
$font-breadcrumb_loose-fontSize	$font-size-regular