@composy/data-import-core

@composy/data-import-core

数据导入映射器核心库，提供可视化的字段映射、数据预览校验与批量导入能力。内置 CSV/JSON/NDJSON 多格式解析器、字段自动映射与转换工具、重复检测与数据验证，并配套轻量的 Web Component 元素（elements/）、DOM 渲染器与样式注入，以及亮/暗两套主题 token，可由 @composy/data-import-vue（Vue 3 适配器）消费，也可被任意框架直接使用。

安装

# pnpm
pnpm add @composy/data-import-core

# npm
npm install @composy/data-import-core

目录结构

基于真实 src/ 布局：

packages/core/
├── src/
│   ├── index.ts                # 入口，聚合所有公开导出
│   ├── core/                   # data-importer.ts（DataImporter + createDataImporter）、event-emitter.ts
│   ├── parsers/                # csv-parser / json-parser / index（parseFile/parseCSV/parseJSON/getSupportedTypes）
│   ├── mappers/                # field-mapper.ts（autoMap/applyTransform/mapRow/模板）
│   ├── validators/             # data-validator.ts（validateData/detectDuplicates/DataValidator）
│   ├── theme/                  # theme-manager.ts、tokens.ts（lightTokens/darkTokens/ThemeTokens）
│   ├── ui/                     # style-manager.ts（injectStyles/removeStyles/cls/clsx）、dom-renderer.ts
│   ├── elements/               # Web Component（LDesignDataImporter/LDesignElement/define/register）
│   ├── constants/              # PREFIX 等常量
│   ├── types/  utils/          # 类型定义、clone 等工具
│   └── ...
├── es/  esm/                 # ESM 产物
├── lib/                      # CJS 产物
└── dist/                     # UMD/浏览器产物

核心 API 详表

严格基于 src/index.ts 的实际导出：

类（class）

函数（function）

类型（type）

常量（constant）

使用示例

根导出与子路径导出（/core、/mappers、/parsers、/theme、/ui、/validators、/types）均可用：

import { createDataImporter } from '@composy/data-import-core'

createDataImporter({
  container: '#data-import',
  targetFields: [
    { key: 'name', label: 'Name', type: 'string', required: true },
    { key: 'email', label: 'Email', type: 'string' },
  ],
})

OPT-105 能力说明

解析器默认支持 .csv、.json、.ndjson 与 .jsonl。parseFile(file, options) 会按扩展名或 MIME 类型选择解析器；CSV 支持自动识别逗号、制表符、分号和竖线分隔符，所有解析流程都可通过 AbortSignal 中止，并可用 maxRows 限制预览规模：

import {
  getAcceptString,
  parseCSV,
  parseFile,
  registerParser,
} from '@composy/data-import-core'

const dispose = registerParser('.tsv', async (file, options) => {
  return parseCSV(file, { ...options, delimiter: '\t' })
})
const controller = new AbortController()
const result = await parseFile(file, {
  signal: controller.signal,
  trimHeaders: true,
  trimValues: true,
  maxRows: 1000,
})
console.log(getAcceptString(), result.totalRows)
dispose()

字段映射可以通过 autoMapWithConfidence 获取分数、匹配原因和歧义标记；FieldMapping.transform 支持数组形式的流水线，内置 trim、大小写、Unicode normalize、日期、枚举和自定义转换。saveMappingTemplate 会记录源列签名与目标 schema 版本，applyMappingTemplate 优先按表头恢复映射，只有无法匹配时才回退到列索引。

大文件或远程校验场景使用 validateDataAsync(rows, mappings, targetFields, customValidator, asyncValidator, options)，通过 signal、maxErrors 和 yieldEvery 控制取消、错误上限及主线程让出。组件级 ImporterInstance.startImport({ signal, dryRun }) 支持试运行和取消；batchSize 控制提交批次，onImport(batch, context) 可使用 context.rowIndexes、context.batchIndex 和 context.signal 做幂等提交，重复策略为 skip 时会在 ImportResult.skipped 与进度事件中单独统计。

在 iframe 或 shadow DOM 中创建实例时可以传入 document，渲染器会使用容器所属 document 创建节点并把样式注入正确的 root；上传、步骤、预览、错误和进度区域同时提供基础 ARIA 语义。

构建脚本 & 验证命令

# Build with @composy/builder + rolldown
pnpm --dir packages/core run build

# Type checks
pnpm --dir packages/core run type-check
pnpm --dir packages/core run type-check:cjs

# Strict ESLint
pnpm --dir packages/core run lint:check

# Aggregate workspace checks
pnpm build
pnpm type-check
pnpm lint:check

# 发布
pnpm release             # ldesign-release publish --package-dir .

Builder, ESLint, and ESM/CJS TypeScript authority configs are in .ldesign/. The root tsconfig.json and tsconfig.cjs.json remain compatibility entry points.

产物说明

统一由 @composy/builder（ldesign-builder build）生成：

• es/ — ESM 产物，import 与默认入口；含 .d.ts 类型声明
• esm/ — ESM 别名产物
• lib/ — CJS 产物（.cjs），require 入口
• dist/ — UMD/浏览器产物（index.min.js），unpkg / jsdelivr / browser 字段指向

files 白名单发布 es/lib/esm/dist/README.md。

备注

• 作为 @composy/data-import-vue 的底层能力：本包保持框架无关，提供解析、映射、校验、主题与 DOM 渲染逻辑，组件封装由 Vue 适配器完成。
• elements/ 目录内含 Web Component 元素（LDesignElement / LDesignDataImporter / define / register），仓库规范要求的自定义元素实现。
• 解析器（CSV/JSON）与字段映射器均为独立模块，可单独使用。
• 无运行时 peerDependencies；@composy/builder、@composy/testing、@composy/release 仅为开发依赖。
• 完整类型定义见 src/types/index.ts。
• 发布源为私有 registry http://npm.longrise.cn:6286/。