代码演示
如何引入
<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 字段,覆盖共享的分隔符。
代码
<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>=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 参考
Breadcrumb
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| activeIndex | 受控使用,当前项的序号(从 0 起);缺省时最后一项为当前项。 | number | - |
| autoCollapse | 超出 maxItemCount 后是否自动折叠。 | boolean | true |
| compact | 是否使用紧凑尺寸。 | boolean | true |
| icon | 每一项的图标,参数为该项的路由、序号、size 与 class,需要把后两者传给图标;渲染为空时该项无图标。 | TypeSnippet<[BreadcrumbIconContext]> | - |
| item | 自定义每一项的标题,参数为该项的路由与序号;内容按内联渲染,不走截断。 | TypeSnippet<[BreadcrumbRouteContext]> | - |
| maxItemCount | 超出多少个级别后自动折叠。 | number | 4 |
| 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 的原生点击监听。
Breadcrumb.Item
Svelte 没有 Breadcrumb.Item,每一项的数据见下方 Route。
Route
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| href | 链接目的地 | string | - |
| name | 路由名 | string | - |
| path | 路由路径 | string | - |
| noLink | 移除该项 hover 和 active 的样式 | boolean | - |
| separator | 该项的文字分隔符,可以覆盖父级的分隔符 | string | - |
| key | 该项的 key | string | number | - |
路由的图标由 icon snippet 渲染,自定义标题由 item snippet 渲染;data-* 字段会传给对应的项。
Accessibility
- Breadcrumb 支持传入
aria-label来表示该 Breadcrumb 作用 - Breadcrumb 会对当前项设置
aria-current='page'
文案规范
- 每个页面链接都应该很简短,并且清楚地反映它链接到的位置或链接的实体
- 按句子大小写书写
设计变量
| 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 |