import{_ as i,o as a,c as t,a2 as n}from"./chunks/framework.BbmSSMjL.js";const o=JSON.parse('{"title":"7.5 前端文件组件","description":"","frontmatter":{},"headers":[],"relativePath":"zh/tools/file-components.md","filePath":"zh/tools/file-components.md"}'),h={name:"zh/tools/file-components.md"};function l(k,s,p,e,d,r){return a(),t("div",null,[...s[0]||(s[0]=[n(`

7.5 前端文件组件

概述

本节介绍前端项目（独立 NaiveVue 仓库）中的文件处理组件，包括上传组件（BasicUpload）、富文本编辑器（Editor）与 Excel 导入导出组件的使用方法。组件封装了 7.1 文件上传全流程的接口调用。

Upload 上传组件

vue

<template>
  <BasicUpload
    :value="formData.avatar"
    :action="uploadUrl"
    :maxNumber="1"
    :data="{ type: 'image' }"
    @uploadChange="handleUploadChange"
  />
</template>

<script setup>
import { BasicUpload } from '@/components/Upload';

const uploadUrl = '/api/upload/uploadFile';
const formData = ref({ avatar: [] });

// 上传/删除后回写文件值数组（相对路径）
const handleUploadChange = (files) => {
  formData.value.avatar = files;
};
</script>

字段值约定

BasicUpload 绑定的值（value 数组）建议存 filePath（相对路径）——提交表单后由 Service 的 fileFields 归一化，读取时自动补全 FILE_DOMAIN_URL 域名。上传需携带 Authorization: Bearer <token> 请求头（组件内部或 http 封装统一处理）。

常用属性

属性	说明
`value`（配合 `@uploadChange` 回写）	绑定的文件值数组（相对路径）
`action`	上传接口地址（`/api/upload/uploadFile`）
`maxNumber`	最大上传数量（1 = 单文件，如头像）
`:data="{ type: 'image' }"`	上传类型（image 校验图片后缀白名单，两类均存入 `temp/` 临时目录）

Editor 富文本编辑器

vue

<template>
  <Editor v-model="formData.content" />
</template>

<script setup>
import Editor from '@/components/Editor/index.vue';

const formData = ref({ content: '' });
</script>

富文本字段

编辑器产出的 HTML 提交后，由 Service 的 contentFields 配置触发 [IMG_URL] 占位符处理（见 7.3 富文本处理）。编辑器粘贴内容建议开启安全过滤模式防 XSS。

Excel 导入组件

vue

<template>
  <ImportExcel @success="handleImportSuccess" />
</template>

<script setup>
import ImportExcel from '@/components/Excel/src/ImportExcel.vue';

const handleImportSuccess = (data) => {
  // data 为解析后的数组（前端本地解析预览场景）
  console.log(data);
};
</script>

前端解析 vs 后端导入

后端导入（推荐，走业务校验）：n-upload 直传 /api/{module}/import，由 Service 逐行 add()（字典反查、唯一校验、事务），见 7.4 数据导入导出；
前端解析：ImportExcel 组件用 xlsx 库本地解析为数组，适合导入前预览、无业务校验的场景。

Excel 导出

typescript

import { jsonToSheetXlsx } from '@/components/Excel/src/Export2Excel';

// 前端直接导出（本地数据组装为 Excel，不经过后端）
jsonToSheetXlsx({
  data: tableData.value,
  header: {
    name: '名称',
    statusText: '状态',
    createTime: '创建时间',
  },
  filename: '导出数据.xlsx',
});

typescript

// 后端导出（大数据量 / 需要权限控制时）：调用模块导出接口拿文件 URL
const res = await exampleExport(params);   // 文件地址
window.open(res);

两种导出方式选择

方式	适用场景	特点
前端 `jsonToSheetXlsx`	当前页数据、无权限要求	零后端交互、即时下载
后端 `/export` 接口	全量数据、需权限与字典翻译	`#[Permission]` 控制、`serializeMaps` 枚举转文字、分批防溢出

`,18)])])}const g=i(h,[["render",l]]);export{o as __pageData,g as default};

7.5 前端文件组件 ​

Upload 上传组件 ​

常用属性 ​

Editor 富文本编辑器 ​

Excel 导入组件 ​

Excel 导出 ​