# @flatfile/adapter 中文文档

规范地址：https://npmcn.com/package/%40flatfile/adapter/

版本：2\.9\.6
npm 元数据更新时间：2026-04-23T23:54:03.433Z
中文译文更新时间：2026-11-14T21:47:29.730Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flatfile/adapter
原文对照：https://npmcn.com/package/%40flatfile/adapter/?lang=original
项目主页：https://flatfile.com/
源码仓库：https://github.com/flatfilers/adapter

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：863 kB，89 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=4\.5
- 运行依赖：11 个
- 首次发布：2020-08-03T21:30:22.576Z
- 最新版本发布：2021-12-01T20:57:01.669Z
- 近 30 天下载量：430462（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 0 个）

## 中文简介

轻量级 TypeScript/JavaScript 适配器,用于使用 Flatfile 的门户网站

## 安装

```sh
npm install @flatfile/adapter
```

也可以使用：`pnpm add @flatfile/adapter`、`yarn add @flatfile/adapter`、`bun add @flatfile/adapter`

## README

# Flatfile.com CSV 导入器适配器

[![Build Status](https://travis-ci.org/FlatFilers/Adapter.svg?branch=master)](https://travis-ci.org/FlatFilers/Adapter) [![Standard Version](https://img.shields.io/badge/release-standard%20version-brightgreen.svg)](https://github.com/conventional-changelog/standard-version) [![dependencies Status](https://img.shields.io/david/FlatFilers/adapter)](https://david-dm.org/FlatFilers/adapter) [![devDependencies Status](https://img.shields.io/david/dev/FlatFilers/adapter)](https://david-dm.org/FlatFilers/adapter?type=dev)

一个简单的适配器,用于优雅地导入数据(CSV, XLS & more) 通过 [flatfile.com (中文(简体) )](https://www.flatfile.com/) (Typescript,ES6,浏览器)

__重要说明:__ 虽然以下信息是起跑的基本方式,但我们建议阅读开发商Docs [https://flatfile.com/developers/javascript/得到启动](https://flatfile.com/developers/javascript/getting-started)

__另注:__ 如果你在使用Angular或React, 我们有特定的软件包。 看看我们 [在 GitHub 上反应软件包](https://github.com/FlatFilers/react-adapter) 财务报告和审定财务报表 [GitHub 上的角包](https://github.com/FlatFilers/angular-adapter)。 。 。 .

> **许可证密钥**
> 
> 为了建立起来 你需要 [创建或签名到您的 flatfile.com 账户](https://flatfile.com/) 并获得许可证钥匙.

#### 更改日志

欲查看有关最新发布和任何小/重大修改的资料,请查看 [这里的更改日志](https://npmcn.com/package/%40flatfile/adapter/CHANGELOG.md)。 。 。 .

> 注:在2.8版中,先前可用的"深入"(用于界面)被移动到根位 `@flatfile/adapter`。 。 。 .

## 利用国家预防机制

如果你不喜欢外部的依赖性,或者你有像Webpack这样的良好的构建系统到位. 您可以安装并使用 Flatfile 作为 npm 包.

```sh
npm i @flatfile/adapter --save
```

## 使用 CDN 软件

最新版本的软件包通过CDN提供,这样你就可以把它扔入自己的网站并开始使用.

```sh
https://unpkg.com/@flatfile/adapter/build/dist/index.min.js
```

## 快速启动

结尾前添加以下代码 `</body>` 标记在您的 html 中.

```html
<script src="https://unpkg.com/@flatfile/adapter/build/dist/index.min.js"></script>

<script>
  const LICENSE_KEY = '00000000-0000-0000-0000-000000000000' // replace this with your license key

  const importer = new FlatfileImporter(LICENSE_KEY, {
    type: 'Robot',
    fields: [
      {
        label: 'Name',
        key: 'name',
        validators: [ { validate: 'unique' } ]
      },
      {
        label: 'Phone',
        key: 'phone',
        alternates: ['number', 'tel'],
        validators: [
          {
            validate: 'regex_matches',
            regex: '^\d{10}$'
          }
        ]
      },
      {
        label: 'Country',
        key: 'country',
        type: 'select',
        options: [
          { value: 'US', label: 'United States' },
          { value: 'CA', label: 'Canada' }
        ]
      }
    ]
  })

  // More info: https://flatfile.com/developers/javascript/getting-started/#the-basics
  importer.setCustomer({
    userId: '1'
  })

  importer.requestDataFromUser().then((results) => {
    importer.displayLoader('Please wait while your data is loading')

    // do something with your data
    setTimeout(() => {
      // console.log(results)

      importer.displaySuccess('You are all done!')
    }, 1000)
  })
</script>
```

## ES6 / 贝贝

```js
const LICENSE_KEY = '00000000-0000-0000-0000-000000000000' // replace this with your license key

const importer = new FlatfileImporter(LICENSE_KEY, {
  type: 'Robot',
  fields: [
    {
      label: 'Name',
      key: 'name'
    }
  ]
})

// More info: https://flatfile.com/developers/javascript/getting-started/#the-basics
importer.setCustomer({
  userId: '1'
})

document.querySelector('button').addEventListener('click', async () => {
  try{
    const results = await importer.requestDataFromUser()

    importer.displayLoader('Please wait while your data is loading')

    // do something with your data
    setTimeout(() => {
      // console.log(results)

      importer.displaySuccess('You are all done!')
    }, 1000)
  }catch(e){
    // handle a failed upload
  }
})
```

## 数据钩子

Flatfile's Data Hooks是一个有用的数据愈合元素,用于在导入过程中自动重排格式,验证和/或更正数据而无需用户手动更正.

详情: [数据钩开始](https://flatfile.com/developers/javascript/datahooks)

```js
const importer = new FlatfileImporter(LICENSE_KEY, {
  type: 'Robot',
  fields: [
    {
      label: 'Name',
      key: 'name'
    }
  ]
})

importer.setCustomer({
  userId: '1'
})

// adding a data hook that will add 'Jr.' to the name in each row
importer.registerRecordHook((row) => {
  // Example row: {name: 'John'}
  const result = {};

  if (row.name) {
    result.name = {
      value: `${row.name} Jr.`
    };
  }

  return result;
});
```

## 主题

他们让你独立控制了Flatfile门户网站的外观和感觉. 您可以在此调整进口商内部的全局样式和单个组件, 以及控制 CSS 伪类 : hover & : 聚焦于按钮 .

详情: [自定义平面文件端口的主题](https://flatfile.com/developers/javascript/themes)

```js
const importer = new FlatfileImporter(LICENSE_KEY, {
  type: 'Robot',
  fields: [
    {
      label: 'Name',
      key: 'name'
    }
  ],
  theme: {
    global: {
      backgroundColor: '#212327',
      textColor: '#c2c3c3',
      primaryTextColor: '#c2c3c3',
      secondaryTextColor: '#c2c3c3',
      successColor: '#c2c3c3',
      warningColor: '#c2c3c3'
    },
    // other keys below
  }
})
```

## 承诺覆盖

Flatfile包括一个基本本土相容的许诺 shim 用于IE支持. 您可以使用以下全局设置, 以您的首选库来覆盖 :

```js
FlatfileImporter.Promise = Bluebird.Promise
```

## 常见问题

### @flatfile/adapter 是什么？

轻量级 TypeScript/JavaScript 适配器,用于使用 Flatfile 的门户网站

### 如何安装 @flatfile/adapter？

在项目目录运行 npm install @flatfile/adapter，或使用 pnpm add / yarn add / bun add。

### @flatfile/adapter 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @flatfile/adapter 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flatfile/adapter 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=4\.5。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flatfile/adapter 可以商用吗？

@flatfile/adapter 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flatfile/adapter 的下载量有多少？

根据 npm 官方下载统计，@flatfile/adapter 在 2026/10/15 – 2026/11/13 这 30 天内被下载 430,462 次，日均约 14,349 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flatfile/adapter 还在维护吗？

最新版本 2\.9\.6 发布于 2021/12/02（4 年前）；至今共发布 41 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/08/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。