面包屑 - Semi Design Next

代码演示

如何引入

import { Breadcrumb } from '@fibrous/semi-ui-solid';

基本用法

代码

import { Breadcrumb } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb>
            <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
    );
}

带图标的

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

图标通过 Breadcrumb.Item 的 icon 属性传入，可以是图标元素，例如 icon={<IconHome />}。

代码

import { IconArticle, IconHome } from '@fibrous/semi-icons-solid';
import { Breadcrumb } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb>
            <Breadcrumb.Item icon={<IconHome size="small" />} />
            <Breadcrumb.Item icon={<IconArticle size="small" />}>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>With Icon</Breadcrumb.Item>
        </Breadcrumb>
    );
}

尺寸

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

代码

import { IconHome } from '@fibrous/semi-icons-solid';
import { Breadcrumb } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <div>
            <Breadcrumb compact aria-label="紧凑面包屑">
                <Breadcrumb.Item icon={<IconHome size="small" />} />
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Loose</Breadcrumb.Item>
            </Breadcrumb>
            <br />
            <Breadcrumb compact={false} aria-label="宽松面包屑">
                <Breadcrumb.Item icon={<IconHome size="small" />} />
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Loose</Breadcrumb.Item>
            </Breadcrumb>
        </div>
    );
}

自定义的分隔符

默认为 /。

separator 属性接收文字或 JSX 元素，例如 separator={<IconArrowRight />}。Breadcrumb.Item 同样提供 separator 属性，用来覆盖父级的分隔符。

v>=1.16.0

代码

