# 移动端配置化表单/列表组件文档

## 组件概述

这是一个基于 Vue 3 + TypeScript + Vant 4 开发的移动端配置化查询列表组件系统,主要包含以下组件:

- `XCellList`: 列表容器组件
- `XCellListFilter`: 列表筛选组件
- `XFormItem`: 表单项组件
- `XForm`: 表单容器组件
- `XFormGroup`: 表单分组组件

## 功能特性

### 列表功能

- ✅ 下拉刷新
- ✅ 上拉加载
- ✅ 搜索过滤
- ✅ 多条件筛选
- ✅ 排序功能
- ✅ 卡片式布局
- ✅ 批量操作
- ✅ 自定义操作按钮
- ✅ **长按多选功能** ✨

### 表单功能

- ✅ 支持多种表单项类型
- ✅ 表单分组
- ✅ 表单验证
- ✅ 动态显示隐藏
- ✅ 表单联动
- ✅ 数据字典
- ✅ 自定义校验规则

## 多选功能 ✨

### 功能概述

XCellList 组件新增了强大的长按多选功能，支持以下特性：

- **长按触发**：长按卡片 500ms 进入多选模式
- **精确选择**：点击标题切换选中状态，点击卡片其他区域不触发选择
- **视觉反馈**：选中项目有高亮边框和背景色变化
- **操作面板**：底部 ActionSheet 显示自定义操作按钮
- **智能提示**：启用多选功能时显示操作提示
- **按钮禁用**：多选模式下自动禁用其他操作按钮

### 使用方法

#### 基础多选

```vue
<script setup lang="ts">
const multiSelectActions = ref([
  { name: '批量操作', key: 'batchOperation', color: '#000000', icon: 'records-o' }
])

function handleMultiSelectAction(action, selectedIds, selectedItems) {
  console.log('多选操作:', action, selectedIds, selectedItems)
  // 处理批量操作逻辑
}

function handleSelectionChange(selectedItems) {
  console.log('选择变化:', selectedItems)
}
</script>

<template>
  <XCellList
    config-name="listConfig"
    :service-name="serviceName"
    :enable-multi-select="true"
    id-key="rr_id"
    :multi-select-actions="multiSelectActions"
    @multi-select-action="handleMultiSelectAction"
    @selection-change="handleSelectionChange"
  />
</template>
```

#### 自定义多选操作

```vue
<script setup lang="ts">
const multiSelectActions = ref([
  { name: '标记已读', key: 'markRead', color: '#1989fa', icon: 'eye-o' },
  { name: '移动到文件夹', key: 'moveToFolder', color: '#07c160', icon: 'folder-o' },
  { name: '标记重要', key: 'markImportant', color: '#ff976a', icon: 'star-o' }
])

function handleMultiSelectAction(action, selectedIds, selectedItems) {
  switch (action) {
    case 'markRead':
      // 标记已读逻辑
      break
    case 'moveToFolder':
      // 移动到文件夹逻辑
      break
    case 'markImportant':
      // 标记重要逻辑
      break
  }
}
</script>
```

### 多选功能提示

当启用多选功能（`enableMultiSelect: true`）但未进入多选模式时，会在筛选条件下方显示一个提示条：

- 提示内容："长按卡片可进入多选模式"
- 样式：浅灰色背景，信息图标，友好的提示文字
- 进入多选模式后，此提示自动消失，显示多选模式提示条

### 多选模式下的按钮禁用

在多选模式下，以下按钮会被自动禁用：

- 新增按钮（add-action-btn）
- 卡片内的操作按钮（action-button）
- 卡片底部的操作按钮（action-btn）
- 更多按钮（⋯）

这样可以避免在多选过程中误触发其他操作。

## 使用示例

### 基础列表

```vue
<script setup lang="ts">
const serviceName = 'userService'

function handleDetail(item) {
  // 处理详情点击
}
</script>

<template>
  <XCellList
    config-name="listConfig"
    :service-name="serviceName"
    @to-detail="handleDetail"
  />
</template>
```

### 带筛选的表单

```vue
<script setup lang="ts">
const configName = 'searchForm'
const serviceName = 'userService'
const formData = ref({})

function handleSubmit(data) {
  console.log('表单提交:', data)
}
</script>

<template>
  <XFormGroup
    :config-name="configName"
    :service-name="serviceName"
    :group-form-data="formData"
    mode="查询"
    @submit="handleSubmit"
  />
</template>
```

### 表单功能(琉璃配置中的需要勾选的新增和修改)

```vue
<script setup lang="ts">
const configName = 'searchForm'
const serviceName = 'userService'

function addOption() {
  console.log('新增表单')
}
function updateRow(item) {
  console.log('修改表单:', item)
}
</script>

<template>
  <XCellList
    :config-name="configName"
    :service-name="serviceName"
    :custom-add="true"
    :custom-edit="true"
    @update="updateRow"
    @add="addOption"
  />
</template>
```

## API 文档

### XCellList Props

| 参数                   | 说明                   | 类型        | 默认值    |
| ---------------------- | ---------------------- | ----------- | --------- |
| configName             | 配置名称               | string      | -         |
| serviceName            | 服务名称               | string      | -         |
| fixQueryForm           | 固定查询参数           | object      | null      |
| idKey                  | 主键字段               | string      | 'o_id'    |
| customAdd              | 是否采用自定义新增按钮 | boolean     | false     |
| customEdit             | 是否采用自定义修改按钮 | boolean     | false     |
| **enableMultiSelect**  | **是否启用多选功能**   | **boolean** | **false** |
| **multiSelectActions** | **多选操作按钮配置**   | **Array**   | **[]**    |

### XCellList Events

