256 lines
7.8 KiB
Markdown
256 lines
7.8 KiB
Markdown
# 文件上传组件 (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` |