@douyinfe/semi-ui

Version:

A modern, comprehensive, flexible design system and UI library. Connect DesignOps & DevOps. Quickly build beautiful React apps. Maintained by Douyin-fe team.

semi.design

DouyinFE/semi-design

357 lines (305 loc) • 14 kB

Markdown

--- localeCode: zh-CN order: 56 category: 导航类 title: Breadcrumb 面包屑 icon: doc-breadcrumb brief: 面包屑是用户界面中的一种辅助导航，可以显示当前页面在层级架构中的位置，并能返回之前的页面。 --- ## 代码演示 ### 如何引入 ```jsx import import { Breadcrumb } from '@douyinfe/semi-ui'; ``` ### 基本用法 ```jsx live=true import React from 'react'; import { Breadcrumb } from '@douyinfe/semi-ui'; () => ( <Breadcrumb> <Breadcrumb.Item>Semi-ui</Breadcrumb.Item> <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item> <Breadcrumb.Item>Default</Breadcrumb.Item> </Breadcrumb> ); ``` ### 带图标的支持标题只显示图标或者同时显示图标和文本。 ```jsx live=true import React from 'react'; import { Breadcrumb } from '@douyinfe/semi-ui'; import { IconHome, IconArticle } from '@douyinfe/semi-icons'; () => ( <Breadcrumb> <Breadcrumb.Item icon={<IconHome size="small" />}></Breadcrumb.Item> <Breadcrumb.Item icon={<IconArticle size="small" />}>Breadcrumb</Breadcrumb.Item> <Breadcrumb.Item>With Icon</Breadcrumb.Item> </Breadcrumb> ); ``` ### 尺寸默认为 `compact`，设置属性为 `false` 可使图标和文字尺寸增加。 ```jsx live=true import React from 'react'; import { Breadcrumb } from '@douyinfe/semi-ui'; import { IconHome } from '@douyinfe/semi-icons'; () => ( <div> <Breadcrumb compact> <Breadcrumb.Item icon={<IconHome size="small" />}></Breadcrumb.Item> <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item> <Breadcrumb.Item>Loose</Breadcrumb.Item> </Breadcrumb> <br/> <Breadcrumb compact={false}> <Breadcrumb.Item icon={<IconHome size="small" />}></Breadcrumb.Item> <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item> <Breadcrumb.Item>Loose</Breadcrumb.Item> </Breadcrumb> </div> ); ``` ### 自定义的分隔符默认为 `/`。 ```jsx live=true import React from 'react'; import { Breadcrumb, Tag } from '@douyinfe/semi-ui'; import { IconArrowRight } from '@douyinfe/semi-icons'; () => ( <div> <Breadcrumb separator={'>'}> <Breadcrumb.Item>Semi-ui</Breadcrumb.Item> <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item> <Breadcrumb.Item>Default</Breadcrumb.Item> </Breadcrumb> <br/> <Breadcrumb separator={<IconArrowRight size={'small'} />}> <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 size={'small'} > <Breadcrumb.Item separator=":">Semi-ui</Breadcrumb.Item> <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item> <Breadcrumb.Item>Default</Breadcrumb.Item> </Breadcrumb> </div> ); ``` ### 截断逻辑在 **0.34.0** 版本之后，当级别名字溢出设定宽度后省略截断。可以通过 `showTooltip` 属性设置相关参数。默认宽度150px，鼠标悬停时显示 Tooltip 完整显示级别名称。 ```jsx live=true import React from 'react'; import { Breadcrumb, Typography } from '@douyinfe/semi-ui'; () => { const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页']; const { Text } = Typography; return ( <> <Text size="small">默认行为</Text> <Breadcrumb routes={routes} /> <br/> <Text size="small">省略但不显示Tooltip</Text> <Breadcrumb showTooltip={false} routes={routes} /> <br/> <Text size="small">不截断</Text> <Breadcrumb showTooltip={{ width: 'auto' }} routes={routes} /> <br/> <Text size="small">从标题中间开始省略</Text> <Breadcrumb showTooltip={{ ellipsisPos: 'middle' }} routes={routes} /> <br/> <Text size="small">自定义 Tooltip 参数</Text> <Breadcrumb showTooltip={{ opts: { position: 'topLeft' } }} routes={routes} /> </> ); }; ``` 当路径层级超过 4 个级别，则：第二层至倒数第三层省略，点击省略号展开显示全部级别；如果过长则自动换行。在 **v>=1.9.0** 之后，可以通过 `maxItemCount` 来控制超过多少个级别进行折叠。 ```jsx live=true import React from 'react'; import { Breadcrumb } from '@douyinfe/semi-ui'; () => ( <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`。 ```jsx live=true import React from 'react'; import { Breadcrumb } from '@douyinfe/semi-ui'; () => ( <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()` 方法。 ```jsx live=true import React from 'react'; import { Breadcrumb, Popover } from '@douyinfe/semi-ui'; import { IconMore } from '@douyinfe/semi-icons'; function Demo() { const separator = '-'; // 用于拼接 restItem 数组项的分隔符 const renderMore = restItem => { const content = ( <> { restItem.map((item, idx) => ( <React.Fragment key={`restItem-${idx}`}> {item} {idx !== restItem.length - 1 && <span style={{ color: 'var(--semi-color-text-2)', marginRight: '6px' }}> {separator} </span> } </React.Fragment> )) } </> ); return ( <Popover content={content} style={{ padding: 12 }} showArrow > <IconMore /> </Popover> ); }; return ( <> <Breadcrumb renderMore={restItem => renderMore(restItem)} 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, icon }` 或字符串组成的数组。可以配合 renderItem 来渲染节点。通过这样实现的 Breadcrumb 同样会进行截断处理。 - name 为展示的名称，不传入时为空字符串。当 route 为字符串时，默认将字符串设置为名称。 - path 为路由路径 - href 为链接目的地，挂载在 a 标签上。 - icon 为标签的显示图标 ```jsx live=true hideInDSM import React from 'react'; import { Breadcrumb } from '@douyinfe/semi-ui'; import { IconHome, IconArticle } from '@douyinfe/semi-icons'; () => ( <div> <Breadcrumb routes={['Semi-ui', 'Breadcrumb', 'Default']} /> <br /> <Breadcrumb routes={ [ { path: '/', href: '/', icon: <IconHome size="small" /> }, { path: '/breadcrumb', href: '/zh-CN/navigation/breadcrumb', name: 'breadcrumb', icon: <IconArticle size="small" /> }, 'with icon' ] } /> <br /> <Breadcrumb routes={['首页', '当这个页面标题很长时需要省略', '详情页']} /> </div> ); ``` ## API 参考 ### Breadcrumb | 属性 | 说明 | 类型 | 默认值 | 版本 | | ---------- |---------------------------------------------------------------------------------------------------------| ------------------------------------------ | ------ | ------ | | activeIndex| 受控使用，当前选择的导航序号 | - | 2.61.0 | | autoCollapse | 是否超出maxItemCount后自动折叠 | boolean | true | 1.9.0 | | className | 类名 | string | - | | | compact | 显示尺寸，是否紧凑 | boolean | true | | | maxItemCount | 超出多少个进行自动折叠 | number | 4 | 1.9.0 | |moreType| 内置的...区域的渲染类型，可选值为 'default'、'popover' |string|'default'|1.27.0| | renderItem | 自定义链接函数，配合 routes 使用 | (Route: [Route](#Route)) => ReactNode | - | 0.27.0 | | renderMore| 自定义...区域的渲染 |(restItem: ReactNode[]) => ReactNode|-|1.27.0| | routes | router 的路由信息，由路由对象或字符串组成的数组，路由对象格式参考: [Route](#Route) | Array<[Route](#Route) \| string\> | - | | | separator | 自定义的分隔符 | ReactNode | '/' | | | showTooltip | 是否展示 Tooltip 及相关配置: width，溢出宽度； ellipsisPos，截断方式，从中间/末尾截断； opts，透传给Tooltip的属性 | boolean \| showToolTipProps | {width: 150, ellipsisPos: 'end', opts: { autoAdjustOverflow: true, position: "bottomLeft" }} | 0.34.0 | | style | 内联样式 | CSSProperties | - | | | onClick | 单击事件 | (item: [Route](#Route) , e: Event) => void | - | 0.27.0 | ### Breadcrumb.Item | 属性 | 说明 | 类型 | 默认值 | 版本 | | ------- | -------------- | ------------------------------- | ------ | ------ | | href | 链接的目的地 | string | - | | | icon | 标签的显示图标 | ReactNode | - | | | onClick | 单击事件 | function(item: Route, e: Event) | - | 0.27.0 | | separator | 分隔符，可以覆盖父级的分隔符 | ReactNode | - | 1.16.0 | | noLink | 移除 hover 和 active 的样式 | boolean | false | 1.16.0 | ### Route | 属性 | 说明 | 类型 | 默认值 | 版本 | | ---- | -------------- | ----------------- | ------ | ------ | | href | 链接目的地 | string | - | 0.27.0 | | icon | 标签的显示图标 | ReactNode | - | | | name | 路由名 | string | - | | | path | 路由路径 | string | - | | **v>=1.16.0** 之后 Route 支持 Breadcrumb.Item 上的相应属性。 ## Accessibility - Breadcrumb 支持传入 `aria-label` 来表示该 Breadcrumb 作用 - Breadcrumb 会对当前项设置 `aria-current='page'` ## 文案规范 - 每个页面链接都应该很简短，并且清楚地反映它链接到的位置或链接的实体 - 按句子大小写书写 ## 设计变量 <DesignToken/>