import { IconArrowRight } from '@fibrous/semi-icons-solid';
import { Breadcrumb, Tag } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <div>
            <Breadcrumb separator=">" aria-label="文字分隔符">
                <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Default</Breadcrumb.Item>
            </Breadcrumb>
            <br />
            <Breadcrumb separator={<IconArrowRight size="small" />} aria-label="图标分隔符">
                <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Default</Breadcrumb.Item>
            </Breadcrumb>
            <br />
            <Tag>{`v>=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>
    );
}

截断逻辑

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

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

代码

import { Breadcrumb, Typography } from '@fibrous/semi-ui-solid';

const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页'];
const { Text } = Typography;

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

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

代码

import { Breadcrumb } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    return (
        <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>
    );
}

自定义省略号区域

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

代码

import { Breadcrumb } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    return (
        <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>
    );
}

如果想要为省略号区域自定义其他形式的渲染，则可以使用 renderMore 属性。它的参数是被折叠的项的数据：routes 写法下是路由对象，children 写法下是各 Breadcrumb.Item 的 props（在需要显示的位置再读取其 children、icon）；返回值渲染到省略号区域，提供时优先于 moreType。

代码

import { For, Show } from 'solid-js';
import { IconMore } from '@fibrous/semi-icons-solid';
import { Breadcrumb, Popover, type BreadcrumbItemProps, type BreadcrumbRouteProps } from '@fibrous/semi-ui-solid';

const separator = '-'; // 拼接 restItems 用的分隔符

// restItems holds the props of the hidden Breadcrumb.Items, whose children the popover reads only when it opens
const renderMore = (restItems: Array<BreadcrumbRouteProps | BreadcrumbItemProps>) => (
    <Popover
        content={
            <For each={restItems}>
                {(item, index) => (
                    <>
                        {(item as BreadcrumbItemProps).children}
                        <Show when={index() !== restItems.length - 1}>
                            <span style={{ color: 'var(--semi-color-text-2)', 'margin-right': '6px' }}>{separator}</span>
                        </Show>
                    </>
                )}
            </For>
        }
        style={{ padding: '12px' }}
        showArrow
    >
        {/* the more button around the icon is already the Tab stop, so the icon itself is taken out of the Tab order */}
        {(trigger) => <IconMore {...trigger({ tabIndex: -1 })} />}
    </Popover>
);

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb renderMore={renderMore} onClick={(item, e) => console.log(item, e)}>
            <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>
    );
}

路由对象

Breadcrumb 支持通过 routes 传入路由对象 route: { name, path, href } 或字符串组成的数组。路由对象里只放数据；用 renderItem 渲染每一项的内容，用 renderIcon(route, index) 提供图标，参数都包含该项的路由对象。通过这样实现的 Breadcrumb 同样会进行截断处理。

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

代码

import { IconArticle, IconHome } from '@fibrous/semi-icons-solid';
import { Breadcrumb, type BreadcrumbRouteProps } from '@fibrous/semi-ui-solid';

export default function BreadcrumbDemo() {
    const iconRoutes = [
        {
            path: '/',
            href: '/',
        },
        {
            path: '/breadcrumb',
            href: '/zh-CN/navigation/breadcrumb',
            name: 'breadcrumb',
        },
        'with icon',
    ];

    const renderIcon = (route: BreadcrumbRouteProps) => (route.path === '/' ? <IconHome aria-label="首页" size="small" /> : route.path === '/breadcrumb' ? <IconArticle size="small" /> : undefined);

    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <div>
            <Breadcrumb routes={['Semi-ui', 'Breadcrumb', 'Default']} aria-label="字符串路由" />
            <br />
            <Breadcrumb aria-label="带图标的路由" routes={iconRoutes} renderIcon={renderIcon} />
            <br />
            <Breadcrumb routes={['首页', '当这个页面标题很长时需要省略', '详情页']} aria-label="长标题路由" />
        </div>
    );
}

API 参考

Props

属性	说明	类型	默认值
activeIndex	受控使用，当前项的序号（从 0 起）；缺省时最后一项为当前项。	`number`	-
autoCollapse	超出 maxItemCount 后是否自动折叠。	`boolean`	`true`
compact	是否使用紧凑尺寸，影响图标与文字的尺寸。	`boolean`	`true`
maxItemCount	超出多少个级别后自动折叠。	`number`	`4`
moreType	内置省略号区域的渲染类型，可选 default、popover；提供 renderMore 时以 renderMore 为准。	`MoreType`	`"default"`
onClick	点击时调用。routes 写法收到该项的路由；Breadcrumb.Item 写法收到 `{ name, href }`，name 是该项的子节点。第二个参数为原生 MouseEvent。传入后没有 href 的项也可以用 Enter 操作。	`Type`	-
renderIcon	自定义 routes 中每一项的图标，参数为该项的路由对象与序号（含被折叠的项）。	`Type`	-
renderItem	自定义每一项的内容，配合 routes 使用，参数为该项的路由对象（字符串路由为 `{ name }`）。	`Type`	-
renderMore	自定义省略号区域的内容，参数为被折叠的项的数据：routes 写法下是路由对象，children 写法下是各 Breadcrumb.Item 的 props；提供时以它为准。	`Type`	-
routes	路由信息，由路由对象或字符串组成的数组；不为空时按 routes 渲染，不再渲染 children。	`Type`	`[]`
separator	自定义的分隔符，可以是文字或 JSX 元素。	`JSX.Element`	`"/"`
showTooltip	是否在标题溢出时展示 Tooltip 及相关配置：width 为截断宽度，数字按 px 计算，传 'auto' 时不截断；ellipsisPos 为截断位置，end 或 middle；opts 为传给 Tooltip 的属性，不含 content。传 false 时不展示 Tooltip。	`boolean \| showToolTipProps`	`{ width: 150, ellipsisPos: 'end' }`

class、style、ref 与其他原生属性（如 id、data-*）落在根元素 nav 上。

Props

属性	说明	类型	默认值
href	链接的目的地，挂载在 a 标签上；当前项不渲染为链接。	`string`	-
icon	标签的显示图标；Semi 图标未设置 size 时按 Breadcrumb 的 compact 取 small 或 default。	`JSX.Element`	-
noLink	移除 hover 和 active 的样式，该项也不再可以用键盘操作。	`boolean`	-
onClick	单击事件，参数同 Breadcrumb 的 onClick：routes 写法为该项的路由，children 写法为 `{ name, href }`；第二个参数为原生 MouseEvent。	`Type`	-
separator	该项之后的分隔符，覆盖 Breadcrumb 的 separator，可以是文字或 JSX 元素。	`JSX.Element`	-

class、style、ref 与其他原生属性（如 id、data-*）落在 Item 最外层的 span 上。

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

Route

路由还可以带 noLink、separator 与 onClick，作用与 Breadcrumb.Item 的同名属性相同。data-* 字段会传给对应的项。

属性	说明	类型	默认值
href	链接目的地	`string`	-
name	路由名	`string`	-
path	路由路径	`string`	-

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