Appearance
xtf-breadcrumb
组件说明
xtf-breadcrumb 是面包屑，用于呈现层级路径并处理路径项导航。当前实现读取 items 数据、通过 click 等事件反馈交互。
- 实际 Demo 路由：
#/pages/components/xtf-breadcrumb/index - Demo 源码
基础用法
1. 最小可用
提供能够直接看到或操作组件的最少业务内容。
vue
<template>
<view class="doc-minimum">
<XtfBreadcrumb :items="fixture" />
</view>
</template>
<script setup lang="uts">
import XtfBreadcrumb from "@/uni_modules/xtf-linkuiunix/components/xtf-breadcrumb/xtf-breadcrumb.uvue"
const fixture = [{ key: 'home', label: '首页', path: '/pages/index/index' }, { key: 'bill', label: '账单' }] as Array<any>
</script>
<style>
.doc-minimum { display: flex; flex-direction: column; padding: 24rpx; }
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2. 核心数据与主要事件
使用组件真实数据入口，并记录当前源码声明的主要事件。
vue
<template>
<view class="doc-core">
<XtfBreadcrumb :items="fixture" @click="onPrimaryEvent" />
</view>
</template>
<script setup lang="uts">
import XtfBreadcrumb from "@/uni_modules/xtf-linkuiunix/components/xtf-breadcrumb/xtf-breadcrumb.uvue"
const fixture = [{ key: 'home', label: '首页', path: '/pages/index/index' }, { key: 'bill', label: '账单' }] as Array<any>
function onPrimaryEvent(payload: any): void { console.log("xtf-breadcrumb:click", payload) }
</script>
<style>
.doc-core { display: flex; flex-direction: column; padding: 24rpx; }
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
3. 动态 block 状态
运行时切换 block，观察组件对应状态变化。
vue
<template>
<view class="doc-dynamic">
<XtfBreadcrumb :items="fixture" :block="state" />
<button class="doc-action-button" @click="toggleState">切换 block</button>
<text class="doc-state-text">block: {{ state }}</text>
</view>
</template>
<script setup lang="uts">
import XtfBreadcrumb from "@/uni_modules/xtf-linkuiunix/components/xtf-breadcrumb/xtf-breadcrumb.uvue"
import { ref } from "vue"
const fixture = [{ key: 'home', label: '首页', path: '/pages/index/index' }, { key: 'bill', label: '账单' }] as Array<any>
const state = ref(false)
function toggleState(): void { state.value = !state.value; console.log("block", state.value) }
</script>
<style>
.doc-dynamic { display: flex; flex-direction: column; padding: 24rpx; }
.doc-action-button { margin-top: 16rpx; }
.doc-state-text { margin-top: 12rpx; color: #475569; font-size: 24rpx; }
</style>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
4. 定制 item 插槽
使用源码真实声明的 item slot 替换对应内容。
vue
<template>
<view class="doc-slot">
<XtfBreadcrumb :items="fixture">
<template #item="scope"><text class="doc-content-text">自定义 item 内容：{{ scope.item }}</text></template>
</XtfBreadcrumb>
</view>
</template>
<script setup lang="uts">
import XtfBreadcrumb from "@/uni_modules/xtf-linkuiunix/components/xtf-breadcrumb/xtf-breadcrumb.uvue"
const fixture = [{ key: 'home', label: '首页', path: '/pages/index/index' }, { key: 'bill', label: '账单' }] as Array<any>
</script>
<style>
.doc-slot { display: flex; flex-direction: column; padding: 24rpx; }
.doc-content-text { color: #334155; font-size: 26rpx; }
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
全部属性
| 属性 | 源码类型 | withDefaults 默认值 | 实际行为 / 范围 | 适用范围 |
|---|---|---|---|---|
items | XtfBreadcrumbItem[] | () => [] as XtfBreadcrumbItem[] | 参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 26、script 行 28、script 行 82 | 数据驱动或选项渲染场景。 |
separator | string | "/" | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：template 行 15、template 行 34 | 需要覆盖组件默认业务值时设置。 |
separatorIcon | string | "" | 设置对应区域的图标名称；消费位置：template 行 15、template 行 16、template 行 34、template 行 35 | 需要提供业务文案或图标内容时设置。 |
maxCount | string | number | 4 | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 26 | 需要覆盖组件默认业务值时设置。 |
ellipsisText | string | "..." | 设置对应区域的显示文案；消费位置：script 行 32 | 需要提供业务文案或图标内容时设置。 |
ellipsisMode | "middle" | "start" | "end" | "middle" | 参与组件运行逻辑；源码在 2 处读取该值；可选值：middle / start / end；消费位置：script 行 33、script 行 38 | 需要覆盖组件默认业务值时设置。 |
theme | XtfBreadcrumbTheme | "primary" | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 54 | 需要调整布局或视觉表现时设置。 |
variant | XtfBreadcrumbVariant | "plain" | 参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 54、script 行 73 | 需要调整布局或视觉表现时设置。 |
size | XtfBreadcrumbSize | "md" | 参与组件运行逻辑；源码在 7 处读取该值；消费位置：script 行 52、script 行 53、script 行 54、script 行 64 | 需要覆盖组件默认业务值时设置。 |
block | boolean | false | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 54 | 需要覆盖组件默认业务值时设置。 |
round | boolean | false | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 54、script 行 73 | 需要覆盖组件默认业务值时设置。 |
showHomeIcon | boolean | false | 设置对应区域的图标名称；消费位置：script 行 68 | 需要控制显示、可用性或交互状态时设置。 |
homeIcon | string | "home" | 设置对应区域的图标名称；消费位置：script 行 68 | 需要提供业务文案或图标内容时设置。 |
activeColor | string | "" | 设置对应区域的颜色；消费位置：script 行 57 | 需要调整布局或视觉表现时设置。 |
inactiveColor | string | "" | 设置对应区域的颜色；消费位置：script 行 58 | 需要调整布局或视觉表现时设置。 |
separatorColor | string | "" | 设置对应区域的颜色；消费位置：script 行 59 | 需要调整布局或视觉表现时设置。 |
background | string | "" | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 60 | 需要覆盖组件默认业务值时设置。 |
borderColor | string | "" | 设置对应区域的颜色；消费位置：script 行 61 | 需要调整布局或视觉表现时设置。 |
autoNavigate | boolean | false | 开关对应显示或交互行为；消费位置：script 行 84 | 需要覆盖组件默认业务值时设置。 |
scrollable | boolean | false | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 2 | 需要覆盖组件默认业务值时设置。 |
showScrollbar | boolean | false | 开关对应显示或交互行为；消费位置：template 行 2 | 需要控制显示、可用性或交互状态时设置。 |
itemClass | string | "" | 追加到对应内部区域的 class；消费位置：script 行 73 | 需要调整布局或视觉表现时设置。 |
itemStyle | UTSJSONObject | () => ({} as UTSJSONObject) | 覆盖或追加对应内部区域的样式对象；消费位置：script 行 76 | 需要调整布局或视觉表现时设置。 |
labelClass | string | "" | 追加到对应内部区域的 class；消费位置：script 行 75 | 需要调整布局或视觉表现时设置。 |
labelStyle | UTSJSONObject | () => ({} as UTSJSONObject) | 覆盖或追加对应内部区域的样式对象；消费位置：script 行 77 | 需要调整布局或视觉表现时设置。 |
separatorClass | string | "" | 追加到对应内部区域的 class；消费位置：script 行 64 | 需要调整布局或视觉表现时设置。 |
separatorStyle | UTSJSONObject | () => ({} as UTSJSONObject) | 覆盖或追加对应内部区域的样式对象；消费位置：script 行 65 | 需要调整布局或视觉表现时设置。 |
customClass | string | "" | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 54 | 需要调整布局或视觉表现时设置。 |
customStyle | UTSJSONObject | () => ({} as UTSJSONObject) | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 56 | 需要调整布局或视觉表现时设置。 |
XtfBreadcrumbItem 数据结构
| 字段 | 源码类型 | 字段语义 |
|---|---|---|
label | string | 显示文字 |
title | string | 主标题 |
key | string | 稳定渲染标识 |
value | string | 业务值 |
path | string | 页面或资源路径 |
icon | string | 图标名称 |
dot | boolean | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
meta | string | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
clickable | boolean | 该项是否允许点击 |
disabled | boolean | 是否禁止该项交互 |
highlight | boolean | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
openType | string | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
navigationType | string | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
style | UTSJSONObject | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
itemClass | string | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
labelClass | string | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
iconClass | string | 源码声明的业务扩展字段；当前实现未提供更具体语义。 |
事件
| 事件名称 | 源码触发边界 | 回调参数 | 参数说明 |
|---|---|---|---|
click | handleClick 内触发（script 行 83）；参数表达式：{ item: sourceItem, index: index } as UTSJSONObject；前置 guard：item.ellipsis、isActive(index) || item.disabled || !item.clickable | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
ellipsis-click | handleClick 内触发（script 行 80）；参数表达式：{ item: item, index: index, hiddenItems: item.hiddenItems, hiddenCount: item.hiddenItems.length } as UTSJSONObject；前置 guard：item.ellipsis | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
navigate | navigate 内触发（script 行 94）；参数表达式：{ item: sourceItem, index: index, method: method } as UTSJSONObject | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
插槽
| 插槽 | Scope 参数 | 实际渲染位置 |
|---|---|---|
item | (props: { item: XtfBreadcrumbRenderItem, index: number, active: boolean, ellipsis: boolean }) | 仅在模板对应 <slot> 渲染位置生效。 |
separator | (props: { item: XtfBreadcrumbRenderItem, index: number, active: boolean, ellipsis: boolean }) | 仅在模板对应 <slot> 渲染位置生效。 |
方法
实例方法
| 方法 | 签名 / 返回值 | 调用边界 |
|---|---|---|
| - | - | 当前组件没有公开实例方法。 |
公开状态
| 状态 | 类型 / 包装 | 读取边界 |
|---|---|---|
| - | - | 当前组件没有公开状态。 |
主题说明
var(--xtf-breadcrumb-active)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-breadcrumb-border)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-breadcrumb-inactive)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-breadcrumb-separator)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-breadcrumb-soft)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-border)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-danger)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-danger-soft)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-info)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-info-soft)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-primary)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-primary-soft)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-success)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-success-soft)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-surface-muted)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-text)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-text-disabled)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-text-secondary)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-warning)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-color-warning-soft)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。var(--xtf-opacity-disabled)：组件样式实际读取的主题变量，可在xtf-config-provider作用域或主题 class 下覆盖。
平台与实现边界
- 基线为 HBuilderX 5.26+ 与 uni-app x；当前报告已验证 Web Chromium 的对应 Demo，不据此承诺 Safari、小程序或 App 原生端等价。
- Android、iOS、HarmonyOS、Vapor 原生路径、触摸手势、字体、Canvas、安全区和系统权限能力，只有源码或完整性报告明确覆盖的部分才可视为已验证。
- 本文按当前源码生成，不补入旧版
xtf-linkui存在但迁移版未实现的 props、事件、slot 或方法。 - 详细公共边界见 平台与实现边界，逐项运行证据见项目根目录 COMPONENT_COMPLETENESS.md。