# @csvbox/react 中文文档

规范地址：https://npmcn.com/package/%40csvbox/react/

版本：2\.0\.0
npm 元数据更新时间：2026-10-26T12:57:28.960Z
中文译文更新时间：2026-11-11T03:32:27.078Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40csvbox/react
原文对照：https://npmcn.com/package/%40csvbox/react/?lang=original
项目主页：https://github.com/csvbox-io/react#readme
源码仓库：https://github.com/csvbox-io/react

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

- 包体积（解压后）：87.5 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10
- 运行依赖：1 个
- peer 依赖：react ^16\.13\.1 \|\| ^17\.0\.2 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^16\.13\.1 \|\| ^17\.0\.2 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2021-07-19T10:31:37.569Z
- 最新版本发布：2026-10-26T12:57:27.708Z
- 近 30 天下载量：110042（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 4 个）

## 中文简介

Csvbox.io 的反应适配器

## 安装

```sh
npm install @csvbox/react
```

也可以使用：`pnpm add @csvbox/react`、`yarn add @csvbox/react`、`bun add @csvbox/react`

## README

# @ csvbox/ 反应

> Csvbox.io 的反应适配器

[![NPM](https://img.shields.io/npm/v/@csvbox/react.svg)](https://www.npmjs.com/package/@csvbox/react) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com/)

## 贝壳

```bash
npm install @csvbox/react
```

## 导入

```js
import { CSVBoxButton } from '@csvbox/react'
```

## 使用量

```jsx
<CSVBoxButton
  licenseKey="Sheet license key"
  user={{
    user_id: "default123"
  }}
  onImport={(result, data) => {
    if(result){
      console.log("success");
      console.log(data.row_success + " rows uploaded");
      //custom code
    }else{
      console.log("fail");
      //custom code
    }
  }}
>
  Import
</CSVBoxButton>
```

## 导入您已有的文件

`openModalWithFile(file)` 在 `File` 自己的页面是持有—— 从您的 自己的投放目标,你自己的文件输入,任何东西——而不是进口商的文件取取器. 这个 文件仍然通过导入者的扩展名、工作表和大小检查 picker, 不是验证.

通过一个参考:

```jsx
const importer = useRef(null)

<CSVBoxButton ref={importer} licenseKey="Sheet license key" user={{ user_id: "default123" }} onImport={onImport}>
  Import
</CSVBoxButton>

<input type="file" onChange={(e) => importer.current.openModalWithFile(e.target.files[0])} />
```

或从 `render` prop,它与它的第三个论点具有相同的功能:

```jsx
<CSVBoxButton
  licenseKey="Sheet license key"
  user={{ user_id: "default123" }}
  onImport={onImport}
  render={(launch, isLoading, launchWithFile) => (
    <div
      onDragOver={(e) => e.preventDefault()}
      onDrop={(e) => {
        e.preventDefault()
        launchWithFile(e.dataTransfer.files[0])
      }}
    >
      Drop a spreadsheet here, or <button disabled={isLoading} onClick={launch}>browse</button>
    </div>
  )}
/>
```

进口商可以拒绝交给的文件 并说为什么在控制台警告中 (单位:千美元)`[csvbox] importer declined the supplied file: <reason>`:

-   `import-in-progress` - 进口商已打开其上传步骤,或仍在读 早先的文件 。 已经打开的导入仍然打开 .
-   `modal-closing` ——文件到达时进口商关门.
-   `import-file-url-configured` ——工作表的设置是为了从URL上加载自己的文件.

传出 a `File`,而不是一个 `Blob`(单位:千美元) `Blob` 没有名字可以读取扩展, 和任何 不是一个 `File` 被忽略.

当输入方重定向到另一个主机时( 数据定位表做此操作), 文件会被发送到主机, 输入方实际上最终会打开, 只要主机是您的输入域或 `<region>-<your domain>` (例如 `eu-app.csvbox.io` 页:1 `app.csvbox.io`) (中文(简体) ). 文件从不会发送给其他主机 .

如果进口商在大约8秒内(例如,由于它重定向到一个没有遵循该命名的主机,或者它太老了,无法知道消息)不回答所提供的文件,则进口商被收起,其他按钮再次被启用,控制台说 `[csvbox] the importer did not respond to the supplied file`。 。 。 .

## 一页上的几个进口商

当一个进口商打开(或仍在装入以打开)时,页面上其他每个 CSVBox 实例的按钮被禁用直到关闭,因此两个进口商不会意外打开. 在反应中 `render` 道具( r)`isLoading`) 也为 `true` 在那种状态下,所以自定义触发器可以同样的方式自禁.

从代码中开设第二个进口商(`openModal()` 或者说 `openModalWithFile()`)仍然有可能。 最后一个打开的进口商显示在其他进口商的上方,关闭后显示下面的进口商.

## 进口时关闭进口商

如果您的用户提交文件, 然后在导入完成前关闭导入者, 则导入继续, 并且您 `onImport` 调用完成后仍随结果调用. 进口商下次打开时会重新装入.

## 读取

关于用法,请参见指南 [https://help.csvbox.io/getting-started #2-install-code 互联网档案馆的存檔,存档日期2013-12-2](https://help.csvbox.io/getting-started#2-install-code)

## 许可证

麻省理工学院 [csvbox-io (英语)](https://github.com/csvbox-io)

## 常见问题

### @csvbox/react 是什么？

Csvbox\.io 的反应适配器

### 如何安装 @csvbox/react？

在项目目录运行 npm install @csvbox/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.13\.1 \|\| ^17\.0\.2 \|\| ^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^16\.13\.1 \|\| ^17\.0\.2 \|\| ^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @csvbox/react 支持 TypeScript 吗？

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

### @csvbox/react 支持 ESM 还是 CommonJS？

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

### @csvbox/react 需要什么版本的 Node\.js？

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

### @csvbox/react 可以商用吗？

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

### @csvbox/react 的下载量有多少？

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

### @csvbox/react 还在维护吗？

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