<!--
 * @Author: chenqihang 592956383@qq.com
 * @Date: 2024-11-11 18:06:07
 * @LastEditors: chenqihang 592956383@qq.com
 * @LastEditTime: 2024-11-12 15:38:05
 * @FilePath: \admin-web\src\components\PageContainer\README.MD
 * @Description: PageContainer 页面容器组件文档
-->

# PageContainer 页面容器组件

## 简介

PageContainer 是一个功能丰富的页面容器组件，集成了数据筛选、表格展示、分页管理等常用功能，适用于中后台管理系统的列表页面开发。

## 功能特性

- 🔍 灵活的筛选系统

  - 支持输入框、下拉框、多选下拉框、日期选择器等多种筛选方式
  - 支持自定义筛选项宽度和占位文本
  - 支持禁用和可关闭选项

- 📊 强大的表格功能
  - 支持列筛选、排序功能
  - 支持表格列自定义配置
  - 内置表格列 tooltip 效果
  - 支持自定义操作列
- 📑 完善的分页管理

  - 支持自定义分页大小
  - 支持页码跳转
  - 支持数据总量显示

- 🎨 丰富的自定义区域
  - 支持表格头部自定义（左右两侧）
  - 支持自定义列渲染

## 使用示例

### 基础用法

```vue
<template>
  <PageContainer
    :filter-conditions="filterConditions"
    :table-data="tableData"
    :columns="columns"
    :loading="loading"
    :pagination="pagination"
    :table-props="tableProps"
    @filter-change="handleFilter"
    @sort-change="handleSort"
    @search-change="handleSearch"
    @page-change="handlePage"
  >
    <!-- 表格头部自定义内容 -->
    <template #header-left>
      <button>新增</button>
    </template>

    <!-- 表格头部右侧操作区 -->
    <!-- ⚠️ **特别注意**：
     1. 列筛选功能：
       - 已内置集成，通过 showSetting 属性控制显示/隐藏
       - 默认展示所有列
       - 如需自定义控制columnController，请通过 tableProps 属性进行配置

     2. 按钮布局：
       - 建议最多放置 3 个操作按钮
       - 超过 3 个按钮时，请自行实现下拉菜单样式
       - 下拉菜单的样式与交互需参照 UI 设计规范
    -->
    <template #header-right>
      <button>批量导出</button>
    </template>

    <!-- 自定义列内容 -->
    <template #colKey="{ row }">
      <span>{{ row.customContent }}</span>
    </template>
  </PageContainer>
</template>
```

## API 文档

### Props 属性

| 属性名           | 说明                       | 类型                  | 默认值                             |
| ---------------- | -------------------------- | --------------------- | ---------------------------------- |
| filterConditions | 筛选条件配置列表           | `FilterItemProp[]`    | `[]`                               |
| tableData        | 表格数据源                 | `any[]`               | `[]`                               |
| columns          | 表格列配置                 | `PrimaryTableCol[]`   | `[]`                               |
| loading          | 数据加载状态               | `boolean`             | `false`                            |
| showTableHeader  | 是否显示表格头部工具栏     | `boolean`             | `true`                             |
| showPagination   | 是否显示分页器             | `boolean`             | `true`                             |
| showSetting      | 是否显示列配置按钮         | `boolean`             | `true`                             |
| pagination       | 分页配置对象               | `Pagination`          | `{ page: 1, limit: 10, total: 0 }` |
| pageSizes        | 可选的每页条数             | `number[]`            | `[10, 20, 50, 100]`                |
| tableProps       | TDesign Table 组件原生属性 | `Partial<TableProps>` | `{ hover: true, resizable: true }` |
| filtersProps     | 筛选器组件原生属性         | `Record<string, any>` | `{}`                               |

### Events 事件

| 事件名            | 说明                     | 回调参数类型                                  |
| ----------------- | ------------------------ | --------------------------------------------- |
| filter-change     | 表格列筛选条件变化时触发 | `(filters: Record<string, any>)`              |
| search-change     | 搜索条件变化时触发       | `(params: Record<string, any>)`               |
| sort-change       | 排序条件变化时触发       | `(sort: Record<string, any>)`                 |
| page-change       | 分页信息变化时触发       | `(pageInfo: { page: number; limit: number })` |
| update:pagination | 更新分页数据时触发       | `(pagination: Pagination)`                    |

### Slots 插槽

| 插槽名       | 说明                                  | 作用域参数     |
| ------------ | ------------------------------------- | -------------- |
| header-left  | 表格头部左侧自定义区域                | -              |
| header-right | 表格头部右侧自定义区域                | -              |
| colKey       | 自定义表格列内容（colKey 为列的 key） | `{ row: any }` |

### TypeScript 类型定义

```typescript
// 分页配置接口
interface Pagination {
  page: number // 当前页码
  limit: number // 每页条数
  total?: number // 数据总条数
}

// 筛选项配置接口
interface FilterItemProp {
  label: string // 筛选项标签文本
  prop: string // 筛选项属性名
  type: 'input' | 'select' | 'multiple-select' | 'date' // 筛选项类型
  str?: string // 单选/输入框的值
  values?: (string | number)[] // 多选值数组
  width?: number // 筛选项宽度
  selectData?: SelectOption[] // 下拉选项数据
  closable?: boolean // 是否可关闭
  placeholder?: string // 占位提示文本
  disabled?: boolean // 是否禁用
}

// 下拉选项接口
interface SelectOption {
  label: string // 选项显示文本
  value: string | number // 选项值
}
```
