更新记录

1.0.0（2026-09-01）

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

平台兼容性

其他

CSV粘贴导入与字段映射（uni-app x）

适用于后台录入、通讯录导入、库存导入、订单导入等场景。组件在用户设备本地解析CSV文本，支持数据预览、自动匹配业务字段、手动调整映射和输出结构化数据。

特性

• 支持逗号、制表符、分号和竖线分隔符自动识别。
• 支持双引号字段、字段内逗号和连续双引号转义。
• 自动处理空表头和重复表头。
• 目标字段自动匹配、必填字段校验和手动映射。
• 支持外部调用 loadText 传入读取到的CSV文本。
• 零网络请求、零权限、零第三方依赖。

基本用法

<dz-csv-mapper-x
  :target-fields="fields"
  :preview-limit="5"
  @parsed="handleParsed"
  @confirm="handleConfirm"
  @error="handleError"
/>

type CsvTargetField = {
  key: string
  label: string
  required?: boolean
}

const fields: CsvTargetField[] = [
  { key: 'name', label: '姓名', required: true },
  { key: 'mobile', label: '手机号', required: true },
  { key: 'city', label: '城市', required: false }
]

function handleConfirm(payload: UTSJSONObject) {
  const data = payload['data'] as UTSJSONObject[]
  console.log(JSON.stringify(data))
}

外部传入CSV文本

读取文件的方式因平台而异。本组件不申请文件权限，由宿主读取文本后调用：

<dz-csv-mapper-x ref="mapper" :target-fields="fields" />

const mapper = ref<ComponentPublicInstance | null>(null)
// mapper.value?.loadText(csvText, true)

loadText(text, true) 的第二个参数控制传入后是否立即解析。

事件

• parsed：CSV解析完成，返回 headers、rows、delimiter。
• confirm：映射确认完成，返回 data、mapping、source。
• error：解析或必填校验失败，返回中文错误信息。

平台说明

第一版重点验证 Chrome、Android 和微信小程序。iOS与鸿蒙暂标记为待验证，不对未验证平台作兼容承诺。

隐私说明

插件不联网、不申请权限、不采集、不上传、不持久化用户数据。所有CSV内容仅在当前设备内存中处理。