OL-LearnPlatform-Frontend/src/components/common/README.md

ImportModal 通用导入组件

一个可复用的数据导入弹窗组件，支持模板下载、文件上传、拖拽上传等功能。

功能特性

• 📄 模板下载：支持下载 Excel 导入模板
• 📤 文件上传：支持点击上传和拖拽上传
• 📊 进度显示：实时显示上传进度
• ✅ 结果反馈：详细的导入结果提示
• 🔒 文件校验：文件格式和大小限制
• 📱 响应式设计：适配不同屏幕尺寸

使用方法

1. 导入组件

<script setup lang="ts">
import ImportModal from '@/components/common/ImportModal.vue';
</script>

2. 在模板中使用

<template>
  <!-- 触发按钮 -->
  <n-button @click="showImportModal = true">导入数据</n-button>
  
  <!-- 导入弹窗 -->
  <ImportModal 
    v-model:show="showImportModal"
    template-name="custom_template.xlsx"
    import-type="custom"
    @success="handleImportSuccess"
    @template-download="handleTemplateDownload"
  />
</template>

3. 处理事件

<script setup lang="ts">
const showImportModal = ref(false);

// 导入成功处理
const handleImportSuccess = (result: any) => {
  console.log('导入结果:', result);
  // 刷新数据列表
  loadData();
};

// 模板下载处理
const handleTemplateDownload = (type?: string) => {
  // 调用下载API
  downloadTemplate(type);
};
</script>

Props

参数	类型	默认值	说明
show	boolean	-	控制弹窗显示/隐藏
templateName	string	'import_template.xlsx'	模板文件名
importType	string	'default'	导入类型标识

Events

事件名	参数	说明
update:show	boolean	弹窗显示状态变化
success	result: ImportResult	导入成功回调
template-download	type?: string	模板下载回调

ImportResult 类型

interface ImportResult {
  success: boolean;
  message: string;
  details?: {
    success: number;
    failed: number;
  };
}

自定义配置

文件限制

• 支持格式：.xlsx, .xls
• 文件大小：最大 10MB
• 同时上传：仅支持单文件

样式自定义

组件使用 scoped 样式，可通过 CSS 变量或深度选择器自定义样式。

API 集成点

组件中预留了以下 API 集成点，需要根据实际项目进行实现：

1. 模板下载 API

   // 在 downloadTemplate 函数中实现
   const downloadTemplate = () => {
     // TODO: 调用模板下载 API
   };
   

2. 文件上传 API

   // 在 handleUpload 函数中实现
   const handleUpload = (options) => {
     // TODO: 调用文件上传 API
   };
   

3. 数据导入 API

   // 在 startImport 函数中实现
   const startImport = async () => {
     // TODO: 调用数据导入 API
   };
   

注意事项

1. 确保后端支持对应的文件格式
2. 模板格式要与后端解析逻辑一致
3. 合理设置文件大小限制
4. 提供清晰的错误提示信息
5. 考虑网络异常情况的处理