Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Breadcrumb 面包屑
显示当前页面在系统层级里的位置,点前面的层级可以返回上级页面。由 NsBreadcrumb 和 NsBreadcrumbItem 配合使用。
引入
import { NsBreadcrumb, NsBreadcrumbItem } from '@ns/ui'
基础用法
每一层用一个 NsBreadcrumbItem,默认插槽是这一层的文字。项和项之间自动加分隔符,最后一项(当前页)后面不加,并显示成正文色加粗。
<template>
<NsBreadcrumb>
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
路由跳转
to 指定路由目标,可以是路径字符串,也可以是路由对象(如 { name: 'user', params: { id: 1 } })。replace 为 true 时用 router.replace 代替 router.push,不会在历史记录里留下一条。
组件库不依赖 vue-router,用的是应用 app.use(router) 后挂上的 $router:
- 应用注册了路由:链接的
href是router.resolve(to).href(路由表里解析不了时,字符串to原样当href)。点击时阻止浏览器默认跳转,改成调用router.push(to)或router.replace(to)。按住 Ctrl、Shift 等修饰键或用中键点击时交给浏览器,可以在新标签页打开。 - 应用没有注册路由:字符串
to当普通链接的href,由浏览器跳转;对象to没法转成地址,这一项显示成普通文本(同时传了href时用href)。
<template>
<NsBreadcrumb>
<NsBreadcrumbItem to="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem :to="{ path: '/system', query: { tab: 'user' } }">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem to="/system/user" replace>用户管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户详情</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
普通链接
href 渲染成普通的 <a href>,由浏览器跳转,不经过路由。同时传了 to 和 href 时,to 能转成地址就用 to。
<template>
<NsBreadcrumb>
<NsBreadcrumbItem href="https://example.com">官网</NsBreadcrumbItem>
<NsBreadcrumbItem>帮助中心</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
不可点击的项
clickable 设为 false 时,即使传了 to 或 href,这一项也只显示成文本,不能点。
<template>
<NsBreadcrumb>
<NsBreadcrumbItem to="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem to="/system" :clickable="false">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
自定义分隔符
NsBreadcrumb 的 separator 设置文字分隔符,默认 /,可以是任意文字;separator-icon 用图标做分隔符(NsIcon 的 name),写了它时 separator 不起作用。分隔符比各项文字淡一档。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace>
<span class="row-label">/(默认)</span>
<NsBreadcrumb>
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</NsSpace>
<NsSpace>
<span class="row-label">></span>
<NsBreadcrumb separator=">">
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</NsSpace>
<NsSpace>
<span class="row-label">·</span>
<NsBreadcrumb separator="·">
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</NsSpace>
<NsSpace>
<span class="row-label">chevron-right</span>
<NsBreadcrumb separator-icon="chevron-right">
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</NsSpace>
<NsSpace>
<span class="row-label">arrow-right</span>
<NsBreadcrumb separator-icon="arrow-right">
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</NsSpace>
<NsSpace>
<span class="row-label">caret-right</span>
<NsBreadcrumb separator-icon="caret-right">
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 96px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
单项分隔符
NsBreadcrumbItem 的 separator 只改这一项后面的分隔符,优先级高于 NsBreadcrumb 的 separator 和 separator-icon。
<template>
<NsBreadcrumb separator-icon="chevron-right">
<NsBreadcrumbItem href="/" separator="|">首页</NsBreadcrumbItem>
<NsBreadcrumbItem href="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
带图标
默认插槽可以放任意内容,例如在文字前面加一个 NsIcon。
<template>
<NsBreadcrumb separator-icon="chevron-right">
<NsBreadcrumbItem href="/">
<NsIcon name="home" style="margin-right: 4px" />
首页
</NsBreadcrumbItem>
<NsBreadcrumbItem href="/users">
<NsIcon name="users" style="margin-right: 4px" />
成员管理
</NsBreadcrumbItem>
<NsBreadcrumbItem>
<NsIcon name="user" style="margin-right: 4px" />
张三
</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
动态生成
用 v-for 根据数据生成。中间插入、删除项后,“最后一项”按页面上的实际顺序重新判断,分隔符跟着更新。
<script setup lang="ts">
import { ref } from 'vue'
import { NsBreadcrumb, NsBreadcrumbItem, NsButton, NsSpace } from '@ns/ui'
const levels = [
{ path: '/', label: '首页' },
{ path: '/system', label: '系统管理' },
{ path: '/system/user', label: '用户管理' },
{ path: '/system/user/1', label: '用户详情' },
{ path: '/system/user/1/log', label: '登录记录' }
]
const crumbs = ref(levels.slice(0, 3))
const addLevel = () => {
crumbs.value = levels.slice(0, crumbs.value.length + 1)
}
const removeLast = () => {
crumbs.value = crumbs.value.slice(0, -1)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsBreadcrumb>
<NsBreadcrumbItem v-for="item in crumbs" :key="item.path" :to="item.path">
{{ item.label }}
</NsBreadcrumbItem>
</NsBreadcrumb>
<NsSpace wrap>
<NsButton :disabled="crumbs.length >= levels.length" @click="addLevel">加一层</NsButton>
<NsButton :disabled="crumbs.length <= 1" @click="removeLast">删掉最后一层</NsButton>
</NsSpace>
</NsSpace>
</template>
读取是否可点
NsBreadcrumbItem 通过 ref 暴露 hasLink,表示这一项现在是不是渲染成了链接。下面切换 clickable,看第二项的变化:
<script setup lang="ts">
import { ref } from 'vue'
import { NsBreadcrumb, NsBreadcrumbItem, NsSpace, NsSwitch } from '@ns/ui'
const clickable = ref(true)
const itemRef = ref<InstanceType<typeof NsBreadcrumbItem>>()
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace>
<NsSwitch v-model="clickable" />
<span>第二项 clickable:{{ clickable }}</span>
</NsSpace>
<NsBreadcrumb>
<NsBreadcrumbItem href="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem ref="itemRef" href="/system" :clickable="clickable"
>系统管理</NsBreadcrumbItem
>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
<span>hasLink:{{ itemRef?.hasLink }}</span>
</NsSpace>
</template>
NsBreadcrumb Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| separator | string | '/' | 分隔符文字 |
| separatorIcon | string | - | 用图标做分隔符,值是 NsIcon 的 name。写了它时 separator 不起作用 |
NsBreadcrumbItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| to | string | Record<string, unknown> | - | 路由目标。应用注册了路由时点击调用 router.push;没有路由时字符串当普通链接,对象显示成文本 |
| replace | boolean | false | 用 to 跳转时是否用 router.replace |
| href | string | - | 普通链接地址,由浏览器跳转 |
| clickable | boolean | true | 是否可点击。为 false 时只显示文本 |
| separator | string | - | 这一项后面的分隔符,优先于 NsBreadcrumb 的 separator、separatorIcon |
NsBreadcrumb Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsBreadcrumbItem |
NsBreadcrumbItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 这一层的内容 |
NsBreadcrumbItem 暴露的属性
通过组件的 ref 读取。
| 名称 | 类型 | 说明 |
|---|---|---|
| hasLink | boolean | 这一项现在是不是渲染成了链接 |
| updateIsLast | (value: boolean) => void | NsBreadcrumb 内部用来标记最后一项,使用方不需要调用 |
类型
import type {
BreadcrumbRoute,
BreadcrumbRouter,
BreadcrumbProps,
BreadcrumbItemProps
} from '@ns/ui'
/** 路由目标:路径字符串或 vue-router 的路由对象 */
type BreadcrumbRoute = string | Record<string, unknown>
/** 组件只用到 $router 的这几个方法 */
interface BreadcrumbRouter {
push(to: BreadcrumbRoute): unknown
replace(to: BreadcrumbRoute): unknown
resolve?(to: BreadcrumbRoute): { href: string }
}
interface BreadcrumbProps {
separator?: string
separatorIcon?: string
}
interface BreadcrumbItemProps {
to?: BreadcrumbRoute
replace?: boolean
href?: string
clickable?: boolean
separator?: string
}
另外还导出了 BreadcrumbItemInstance、BreadcrumbContext 和注入用的 BREADCRUMB_INJECTION_KEY,自己写和 NsBreadcrumb 配合的子组件时才用得到。
注意事项
NsBreadcrumbItem要放在NsBreadcrumb里,单独使用时开发环境会打警告。- 分隔符只能用
separator传文字、separator-icon传图标名,没有分隔符插槽。 - 最后一项(当前页)传了
to或href时仍然是链接,点了照样跳转,只是样式和文本一样(正文色加粗、默认光标)。不想让它能点,就不传to、href,或者加:clickable="false"。 - 最后一项带
aria-current="page";分隔符对读屏软件隐藏。 - 带链接的项是有
href的<a>,可以用 Tab 键聚焦,按回车跳转,也可以右键或中键在新标签页打开。 - 运行时修改
separator、separator-icon会立即生效。 to只靠应用里的$router跳转,和项目里装了几份、哪个版本的 vue-router 无关;to写的是路由对象时,应用要注册路由才能点。