更新记录

1.1.0（2026-09-02）

• 新增CSV/TXT文件选择与UTF-8文本读取。
• 新增文本、数字、整数、布尔值和日期类型转换。
• 新增必填、唯一值、正则格式校验与字段别名自动匹配。
• 新增有效行/错误行分离、错误明细展示和错误CSV复制导出。
• 新增字段映射方案本地保存与自动恢复。
• 优化未闭合引号、文件大小和读取失败提示。

1.0.0（2026-09-01）

首次发布，支持CSV解析、分隔符自动识别、数据预览、字段自动匹配、手动映射和结构化数据输出。

平台兼容性

uni-app x(5.24)

其他

CSV文件导入、校验与字段映射（uni-app x）

适用于通讯录、商品、库存、订单和后台数据导入。组件支持直接选择CSV/TXT文件或粘贴CSV文本，在设备本地完成解析、字段映射、类型转换、数据校验和错误行整理。

主要功能

• 选择UTF-8编码的CSV/TXT文件，默认最大5MB，也可粘贴文本。
• 自动识别逗号、制表符、分号和竖线分隔符。
• 正确处理双引号字段、字段内换行、逗号和连续双引号转义。
• 通过字段名称、key或别名自动匹配，支持手动调整。
• 支持文本、数字、整数、布尔值和日期类型转换。
• 支持必填、唯一值和正则表达式格式校验。
• 有效行和错误行自动分离，展示具体行号与原因。
• 一键复制带“错误原因”列的错误CSV，也可通过事件自行保存。
• 映射方案保存在设备本地，下次导入相同表头时自动恢复。
• 零网络请求、零第三方依赖，CSV数据不上传服务器。

基本用法

<dz-csv-mapper-x
  :target-fields="fields"
  :preview-limit="5"
  storage-key="customer-import-mapping"
  @parsed="handleParsed"
  @validated="handleValidated"
  @confirm="handleConfirm"
  @export-errors="handleExportErrors"
  @error="handleError"
/>

type CsvTargetField = {
  key: string
  label: string
  required?: boolean
  type?: string
  unique?: boolean
  pattern?: string
  patternMessage?: string
  aliases?: string[]
}

const fields: CsvTargetField[] = [
  { key: 'name', label: '姓名', required: true, aliases: ['客户姓名', '联系人'] },
  {
    key: 'mobile',
    label: '手机号',
    required: true,
    unique: true,
    pattern: '^1\\d{10}$',
    patternMessage: '请输入11位手机号',
    aliases: ['手机', '电话']
  },
  { key: 'age', label: '年龄', type: 'integer' },
  { key: 'enabled', label: '启用', type: 'boolean' },
  { key: 'birthday', label: '生日', type: 'date' },
  { key: 'city', label: '城市' }
]

function handleConfirm(payload: UTSJSONObject) {
  const validData = payload['data'] as UTSJSONObject[]
  const invalidRows = payload['invalidRows'] as UTSJSONObject[]
  const errors = payload['errors'] as UTSJSONObject[]
  console.log(`有效${validData.length}行，错误${invalidRows.length}行`)
}

字段配置

布尔值支持：true/false、1/0、yes/no、是/否。日期转换成功后输出ISO 8601字符串。

组件属性

事件

• parsed：解析完成，返回 headers、rows、delimiter。
• validated：校验完成，返回全部错误明细。
• confirm：返回 data（有效数据）、invalidRows、errors、mapping和source。
• export-errors：点击复制错误CSV时返回 csv和errors，宿主可另行保存或分享文件。
• error：解析、文件读取或配置操作失败。

公开方法

• loadText(text, autoParse)：由宿主传入CSV文本。
• parseInput()：解析当前文本。
• getMappedData()：执行校验并返回全部转换后数据。
• getInvalidCsv()：取得带错误原因的CSV字符串。
• saveMapping() / restoreMapping()：保存或恢复映射方案。

平台与隐私

文件选择依赖 uni.chooseFile，最低要求HBuilderX 5.24。当前重点支持Chrome、Android和微信小程序；iOS与鸿蒙暂标记为待验证。

插件只读取用户主动选择的本地文件。CSV内容只在设备内存中处理；映射关系使用 uni.setStorageSync 保存在设备本地，不联网、不上传、不采集用户数据。