daimp-front/sub-government-affairs-service/doc/组件文档.md

# 文件上传组件 (FileUploader)

## 组件说明

文件上传组件用于实现文件的上传、预览和管理功能。支持图片上传、多文件上传、文件预览等功能。

## 基本用法

```vue
<template>
  <file-uploader 
    v-model="fileList" 
    :limit="5"
    accept="image/*"
  />
</template>

<script setup>
import { ref } from 'vue';
const fileList = ref([]);
</script>
```

## Props

| 参数名        | 类型                | 默认值                                               | 说明              |
| ---------- | ----------------- | ------------------------------------------------- | --------------- |
| modelValue | `Array \| String` | `[]`                                              | 绑定值，图片路径数组或单个路径 |
| ossUrl     | `String`          | `'http://gov-cloud.oss-cn-chengdu.aliyuncs.com/'` | 回显时拼接图片完整路径使用   |
| limit      | `Number`          | `5`                                               | 最多上传几张图片        |
| accept     | `String`          | `'image/*'`                                       | 允许上传的文件类型       |
| readonly   | `Boolean`         | `false`                                           | 是否只读模式，不可上传删除   |


## 事件
| 事件名 | 参数 | 说明 |
|-------|------|------|
| update:modelValue | 新的文件列表值（数组或字符串） | 当文件列表发生变化时触发 |

## 插槽
该组件没有提供插槽。

### 数据适配处理

- `selectedFiles`：用于统一处理单文件和多文件场景，读时返回数组，写时根据 `limit` 决定是否回传为字符串或数组。
- `fileList`：用于 `el-upload` 的回显列表，拼接完整 URL。
- `previewList`：用于图片预览的 URL 列表。

## 样式

组件使用了Element Plus的el-upload和el-image-viewer组件，并添加了自定义样式以适应不同的布局需求。

## 依赖项

- `element-plus`
- `@element-plus/icons-vue` 中的 `Plus`
- 自定义 API：`CommonUpload`



# UrlSelect 远程下拉选择组件

该组件基于 `el-select` 和自定义 axios 请求封装，支持从指定接口拉取选项列表，并支持 label/value 字段自定义。

## 功能特性

- 下拉选项从远程接口加载（通过 `url` 和 `params` 指定）
- 支持自定义 label/value 字段名（`labelKey` / `valueKey`）
- 支持插槽透传（可扩展 options 或添加分组）
- 内部使用双向绑定模型 `internalValue` 实现响应式
- 默认使用 `res.data.records` 作为解析逻辑，可自定义 `responseParser`

## 使用示例

```vue
<UrlSelect
  v-model="form.industry"
  url="/api/base/industries"
  :params="{ enabled: true }"
  label-key="name"
  value-key="id"
  placeholder="请选择行业"
/>
```

## Props 参数

| 参数名         | 类型                        | 默认值                      | 说明                           |
| -------------- | --------------------------- | --------------------------- | ------------------------------ |
| modelValue     | `String \| Number \| Array` | `null`                      | 绑定的值                       |
| url            | `String`                    | `null`                      | 请求数据的接口地址             |
| params         | `Object`                    | `{}`                        | 请求时的参数                   |
| labelKey       | `String`                    | `'label'`                   | 数据项中作为 label 显示的字段  |
| valueKey       | `String`                    | `'value'`                   | 数据项中作为 value 的字段      |
| responseParser | `Function`                  | `(res) => res.data.records` | 处理响应数据的函数，需返回数组 |

## 事件说明

组件继承并透传了 `el-select` 的常用事件：

| 事件名              | 说明                         |
| ------------------- | ---------------------------- |
| `update:modelValue` | v-model 绑定更新             |
| `change`            | 选项变化时触发               |
| `blur`              | 失焦时触发                   |
| `focus`             | 聚焦时触发                   |
| `clear`             | 点击清空按钮时触发           |
| `visible-change`    | 下拉框显示/隐藏变化时触发    |
| `remove-tag`        | 多选时移除 tag 触发          |
| `scroll`            | 滚动触发（需设置高度才有效） |

## 核心逻辑说明

### 1. 内部绑定值

```JavaScript
const internalValue = ref(props.modelValue);
watch(() => props.modelValue, (newVal) => internalValue.value = newVal);
watch(internalValue, (newVal) => emit('update:modelValue', newVal));
```

### 2. 拉取远程选项

```JavaScript
async function fetchOptions() {
  if (!props.url) return;
  const res = await request.get(props.url, { params: props.params });
  const records = props.responseParser(res);
  options.value = Array.isArray(records) ? records : [];
}
```

组件挂载时会立即请求一次远程数据。

### 3. 插槽支持

支持透传所有 `$slots`，并提供默认的 `option` 渲染逻辑。也可通过 `option-group` 插槽实现复杂渲染。

## 依赖项

- `element-plus` 的 `el-select`、`el-option`
- 项目中的 `request` 请求封装（例如基于 axios）

## 可拓展点

- 支持分页加载远程选项（下拉滚动触发）
- 支持懒加载（点击展开时再加载）
- 支持 loading/loading-text 状态

---



# AreaSelect.vue 组件文档

## 组件简介

`AreaSelect` 是一个基于 Element Plus 的级联选择组件，封装了行政区域选择功能。支持省/市/县三级联动，数据源通过接口自动获取。

## 使用方式

### 1. 引入组件

```vue
<AreaSelect v-model="areaCodeList" />
```

### 2. 配置示例

```vue
<AreaSelect
  v-model="selectedArea"
  :label="'所属区域：'"
  :placeholder="'请选择区域'"
  :emit-path="true"
  :width="600"
/>
```

------

## Props 参数说明

| 参数名        | 类型              | 默认值           | 说明                                                         |
| ------------- | ----------------- | ---------------- | ------------------------------------------------------------ |
| `modelValue`  | `Array | String`  | `[]`             | 双向绑定的值。如果 `emitPath` 为 `true`，则为数组，否则为字符串。 |
| `label`       | `String`          | `所属行政区域：` | 左侧 label 标签内容。                                        |
| `placeholder` | `String`          | `请选择行政区域` | 选择框中的占位符提示文字。                                   |
| `width`       | `Number | String` | `500`            | 整体组件宽度（单位：px）。                                   |
| `emitPath`    | `Boolean`         | `true`           | 是否返回完整路径的值数组。为 `false` 时只返回最后一级节点的值。 |



------

## Events 说明

| 事件名              | 说明                      |
| ------------------- | ------------------------- |
| `update:modelValue` | 用于 `v-model` 双向绑定。 |



------

## 返回值说明

- 当 `emitPath = true` 时，返回一个数组，例如：

  ```json
  ['530000', '530100', '530102']
  ```

- 当 `emitPath = false` 时，只返回最后一级，例如：

  ```json
  '530102'
  ```

------

## 接口说明

该组件内部自动发起请求：

```
GET /system/area/region?areaCode=530000
```

接口返回行政区域数据，格式如下：

```json
[
  {
    "areaName": "云南省",
    "areaCode": "530000",
    "areaChildVOS": [
      {
        "areaName": "昆明市",
        "areaCode": "530100",
        "areaChildVOS": [...]
      }
    ]
  }
]
```

------

## 注意事项

- 默认展示为“云南省”下的行政区域。
- 默认字段映射为：
  - `label`: `areaName`
  - `value`: `areaCode`
  - `children`: `areaChildVOS`