xtf-breadcrumb
组件说明
xtf-breadcrumb 是面包屑导航组件，用于展示当前页面在层级结构中的位置路径。支持省略折叠、多种视觉变体（纯文本、柔和、胶囊、描边、下划线）、自动导航和图标定制，适用于后台管理、文件目录和商品分类等层级导航场景。
基础用法
1. 最简示例
通过 items 传入路径数组，最后一项自动高亮为当前页：
vue
<template>
<xtf-breadcrumb :items="items" @click="onClick" />
</template>
<script>
export default {
data() {
return {
items: [
{ label: '首页', path: '/pages/index/index' },
{ label: '商品管理', path: '/pages/goods/list' },
{ label: '商品详情' }
]
}
},
methods: {
onClick({ item, index }) {
console.log('点击了:', item.label)
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2. 省略折叠
通过 maxCount 限制显示数量，超出部分自动折叠为省略号，ellipsisMode 控制省略位置：
vue
<template>
<view>
<xtf-text level="caption" color="secondary">中间省略</xtf-text>
<xtf-breadcrumb
:items="items"
:max-count="3"
ellipsis-mode="middle"
@ellipsis-click="onEllipsisClick"
/>
<xtf-text level="caption" color="secondary" style="margin-top: 24rpx">开头省略</xtf-text>
<xtf-breadcrumb
:items="items"
:max-count="3"
ellipsis-mode="start"
@ellipsis-click="onEllipsisClick"
/>
<xtf-text level="caption" color="secondary" style="margin-top: 24rpx">末尾省略</xtf-text>
<xtf-breadcrumb
:items="items"
:max-count="3"
ellipsis-mode="end"
@ellipsis-click="onEllipsisClick"
/>
</view>
</template>
<script>
export default {
data() {
return {
items: [
{ label: '首页', path: '/pages/index/index' },
{ label: '商品管理', path: '/pages/goods/list' },
{ label: '电子产品', path: '/pages/goods/electronics' },
{ label: '手机', path: '/pages/goods/phone' },
{ label: 'iPhone 15' }
]
}
},
methods: {
onEllipsisClick({ hiddenItems, hiddenCount }) {
uni.showToast({ title: '隐藏了 ' + hiddenCount + ' 项', icon: 'none' })
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
3. 视觉变体
通过 variant 切换视觉风格：'plain' / 'soft' / 'pill' / 'outline' / 'underline'：
vue
<template>
<view>
<xtf-text level="caption" color="secondary">纯文本</xtf-text>
<xtf-breadcrumb :items="items" variant="plain" />
<xtf-text level="caption" color="secondary" style="margin-top: 24rpx">柔和</xtf-text>
<xtf-breadcrumb :items="items" variant="soft" />
<xtf-text level="caption" color="secondary" style="margin-top: 24rpx">胶囊</xtf-text>
<xtf-breadcrumb :items="items" variant="pill" />
<xtf-text level="caption" color="secondary" style="margin-top: 24rpx">描边</xtf-text>
<xtf-breadcrumb :items="items" variant="outline" />
<xtf-text level="caption" color="secondary" style="margin-top: 24rpx">下划线</xtf-text>
<xtf-breadcrumb :items="items" variant="underline" />
</view>
</template>
<script>
export default {
data() {
return {
items: [
{ label: '首页', path: '/pages/index/index' },
{ label: '设置', path: '/pages/settings/index' },
{ label: '账户' }
]
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
4. 图标与分隔符
通过 showHomeIcon 在首项显示首页图标，通过 separatorIcon 使用图标分隔符，items 每项支持 icon 字段：
vue
<template>
<xtf-breadcrumb
:items="items"
show-home-icon
separator-icon="chevron-right"
theme="info"
@click="onClick"
/>
</template>
<script>
export default {
data() {
return {
items: [
{ label: '首页', path: '/pages/index/index' },
{ label: '订单管理', path: '/pages/order/list', icon: 'list' },
{ label: '订单详情' }
]
}
},
methods: {
onClick({ item }) {
console.log('导航到:', item.path)
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
5. 自动导航
通过 autoNavigate 启用点击自动跳转，items 每项的 path 作为跳转地址，openType 控制跳转方式：
vue
<template>
<xtf-breadcrumb :items="items" auto-navigate @navigate="onNavigate" />
</template>
<script>
export default {
data() {
return {
items: [
{ label: '首页', path: '/pages/index/index' },
{ label: '商品列表', path: '/pages/goods/list' },
{ label: '商品详情', path: '/pages/goods/detail', openType: 'navigateTo' }
]
}
},
methods: {
onNavigate({ item, method }) {
console.log('跳转方式:', method, '路径:', item.path)
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
全部属性
| 属性 | 类型 | 默认值 | 作用描述 | 适用范围 |
|---|---|---|---|---|
items | Array | [] | 路径数据数组，每项字段见下方子表 | 核心数据源 |
separator | String | '/' | 分隔符文字 | 自定义分隔符 |
separatorIcon | String | '' | 分隔符图标名，设置后替代文字分隔符 | 使用图标分隔 |
maxCount | String | Number | 4 | 最大显示项数，超出折叠为省略号 | 长路径折叠 |
ellipsisText | String | '...' | 省略项显示文字 | 自定义省略文案 |
ellipsisMode | String | 'middle' | 省略位置：'middle' 中间 / 'start' 开头 / 'end' 末尾 | 控制折叠位置 |
theme | String | 'primary' | 主题色：'primary' / 'success' / 'warning' / 'danger' / 'info' / 'inverse' | 切换主题色 |
variant | String | 'plain' | 视觉变体：'plain' / 'soft' / 'pill' / 'outline' / 'underline' | 切换视觉风格 |
size | String | 'md' | 尺寸：'sm' / 'md' / 'lg' | 控制字号和间距 |
block | Boolean | false | 是否占满整行宽度 | 块级布局 |
round | Boolean | false | 是否圆角样式 | 圆角风格 |
showHomeIcon | Boolean | false | 是否在首项显示首页图标 | 首页图标 |
homeIcon | String | 'home' | 首页图标名 | 自定义首页图标 |
activeColor | String | '' | 自定义当前项颜色 | 精确控制高亮色 |
inactiveColor | String | '' | 自定义非当前项颜色 | 精确控制文字色 |
separatorColor | String | '' | 自定义分隔符颜色 | 精确控制分隔符色 |
background | String | '' | 自定义背景色（soft/pill 变体） | 精确控制背景色 |
borderColor | String | '' | 自定义边框色（outline 变体） | 精确控制边框色 |
autoNavigate | Boolean | false | 是否点击自动跳转页面 | 自动导航 |
customClass | String | '' | 自定义类名 | 样式覆盖 |
customStyle | String | Object | Array | '' | 自定义样式 | 动态样式覆盖 |
items 数组每项支持的字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
label | String | — | 项显示文字（必填），也兼容 title |
path | String | '' | 跳转路径，autoNavigate 时使用 |
icon | String | '' | 项前图标名 |
dot | Boolean | false | 是否显示圆点指示 |
meta | String | '' | 辅助信息文字 |
clickable | Boolean | true | 是否可点击，设为 false 禁止点击 |
disabled | Boolean | false | 是否禁用，禁用后不可点击且半透明 |
highlight | Boolean | false | 是否高亮加粗 |
openType | String | 'navigateTo' | 跳转方式：'navigateTo' / 'redirectTo' / 'switchTab' / 'reLaunch'，也兼容 navigationType |
style | String | Object | '' | 单项自定义样式 |
key | String | — | 唯一标识 |
事件
| 事件名称 | 触发时机 | 回调参数 | 参数说明 |
|---|---|---|---|
click | 点击非当前项时触发（disabled / clickable=false 不触发） | (payload: { item: Object, index: Number }) | item 为点击项数据，index 为索引 |
ellipsis-click | 点击省略项时触发 | (payload: { item: Object, index: Number, hiddenItems: Array, hiddenCount: Number }) | hiddenItems 为被隐藏的项数组 |
navigate | 自动导航跳转后触发（需 autoNavigate） | (payload: { item: Object, index: Number, method: String }) | method 为跳转方式 |
事件使用示例
vue
<template>
<xtf-breadcrumb
:items="items"
:max-count="2"
@click="onClick"
@ellipsis-click="onEllipsisClick"
/>
</template>
<script>
export default {
data() {
return {
items: [{ label: '首页', path: '/pages/index/index' }, { label: '商品' }, { label: '详情' }]
}
},
methods: {
onClick({ item, index }) {
console.log('点击路径', item, index)
},
onEllipsisClick({ hiddenItems }) {
console.log('隐藏路径', hiddenItems)
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
插槽
| 插槽名 | 作用域参数 | 说明 |
|---|---|---|
item | { item, index, active, ellipsis } | 替换路径项。 |
separator | { item, index } | 替换路径分隔符。 |
插槽使用示例
vue
<template>
<xtf-breadcrumb :items="items" :max-count="3">
<template #item="{ item, active, ellipsis }">
<text :style="{ color: active ? '#2563eb' : '#64748b' }">
{{ ellipsis ? '更多' : item.label }}
</text>
</template>
<template #separator="{ index }">
<text style="margin: 0 8rpx; color: #94a3b8">{{ index === 0 ? '>' : '/' }}</text>
</template>
</xtf-breadcrumb>
</template>
<script>
export default {
data() {
return {
items: [
{ label: '首页', path: '/pages/index/index' },
{ label: '商品管理', path: '/pages/goods/list' },
{ label: '手机' },
{ label: '详情' }
]
}
}
}
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
主题说明
- 当前项颜色使用
var(--xtf-breadcrumb-active)，非当前项使用var(--xtf-breadcrumb-inactive) - 分隔符颜色使用
var(--xtf-breadcrumb-separator) soft/pill变体背景使用var(--xtf-breadcrumb-soft)，边框透明outline变体边框使用var(--xtf-breadcrumb-border)underline变体当前项下划线颜色跟随--xtf-breadcrumb-active- 字号使用
var(--xtf-breadcrumb-font-size)，辅助信息字号使用var(--xtf-breadcrumb-meta-size) - 间距使用
var(--xtf-breadcrumb-gap)，内边距使用var(--xtf-breadcrumb-padding)
如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。