# @docflow/react-activestorage-provider 中文文档

规范地址：https://npmcn.com/package/%40docflow/react-activestorage-provider/

版本：1\.0\.1
npm 元数据更新时间：2024-04-19T11:15:50.274Z
中文译文更新时间：2026-11-12T13:45:35.227Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：74.4 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>= 16\.8\.0
- 首次发布：2024-03-29T17:45:29.193Z
- 最新版本发布：2024-04-19T11:15:50.071Z
- 近 30 天下载量：12855（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

反应组件,可以使用 ActiveStorage 方便地上传文件. 已更新以用于反应 18

## 安装

```sh
npm install @docflow/react-activestorage-provider
```

也可以使用：`pnpm add @docflow/react-activestorage-provider`、`yarn add @docflow/react-activestorage-provider`、`bun add @docflow/react-activestorage-provider`

## README

# @ docflow/ react-活性存储器提供器

[![NPM](https://img.shields.io/npm/v/@docflow/react-activestorage-provider.svg)](https://www.npmjs.com/package/@docflow/react-activestorage-provider)

> \[注\]  
> 这是叉子 `react-activestorage-provider`,在TypeScript和现代React(支持回放18)中重写.
> 
> 有关 `uploads` 包含已完成上传的数组,参见 [变动情况](https://npmcn.com/package/%40docflow/react-activestorage-provider/CHANGELOG.md)。 。 。 .
> 
> 除此之外,这个软件包还提取了 `DirectUploadProvider` 换入新钩子 `useDirectUpload` 用于跳过渲染函数。 余等同为相.

ActiveStorage是 Rails 5.2 的一个惊人的添加, 并且与往常一样, 这个组件旨在使它同样容易从React中被使用.

ActiveStorage Provider处理将文件直接上传到ActiveStorage服务,并将该文件附加到您的模型上. 它使用渲染道具模式来构建自己的上传部件.

## 安装

```bash
npm install --save @docflow/react-activestorage-provider
```

## 使用量

ActiveStorage Provider使得简单上传按钮容易被添加. 当你打电话 `handleUpload` 带有 `FileList` 或数组 `File`s,此组件创建 `Blob` 记录,将文件直接上传到您的存储服务,然后点击您的 Rails 控制器将 blob 附加到您的模型中. (如果你想自己处理附件,例如,提供其他属性, [见下一层 `DirectUploadProvider`](https://npmcn.com/package/%40docflow/react-activestorage-provider/#readme-directuploadprovider). ) (中文(简体) )

```jsx
import ActiveStorageProvider from "@docflow/react-activestorage-provider";

// ...

return (
  <ActiveStorageProvider
    endpoint={{
      path: "/profile",
      model: "User",
      attribute: "avatar",
      method: "PUT",
    }}
    onSubmit={(user) => this.setState({ avatar: user.avatar })}
    render={({ handleUpload, uploads, ready }) => (
      <div>
        <input
          type="file"
          disabled={!ready}
          onChange={(e) => handleUpload(e.currentTarget.files)}
        />

        {uploads.map((upload) => {
          switch (upload.state) {
            case "waiting":
              return (
                <p key={upload.id}>Waiting to upload {upload.file.name}</p>
              );
            case "uploading":
              return (
                <p key={upload.id}>
                  Uploading {upload.file.name}: {upload.progress}%
                </p>
              );
            case "error":
              return (
                <p key={upload.id}>
                  Error uploading {upload.file.name}: {upload.error}
                </p>
              );
            case "finished":
              return (
                <p key={upload.id}>Finished uploading {upload.file.name}</p>
              );
          }
        })}
      </div>
    )}
  />
);
```

### `ActiveStorageProvider` 道具

这些是您配置 ActiveStorage Provider 的选项 .

| 主张 (\* 需要) | 说明 |
| --- | --- |
| `directUploadsPath` | `string`  
直接上传路径到您的 Rails app上, 如果您已覆盖 `ActiveStorage::DirectUploadsController` |
| `endpoint`\* 联合国 | `{ path: string, model: string, attribute: string, method: string, host?: string, port?: string, protocol?: string }`  
请求附上文件的细节 |
| `headers` | `Record<string, string>`  
要添加到请求中的可选信头, 也可以用于覆盖默认信头 |
| `multiple` | `boolean` (默认:虚假)  
组件是否接受多个文件 。 如果是真的,模型应该使用 `has_many_attached` |
| `onBeforeBlobRequest` | `(request: { id: string, file: File, xhr: XMLHttpRequest }) => void`  
允许您修改 blob 请求的回调 |
| `onBeforeStorageRequest` | `(request: { id: string, file: File, xhr: XMLHttpRequest }) => void`  
一个允许您修改存储请求的回调 |
| `onError` | `(error: Response) => void`  
处理服务器在保存您的模型时的错误( QQ400) 响应的回调 |
| `onSubmit`\* 联合国 | `(endpointResponse: unknown) => void`  
服务器响应的回调以成功保存您的模型 |
| `render`\* 联合国 | `(props: RenderProps) => ReactNode`  
上传器的渲染功能 |

### `RenderProps`

这是调用您渲染函数的参数类型 .

```ts
export type RenderProps = {
  /** false while any file is uploading */
  ready: boolean;
  /** uploads in progress */
  uploads: ActiveStorageFileUpload[];
  /** call to initiate an upload */
  handleUpload: (files: FileList | File[]) => unknown;

  /* or, if you want more granular control... */

  /** call to set list of files to be uploaded */
  handleChooseFiles: (files: FileList | File[]) => unknown;
  /** begin the upload of the files in the list */
  handleBeginUpload: () => unknown;
};

export type CustomHeaders = Record<string, string>;
```

## `DirectUploadProvider`

ActiveStorage Provider通过同时照顾上传和附加文件, 使得快速添加“上载”按钮变得简单, 如果你想处理第二步, 附加你的 `Blob` 记录到您的模型,你自己, 你可以使用低级 `DirectUploadProvider`它创建了blob记录,并将用户的文件直接上传到您的存储服务,然后用这些blobs的签名ID打给你。 之后,您可以根据需要创建或更新您的模型.

```jsx
function PostForm() {
  function handleAttachment(signedIds) {
    const body = JSON.stringify({ post: { title: ..., images: signedIds }})
    fetch('/posts.json', { method: 'POST', body })
  }

  return (
    <DirectUploadProvider onSuccess={handleAttachment} render={...} />
  )
}
```

`DirectUploadProvider` 是名导出, 所以

```jsx
import { DirectUploadProvider } from "@docflow/react-activestorage-provider";
```

并使用以下道具:

| 主张 (\* 需要) | 说明 |
| --- | --- |
| `directUploadsPath` | `string`  
直接上传路径到您的 Rails app上, 如果您已覆盖 `ActiveStorage::DirectUploadsController` |
| `headers` | `Record<string, string>`  
在请求中添加的可选标题 |
| `onBeforeBlobRequest` | `(request: { id: string, file: File, xhr: XMLHttpRequest }) => void`  
允许您修改 blob 请求的回调 |
| `onBeforeStorageRequest` | `(request: { id: string, file: File, xhr: XMLHttpRequest }) => void`  
一个允许您修改存储请求的回调 |
| `onSuccess`\* 联合国 | `(signedIds: string[]) => void`  
上传完成后随文件的签名代号调用 |
| `origin` | `{ host?: string, port?: string, protocol?: string }`  
您的铁路服务器的来源 。 默认为您的 React app 正在运行的地方 |
| `render`\* 联合国 | `(props: RenderProps) => ReactNode`  
上传器的渲染功能 |

## `useDirectUpload`

如果您想要使用 `DirectUploadProvider` 使用这个钩子。 它的道具都一样 `DirectUploadProvider`时,除 `render`,并返回与渲染函数接受为参数的同物.

```tsx
import { useDirectUpload } from "@docflow/react-activestorage-provider";

function Uploader() {
  const { handleUpload } = useDirectUpload({
    onSuccess: (signedIds) => console.log(signedIds),
  });

  return (
    <input
      type="file"
      onChange={(e) => e.target.files && handleUpload(e.target.files)}
    />
  );
}
```

## 常见问题

### @docflow/react-activestorage-provider 是什么？

反应组件,可以使用 ActiveStorage 方便地上传文件\. 已更新以用于反应 18

### 如何安装 @docflow/react-activestorage-provider？

在项目目录运行 npm install @docflow/react-activestorage-provider，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>= 16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @docflow/react-activestorage-provider 支持 TypeScript 吗？

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

### @docflow/react-activestorage-provider 支持 ESM 还是 CommonJS？

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

### @docflow/react-activestorage-provider 可以商用吗？

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

### @docflow/react-activestorage-provider 的下载量有多少？

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

### @docflow/react-activestorage-provider 还在维护吗？

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