mirror of
https://github.com/fastapiadmin/FastapiAdmin.git
synced 2026-09-21 04:46:26 +00:00
308 lines
7.8 KiB
Markdown
308 lines
7.8 KiB
Markdown
---
|
|
title: 自定义 Tabbar
|
|
iframe: true
|
|
iframeFormatter: ''
|
|
---
|
|
|
|
# 自定义 Tabbar
|
|
|
|
本项目基于 [Wot UI](https://wot-ui.cn/) 的 `wd-tabbar` 组件，提供自定义 Tabbar 的实现。
|
|
|
|
## 实现原理
|
|
|
|
项目的自定义 Tabbar 主要由以下三个部分组成：
|
|
|
|
1. **配置文件** (`pages.config.ts`) - 启用自定义 Tabbar 并配置基础信息
|
|
2. **组件实现** (`src/layouts/tabbar.vue`) - 自定义 Tabbar 的视图层
|
|
3. **状态管理** (`src/composables/useTabbar.ts`) - Tabbar 的逻辑和状态管理
|
|
|
|
当前实现中，`tabbar.vue` 会在 APP 端调用 `uni.hideTabBar()` 隐藏原生 Tabbar，并通过 `router.pushTab` 切换页面。
|
|
|
|
## 添加 Tabbar 项
|
|
|
|
### 1. 修改配置文件
|
|
|
|
在 `pages.config.ts` 中的 `tabBar.list` 数组中添加新的页面路径：
|
|
|
|
```typescript
|
|
tabBar: {
|
|
custom: true,
|
|
// ... 其他配置
|
|
list: [{
|
|
pagePath: 'pages/index/index',
|
|
}, {
|
|
pagePath: 'pages/about/index',
|
|
}, {
|
|
// 添加新的tabbar项
|
|
pagePath: 'pages/new-page/index',
|
|
}],
|
|
}
|
|
```
|
|
|
|
### 2. 更新状态管理
|
|
|
|
在 `src/composables/useTabbar.ts` 中的 `tabbarItems` 数组中添加对应的配置：
|
|
|
|
```typescript
|
|
const tabbarItems = ref<TabbarItem[]>([
|
|
{ name: 'home', active: true, title: '首页', icon: 'home' },
|
|
{ name: 'about', active: false, title: '关于', icon: 'user' },
|
|
// 添加新的tabbar项
|
|
{ name: 'new-page', active: false, title: '新页面', icon: 'star' },
|
|
])
|
|
```
|
|
|
|
### 3. TabbarItem 接口说明
|
|
|
|
```typescript
|
|
interface TabbarItem {
|
|
name: string // 页面名称，对应路由name
|
|
value?: number // 徽标数值，不传表示不显示徽标
|
|
active: boolean // 是否为当前激活项
|
|
title: string // 显示标题
|
|
icon: string // 图标名称
|
|
}
|
|
```
|
|
|
|
## 配置图标
|
|
|
|
### 图标来源
|
|
|
|
项目使用 [Wot UI](https://wot-ui.cn/) 的内置图标库。你可以通过以下方式查看可用图标：
|
|
|
|
1. 访问 [Wot UI 图标文档](https://wot-ui.cn/component/icon.html)
|
|
2. 查看所有可用的图标名称
|
|
|
|
### 修改图标
|
|
|
|
在 `src/composables/useTabbar.ts` 中修改对应项的 `icon` 字段：
|
|
|
|
```typescript
|
|
const tabbarItems = ref<TabbarItem[]>([
|
|
{ name: 'home', active: true, title: '首页', icon: 'home' },
|
|
{ name: 'about', active: false, title: '关于', icon: 'user' },
|
|
])
|
|
```
|
|
|
|
### 常用图标示例
|
|
|
|
```typescript
|
|
// 常用的tabbar图标
|
|
'home' // 首页
|
|
'user' // 用户/关于
|
|
'shopping-bag' // 购物
|
|
'star' // 收藏
|
|
'setting' // 设置
|
|
'message' // 消息
|
|
'search' // 搜索
|
|
'calendar' // 日历
|
|
```
|
|
|
|
### 使用自定义图标
|
|
|
|
如果内置图标不能满足需求，你可以使用 `wd-tabbar-item` 的 `icon` 插槽来自定义图标。
|
|
|
|
#### 修改 tabbar.vue 组件
|
|
|
|
在 `src/layouts/tabbar.vue` 中使用插槽自定义图标：
|
|
|
|
```vue
|
|
<template>
|
|
<wd-tabbar
|
|
:model-value="activeTabbar.name"
|
|
placeholder
|
|
bordered
|
|
safe-area-inset-bottom
|
|
fixed
|
|
@change="handleTabbarChange"
|
|
>
|
|
<wd-tabbar-item
|
|
v-for="(item, index) in tabbarList"
|
|
:key="index"
|
|
:name="item.name"
|
|
:value="getTabbarItemValue(item.name)"
|
|
:title="item.title"
|
|
>
|
|
<!-- 使用 icon 插槽自定义图标 -->
|
|
<template #icon="{ active }">
|
|
<image
|
|
:src="active ? item.activeIcon : item.inactiveIcon"
|
|
class="custom-icon"
|
|
/>
|
|
</template>
|
|
</wd-tabbar-item>
|
|
</wd-tabbar>
|
|
</template>
|
|
|
|
<style>
|
|
.custom-icon {
|
|
width: 22px;
|
|
height: 22px;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
#### 更新 TabbarItem 接口
|
|
|
|
```typescript
|
|
interface TabbarItem {
|
|
name: string // 页面名称，对应路由name
|
|
value?: number // 徽标数值，不传表示不显示徽标
|
|
active: boolean // 是否为当前激活项
|
|
title: string // 显示标题
|
|
icon: string // 图标名称（使用内置图标时）
|
|
activeIcon?: string // 激活状态自定义图标路径
|
|
inactiveIcon?: string // 未激活状态自定义图标路径
|
|
}
|
|
```
|
|
|
|
#### 配置自定义图标
|
|
|
|
```typescript
|
|
const tabbarItems = ref<TabbarItem[]>([
|
|
{
|
|
name: 'home',
|
|
active: true,
|
|
title: '首页',
|
|
icon: 'home',
|
|
activeIcon: '/static/icons/home-active.png',
|
|
inactiveIcon: '/static/icons/home.png'
|
|
},
|
|
{
|
|
name: 'about',
|
|
active: false,
|
|
title: '关于',
|
|
icon: 'user',
|
|
activeIcon: '/static/icons/about-active.png',
|
|
inactiveIcon: '/static/icons/about.png'
|
|
},
|
|
])
|
|
```
|
|
|
|
> 📖 **了解更多**: 查看 [wd-tabbar 组件文档](https://wot-ui.cn/component/tabbar.html) 了解更多自定义选项和插槽用法。
|
|
|
|
## 徽标配置
|
|
|
|
自定义 Tabbar 支持显示徽标，通过 `setTabbarItem` 方法为 Tabbar 项设置徽标数值。
|
|
|
|
### 显示徽标
|
|
|
|
使用 `setTabbarItem` 方法为 Tabbar 项设置徽标数值：
|
|
|
|
```typescript
|
|
const { setTabbarItem } = useTabbar()
|
|
|
|
// 为 'about' 页面设置徽标数值为 5
|
|
setTabbarItem('about', 5)
|
|
```
|
|
|
|
### 清除徽标
|
|
|
|
当前 `setTabbarItem` 的类型签名是 `setTabbarItem(name: string, value: number)`，文档示例只演示数字徽标。
|
|
|
|
如果你希望支持显式清除（例如传 `undefined` 或 `null`），建议先将 `useTabbar.ts` 中的签名改为 `value?: number` 或 `value: number | null`，再在业务中调用。
|
|
|
|
### 在组件中使用
|
|
|
|
```vue
|
|
<script setup>
|
|
const { setTabbarItem } = useTabbar()
|
|
|
|
// 模拟收到新消息
|
|
function onNewMessage() {
|
|
setTabbarItem('about', 3) // 显示3条未读消息
|
|
}
|
|
|
|
// 消息已读
|
|
function onMessageRead() {
|
|
// 当前实现没有“清除徽标”的独立方法，可按业务约定设置数字值
|
|
setTabbarItem('about', 1)
|
|
}
|
|
</script>
|
|
```
|
|
|
|
## 取消自定义 Tabbar
|
|
|
|
如果你想恢复使用 uni-app 原生 Tabbar，按以下步骤操作：
|
|
|
|
### 1. 修改配置文件
|
|
|
|
在 `pages.config.ts` 中修改 `tabBar` 配置：
|
|
|
|
```typescript
|
|
tabBar: {
|
|
custom: false, // 改为 false 或直接删除此行
|
|
color: '#7A7E83',
|
|
selectedColor: '#3cc51f',
|
|
backgroundColor: '#ffffff',
|
|
borderStyle: 'black',
|
|
list: [{
|
|
pagePath: 'pages/index/index',
|
|
text: '首页',
|
|
iconPath: '/static/icon/home.png', // 需要提供图标文件
|
|
selectedIconPath: '/static/icon/home-active.png'
|
|
}, {
|
|
pagePath: 'pages/about/index',
|
|
text: '关于',
|
|
iconPath: '/static/icon/about.png',
|
|
selectedIconPath: '/static/icon/about-active.png'
|
|
}],
|
|
}
|
|
```
|
|
|
|
### 2. 准备图标资源
|
|
|
|
原生 Tabbar 需要提供图标文件，在 `static/icon/` 目录下放置相应的图标：
|
|
|
|
- 未选中状态图标：`home.png`、`about.png`
|
|
- 选中状态图标：`home-active.png`、`about-active.png`
|
|
|
|
### 3. 移除自定义组件
|
|
|
|
可以选择删除或注释以下文件：
|
|
- `src/layouts/tabbar.vue`
|
|
- `src/composables/useTabbar.ts`
|
|
|
|
### 4. 更新布局
|
|
|
|
如果使用了自定义 Tabbar 布局，需要相应调整页面布局文件。
|
|
|
|
## 注意事项
|
|
|
|
1. **平台兼容性**: 自定义 Tabbar 在所有平台都能正常工作，但在 APP 端会自动隐藏原生 Tabbar
|
|
2. **页面路由**: 确保 `pages.config.ts` 中的 `pagePath` 与实际页面文件路径一致
|
|
3. **路由名称**: `tabbarItems` 中的 `name` 需要与目标页面路由名一致，否则 `router.pushTab({ name })` 无法正确跳转
|
|
4. **徽标更新**: 徽标状态是响应式的，可以实时更新
|
|
5. **主题支持**: 自定义 Tabbar 完全支持明暗主题切换
|
|
|
|
## API 参考
|
|
|
|
### useTabbar()
|
|
|
|
返回的方法和属性：
|
|
|
|
```typescript
|
|
const {
|
|
tabbarList, // 计算属性：Tabbar项列表
|
|
activeTabbar, // 计算属性：当前激活的Tabbar项
|
|
getTabbarItemValue, // 方法：获取指定项的徽标值
|
|
setTabbarItem, // 方法：设置指定项的徽标值
|
|
setTabbarItemActive, // 方法：设置指定项为激活状态
|
|
} = useTabbar()
|
|
```
|
|
|
|
### 方法详解
|
|
|
|
```typescript
|
|
// 获取徽标值
|
|
getTabbarItemValue(name: string): number | undefined
|
|
|
|
// 设置徽标值
|
|
setTabbarItem(name: string, value: number): void
|
|
|
|
// 设置激活状态
|
|
setTabbarItemActive(name: string): void
|
|
```
|
|
|
|
通过以上配置，你可以灵活地管理项目中的自定义 Tabbar，满足各种业务需求。
|