导航类

面包屑

面包屑是用户界面中的一种辅助导航,可以显示当前页面在层级架构中的位置,并能返回之前的页面。

代码演示

如何引入

<script lang="ts">
    import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>

Svelte 没有 Breadcrumb.Item,每一项由 routes 描述。

基本用法

代码
<script lang="ts">
    import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>

<Breadcrumb routes={['Semi-ui', 'Breadcrumb', 'Default']} />

带图标的

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

图标使用 icon snippet,参数带该项的 route、index,以及要传给图标的 size 与 class:<IconHome {size} class={className} />。图标按序号区分,没有图标的项渲染为空;只显示图标的项,name 写成空字符串,并给图标加 aria-label。

代码
<script lang="ts">
    import { IconArticle, IconHome } from '@fibrae/semi-icons-svelte';
    import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>

<Breadcrumb routes={['', 'Breadcrumb', 'With Icon']}>
    {#snippet icon({ class: className, index, size })}
        {#if index === 0}
            <IconHome aria-label="Home" class={className} {size} />
        {:else if index === 1}
            <IconArticle class={className} {size} />
        {/if}
    {/snippet}
</Breadcrumb>

尺寸

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


代码
<script lang="ts">
    import { IconHome } from '@fibrae/semi-icons-svelte';
    import { Breadcrumb, type BreadcrumbIconContext } from '@fibrae/semi-ui-svelte';

    const routes = ['', 'Breadcrumb', 'Loose'];
</script>

{#snippet icon({ class: className, index, size }: BreadcrumbIconContext)}
    {#if index === 0}
        <IconHome aria-label="Home" class={className} {size} />
    {/if}
{/snippet}

<!-- Several breadcrumbs on one page are told apart by aria-label -->
<div>
    <Breadcrumb aria-label="紧凑面包屑" compact {icon} {routes} />
    <br />
    <Breadcrumb aria-label="宽松面包屑" compact={false} {icon} {routes} />
</div>

自定义的分隔符

默认为 /。

separator 属性接收文字;节点形式的分隔符使用 separator snippet。单个路由可以带 separator 字段,覆盖共享的分隔符。



v>=1.16.0

代码
<script lang="ts">
    import { IconArrowRight } from '@fibrae/semi-icons-svelte';
    import { Breadcrumb, Tag } from '@fibrae/semi-ui-svelte';
</script>

<!-- Several breadcrumbs on one page are told apart by aria-label -->
<div>
    <Breadcrumb aria-label="文字分隔符" routes={['Semi-ui', 'Breadcrumb', 'Default']} separator=">" />
    <br />
    <Breadcrumb aria-label="图标分隔符" routes={['Semi-ui', 'Breadcrumb', 'Default']}>
        {#snippet separator()}
            <IconArrowRight size="small" />
        {/snippet}
    </Breadcrumb>
    <br />
    <Tag>v&gt;=1.16.0</Tag>
    <br />
    <Breadcrumb aria-label="单项分隔符" routes={[{ name: 'Semi-ui', separator: ':' }, 'Breadcrumb', 'Default']} />
</div>

截断逻辑

当级别名字溢出设定宽度后省略截断。可以通过 showTooltip 属性设置相关参数。默认宽度150px,鼠标悬停时显示 Tooltip 完整显示级别名称。

标题来自路由的 name,按文字处理,参与截断与 Tooltip;item snippet 的内容按内联渲染,不截断。

默认行为
省略但不显示Tooltip
不截断
从标题中间开始省略
自定义 Tooltip 参数
代码
<script lang="ts">
    import { Breadcrumb, TypographyText } from '@fibrae/semi-ui-svelte';

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

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

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

代码
<script lang="ts">
    import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>

<Breadcrumb routes={['首页', '当层级很多的时候', '又一层', '再一层', '上上一层', '上一层', '详情页']} />

自定义省略号区域

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

代码
<script lang="ts">
    import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>

<Breadcrumb moreType="popover" routes={['首页', '当层级很多的时候', '又一层', '再一层', '上上一层', '上一层', '详情页']} />

如果想要为省略号区域自定义其他形式的渲染,则可以使用 more snippet。参数 restItems 是被折叠的项,每项为 { route, index };提供时优先于 moreType。

代码
<script lang="ts">
    import { IconMore } from '@fibrae/semi-icons-svelte';
    import { Breadcrumb, Popover, type BreadcrumbRoute } from '@fibrae/semi-ui-svelte';

    // Joins the collapsed items in the popup
    const separator = '-';
    const onClick = (route: BreadcrumbRoute, event: MouseEvent) => console.log(route, event);
</script>

<Breadcrumb {onClick} routes={['首页', '当层级很多的时候', '又一层', '再一层', '上上一层', '上一层', '详情页']}>
    {#snippet more({ restItems })}
        <Popover showArrow style="padding: 12px">
            {#snippet child({ props })}<IconMore {...props} tabindex={-1} />{/snippet}
            {#snippet content()}
                {#each restItems as { route, index }, i (index)}
                    <span>{route.name}</span>
                    {#if i < restItems.length - 1}
                        <span style="color: var(--semi-color-text-2); margin-inline-end: 6px">{separator}</span>
                    {/if}
                {/each}
            {/snippet}
        </Popover>
    {/snippet}
</Breadcrumb>

路由对象

Breadcrumb 通过 routes 传入路由对象 route: { name, path, href } 或字符串组成的数组,不提供 Breadcrumb.Item。用 item snippet 自定义标题(按内联渲染,不走截断),用 icon snippet 提供图标,参数都带该项的 route 与 index。路由里只放数据,不支持 routes[].onClick,改用 Breadcrumb 的 onClick(它是函数 prop,传入与否决定没有 href 的项能否用键盘操作),第一个参数是该项的路由,字符串路由收到 { name }。

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


代码
<script lang="ts">
    import { IconArticle, IconHome } from '@fibrae/semi-icons-svelte';
    import { Breadcrumb, type BreadcrumbRoute } from '@fibrae/semi-ui-svelte';

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

<!-- 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}>
        {#snippet icon({ class: className, index, size })}
            {#if index === 0}
                <IconHome aria-label="首页" class={className} {size} />
            {:else if index === 1}
                <IconArticle class={className} {size} />
            {/if}
        {/snippet}
    </Breadcrumb>
    <br />
    <Breadcrumb aria-label="长标题路由" routes={['首页', '当这个页面标题很长时需要省略', '详情页']} />
</div>

API 参考

Props

属性说明类型默认值
activeIndex受控使用,当前项的序号(从 0 起);缺省时最后一项为当前项。number-
autoCollapse超出 maxItemCount 后是否自动折叠。booleantrue
compact是否使用紧凑尺寸。booleantrue
icon每一项的图标,参数为该项的路由、序号、size 与 class,需要把后两者传给图标;渲染为空时该项无图标。TypeSnippet<[BreadcrumbIconContext]>-
item自定义每一项的标题,参数为该项的路由与序号;内容按内联渲染,不走截断。TypeSnippet<[BreadcrumbRouteContext]>-
maxItemCount超出多少个级别后自动折叠。number4
more自定义省略号区域,参数 restItems 是被折叠的项({ route, index })。TypeSnippet<[BreadcrumbMoreContext]>-
moreType内置省略号区域的渲染类型,可选 default、popover;提供 more snippet 时以 snippet 为准。BreadcrumbMoreType"default"
onClick点击时调用,收到该项的路由(字符串路由为 { name })与原生 MouseEvent。是函数 prop,不是 nav 的原生点击监听;传入后没有 href 的项也可以用 Enter 操作。BreadcrumbClick-
routes路由信息,由路由对象或字符串组成的数组。TypeArray<BreadcrumbRoute | string>[]
separator分隔符,可以是文字或 snippet。string | Snippet"/"
showTooltip是否在标题溢出时展示 Tooltip 及相关配置:width 为溢出宽度,ellipsisPos 为截断方式(从末尾或中间),opts 为传给 Tooltip 的属性,不含 content,class 与 style 落在弹层上。boolean | BreadcrumbShowTooltip{ width: 150, ellipsisPos: 'end' }

class、style、aria-label 与其他原生属性落在根元素 nav 上;onClick 是函数 prop,不是 nav 的原生点击监听。

Svelte 没有 Breadcrumb.Item,每一项的数据见下方 Route。

Route

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

路由的图标由 icon snippet 渲染,自定义标题由 item snippet 渲染;data-* 字段会传给对应的项。

Accessibility

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

文案规范

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

设计变量

下表是组件内部的 Sass 变量,不能覆写。定制样式请覆写 --semi-* CSS 变量(见 Design Token 页),或写不分层的 CSS 规则。
Sass 变量值用法
$transition_duration-breadcrumb_link-textvar(--semi-transition_duration-none)面包屑文字-文字-动画持续时间
$transition_function-breadcrumb_link-textvar(--semi-transition_function-easeIn)面包屑文字-文字-过渡曲线
$transition_delay-breadcrumb_link-textvar(--semi-transition_delay-none)面包屑文字-文字-延迟时间
$transform_scale-breadcrumb_link-textvar(--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-defaultvar(--semi-color-text-2)
$color-breadcrumb_default-text-hovervar(--semi-color-link)
$color-breadcrumb_default-text-activevar(--semi-color-link-hover)
$color-breadcrumb_active-text-defaultvar(--semi-color-text-0)
$color-breadcrumb_active-text-activevar(--semi-color-text-0)
$color-breadcrumb_sepearator_default-icon-defaultvar(--semi-color-text-2)
$color-breadcrumb-restItem-text-defaultvar(--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