| 事件名                | 说明                                           | 回调参数                                                                  |
| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
| toDetail              | 点击详情时触发                                 | item: 当前项数据                                                          |
| add                   | 点击新增按钮时触发（customAdd为true才会触发）  | -                                                                         |
| update                | 点击修改按钮时触发（customEdit为true才会触发） | item: 当前项数据                                                          |
| **multiSelectAction** | **多选操作时触发**                             | **action: 操作key, selectedIds: 选中ID数组, selectedItems: 选中项目数组** |
| **selectionChange**   | **选择状态变化时触发**                         | **selectedItems: 选中项目数组**                                           |

### 多选操作按钮配置

```typescript
interface MultiSelectAction {
  name: string // 按钮显示名称
  key?: string // 操作标识（可选，默认使用name）
  color?: string // 按钮颜色（可选，默认黑色）
  icon?: string // 按钮图标（可选，默认records-o）
}
```

### XFormGroup Props

| 参数          | 说明     | 类型                       | 默认值 |
| ------------- | -------- | -------------------------- | ------ |
| configName    | 配置名称 | string                     | ''     |
| serviceName   | 服务名称 | string                     | -      |
| groupFormData | 表单数据 | object                     | {}     |
| mode          | 表单模式 | '查询' \| '新增' \| '修改' | '查询' |

### XFormItem Props

| 参数      | 说明         | 类型         | 默认值 |
| --------- | ------------ | ------------ | ------ |
| attr      | 表单项配置   | FormItemAttr | -      |
| form      | 表单数据对象 | object       | -      |
| mode      | 表单模式     | string       | '查询' |
| showLabel | 是否显示标签 | boolean      | true   |

## 配置说明

### 列表配置

```typescript
interface ListConfig {
  // 列配置
  columnJson: {
    // 列类型: mobile_header_column | mobile_subtitle_column | mobile_details_column | mobile_footer_column
    mobileColumnType: string
    // 数据字段
    dataIndex: string
    // 标题
    title: string
    // 展示类型
    slotType?: 'badge' | 'action'
    // 操作按钮配置
    actionArr?: Array<{
      text: string
      func: string
    }>
  }[]

  // 按钮状态
  buttonState: {
    add?: boolean
    edit?: boolean
    delete?: boolean
  }

  // 是否显示排序
  showSortIcon?: boolean

  // 查询表单配置
  formJson: FormItem[]
}
```

### 表单配置

```typescript
interface FormItem {
  // 表单项类型
  type: 'input' | 'select' | 'date' | 'checkbox' | 'radio' | 'switch' | 'textarea' | 'uploader'

  // 字段名
  model: string

  // 标签名
  name: string

  // 校验规则
  rule?: {
    required: string
    type: 'string' | 'number' | 'integer' | 'float'
  }

  // 占位提示
  placeholder?: string

  // 数据源配置
  keyName?: string

  // 是否只读
  readonly?: boolean

  // 是否禁用
  disabled?: boolean
}
```

## 高级功能

### 表单联动

```typescript
// 配置联动显示函数
const showFormItemFunc = `function(form, attr, data, mode) {
  return form.type === '1'
}`

// 配置值变化函数
const dataChangeFunc = `function(form, attr, data, mode) {
  if(form.type === '1') {
    form.name = 'test'
  }
}`
```

### 自定义样式

```typescript
// 配置样式函数
const styleFunctionForValue = `function(value) {
  return {
    color: value > 100 ? 'red' : 'green'
  }
}`
```

## 注意事项

1. 配置名称必须与后端配置一致
2. 表单验证规则需要按照规范配置
3. 自定义函数需要使用字符串形式
4. 数据源配置支持多种方式:

- logic@: 逻辑处理
- config@: 配置数据
- search@: 搜索数据5.对于默认的新增和修改功能，单表已经实现（也可以自定义），多表关联及自定义sql请使用自定义按钮实现
- 配置按钮状态（customAdd、customEdit）为 true
- 监听 add 和 update 事件
- 实现自定义逻辑

## 最佳实践

1. 合理使用表单分组
2. 适当配置表单联动
3. 统一管理配置文件
4. 做好错误处理
5. 优化列表性能

## 常见问题

1. Q: 如何配置自定义校验规则?
   A: 在 rule 中配置 validator 函数

2. Q: 如何实现表单联动?
   A: 使用 showFormItemFunc 和 dataChangeFunc 配置联动逻辑

3. Q: 如何自定义列表样式?
   A: 使用 styleFunctionForValue 配置样式函数

4. **Q: 多选功能如何触发？**
   **A: 长按卡片 500ms 即可进入多选模式**

5. **Q: 如何自定义多选操作按钮？**
   **A: 通过 `multiSelectActions` 属性配置，支持自定义名称、颜色和图标**

6. **Q: 多选模式下如何选择项目？**
   **A: 点击项目标题可以切换选中状态，点击卡片其他区域不会触发选择**

7. **Q: 如何获取选中的项目数据？**
   **A: 监听 `selectionChange` 事件，或通过 `multiSelectAction` 事件获取**

## 更新日志

### v1.0.0

- 初始版本发布
- 支持基础列表功能
- 支持表单配置

### v1.1.0

- 添加表单联动
- 优化列表性能
- 修复已知问题

## 后续规划

1. [ ] 支持更多表单类型
2. [ ] 添加表单预览功能
3. [ ] 优化列表性能
4. [ ] 完善错误处理
5. [ ] 添加单元测试

## 贡献指南

欢迎提交 Issue 和 PR,请遵循以下规范:

1. 遵循代码规范
2. 添加必要的测试
3. 更新相关文档

## 许可证

MIT License