# 通用文件夹管理组件库
这是一个可复用的文件夹管理 UI 组件库，提供了完整的文件夹树、面包屑导航、拖放操作等功能。可用于管理各种类型的项目，如 Persona、模板、知识库等。
## 组件列表
| 组件 | 说明 |
|------|------|
| `BaseFolderTree` | 文件夹树组件，支持搜索、展开/折叠、右键菜单、拖放 |
| `BaseFolderTreeNode` | 文件夹树节点组件（内部使用） |
| `BaseFolderCard` | 文件夹卡片组件，用于网格布局展示 |
| `BaseFolderBreadcrumb` | 面包屑导航组件 |
| `BaseCreateFolderDialog` | 创建文件夹对话框 |
| `BaseMoveToFolderDialog` | 移动项目到文件夹对话框 |
| `BaseMoveTargetNode` | 移动对话框中的目标文件夹节点（内部使用） |
## Composable
### `useFolderManager`
提供文件夹管理的核心逻辑，包括状态管理、导航、CRUD 操作等。
```typescript
import { useFolderManager } from '@/components/folder';
const {
// 状态
folderTree,
currentFolderId,
currentFolders,
breadcrumbPath,
expandedFolderIds,
loading,
treeLoading,
// 计算属性
currentFolderName,
breadcrumbItems,
// 方法
loadFolderTree,
navigateToFolder,
refreshCurrentFolder,
createFolder,
updateFolder,
deleteFolder,
moveFolder,
toggleFolderExpansion,
setFolderExpansion,
findFolderInTree,
findPathToFolder,
filterTreeBySearch,
} = useFolderManager({
operations: {
loadFolderTree: async () => {
const response = await axios.get('/api/your-module/folder/tree');
return response.data.data;
},
loadSubFolders: async (parentId) => {
const response = await axios.get('/api/your-module/folder/list', {
params: { parent_id: parentId ?? '' }
});
return response.data.data;
},
createFolder: async (data) => {
const response = await axios.post('/api/your-module/folder/create', data);
return response.data.data.folder;
},
updateFolder: async (data) => {
await axios.post('/api/your-module/folder/update', data);
},
deleteFolder: async (folderId) => {
await axios.post('/api/your-module/folder/delete', { folder_id: folderId });
},
},
rootFolderName: '根目录',
autoLoad: true,
});
```
## 使用示例
### 基础用法
```vue
```
## 类型定义
```typescript
// 文件夹基础接口
interface Folder {
folder_id: string;
name: string;
parent_id: string | null;
description?: string | null;
sort_order?: number;
created_at?: string;
updated_at?: string;
}
// 文件夹树节点接口
interface FolderTreeNode extends Folder {
children: FolderTreeNode[];
}
// 拖放事件数据
interface DropEventData {
item_id: string;
item_type: string;
target_folder_id: string | null;
source_data?: any;
}
// 创建文件夹数据
interface CreateFolderData {
name: string;
parent_id?: string | null;
description?: string;
}
```
## 国际化支持
所有组件都支持通过 `labels` prop 自定义文本，方便集成到不同的国际化方案中：
```vue
```
## 拖放支持
组件内置了拖放支持，可以通过 `acceptDropTypes` 指定接受的拖放类型：
```vue
```
## 与 Pinia Store 集成
如果你更喜欢使用 Pinia Store 管理状态，可以参考现有的 `personaStore.ts` 实现：
```typescript
// stores/myFolderStore.ts
import { defineStore } from 'pinia';
import type { FolderTreeNode, Folder } from '@/components/folder';
export const useMyFolderStore = defineStore('myFolder', {
state: () => ({
folderTree: [] as FolderTreeNode[],
currentFolderId: null as string | null,
currentFolders: [] as Folder[],
// ...
}),
actions: {
async loadFolderTree() {
// ...
},
// ...
},
});
```