# @box/uploads-manager 中文文档

规范地址：https://npmcn.com/package/%40box/uploads-manager/

版本：2\.5\.40
npm 元数据更新时间：2026-11-06T03:57:47.317Z
中文译文更新时间：2026-11-08T12:47:11.006Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40box/uploads-manager
原文对照：https://npmcn.com/package/%40box/uploads-manager/?lang=original

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

- 包体积（解压后）：494 kB，81 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0，react-dom ^18\.0\.0，react-intl ^6\.4\.2，@box/item-icon ^3\.6\.39，@box/blueprint-web ^18\.10\.3，react-aria-components 1\.16\.0，@box/blueprint-web-assets ^5\.15\.0
- 首次发布：2026-05-14T14:23:12.111Z
- 最新版本发布：2026-11-06T03:57:46.586Z
- 近 30 天下载量：31089（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：212（近 12 个月 212 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @box/uploads-manager
```

也可以使用：`pnpm add @box/uploads-manager`、`yarn add @box/uploads-manager`、`bun add @box/uploads-manager`

## README

-   [上传管理器](https://npmcn.com/package/%40box/uploads-manager/#readme-uploads-manager)
    -   [API 概览](https://npmcn.com/package/%40box/uploads-manager/#readme-api-overview)
    -   [类型](https://npmcn.com/package/%40box/uploads-manager/#readme-types)
        -   [`UploadItemStatus`](https://npmcn.com/package/%40box/uploads-manager/#readme-uploaditemstatus)
        -   [`UploadItem`](https://npmcn.com/package/%40box/uploads-manager/#readme-uploaditem)
        -   [`UploadsManagerProps`](https://npmcn.com/package/%40box/uploads-manager/#readme-uploadsmanagerprops)
    -   [使用量](https://npmcn.com/package/%40box/uploads-manager/#readme-usage)
    -   [运行命令](https://npmcn.com/package/%40box/uploads-manager/#readme-running-commands)
    -   [可用命令](https://npmcn.com/package/%40box/uploads-manager/#readme-available-commands)
    -   [所有权](https://npmcn.com/package/%40box/uploads-manager/#readme-ownership)
    -   [翻译](https://npmcn.com/package/%40box/uploads-manager/#readme-translations)

# 上传管理器

显示带有相撞面板的文件和文件夹的上传进度、每个项目动作和批量操作。 组件从 `items` 内部阵列.

## API 概览

消费的应用通过一个 `items: UploadItem[]` 数组和动作召回。 没有获取数据,没有外部上下文依赖性(但除外) `IntlProvider`) (中文(简体) ).

```tsx
<UploadsManager
    isExpanded={isExpanded}
    onToggle={() => setIsExpanded(prev => !prev)}
    items={items}
    onCancelAll={handleCancelAll}
    onRetryAll={handleRetryAll}
    onItemCancel={handleItemCancel}
    onItemRetry={handleItemRetry}
    onItemRemove={handleItemRemove}
    onItemOpen={handleItemOpen}
    onItemShare={handleItemShare}
/>
```

## 类型

### `UploadItemStatus`

```ts
type UploadItemStatus = 'pending' | 'uploading' | 'staged' | 'complete' | 'error' | 'canceled';
```

### `UploadItem`

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `id` | `string` | 对 | 此上传的独特标识符 |
| `name` | `string` | 对 | 显示文件或文件夹的名称 |
| `extension` | `string` | 对 | 文件类型的图标的文件扩展名 |
| `progress` | `number` | 对 | 上传进度百分比( 0- 100) |
| `status` | `UploadItemStatus` | 对 | 目前情况 |
| `isFolder` | `boolean` | 没有 | 此项目是否是一个文件夹( 默认 ): `false`(中文(简体) ) |
| `errorMessage` | `string` | 没有 | 状态时显示的错误消息 `'error'` |
| `versionNumber` | `string` | 没有 | 完成上传的版本标签(例如. `"V2"`(中文(简体) ) |
| `isRetryable` | `boolean` | 没有 | 是否为出错的项目提供重试( 默认 ): `true`(中文(简体) ) |

### `UploadsManagerProps`

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `isExpanded` | `boolean` | 对 | 是否扩大面板 |
| `onToggle` | `() => void` | 对 | 切换扩展/缩放 |
| `items` | `UploadItem[]` | 对 | 上传要显示的项目 |
| `onCancelAll` | `() => void` | 没有 | 取消所有待定/ 正在上传 |
| `onRetryAll` | `() => void` | 没有 | 重试所有出错的项目( 标签为“ 全部重试 ) |
| `onItemCancel` | `(itemId: string) => void` | 没有 | 取消单个项目 |
| `onItemRetry` | `(itemId: string) => void` | 没有 | 重试单个项目( 标签为" 重试") |
| `onItemRemove` | `(itemId: string) => void` | 没有 | 删除已完工/已磨损/已卸载的项目 |
| `onItemOpen` | `(itemId: string) => void` | 没有 | 打开已完成的项目 |
| `onItemShare` | `(itemId: string) => void` | 没有 | 通过链接共享已完成的项目 |

## 使用量

```tsx
import { UploadsManager } from '@box/uploads-manager';
import type { UploadItem } from '@box/uploads-manager';

const items: UploadItem[] = [
    { id: '1', name: 'report.pdf', extension: 'pdf', progress: 100, status: 'complete' },
    { id: '2', name: 'photo.png', extension: 'png', progress: 45, status: 'uploading' },
    {
        id: '3',
        name: 'data.csv',
        extension: 'csv',
        progress: 0,
        status: 'error',
        errorMessage: 'Upload failed',
        isRetryable: true,
    },
];

function App() {
    const [isExpanded, setIsExpanded] = useState(true);

    return (
        <UploadsManager
            isExpanded={isExpanded}
            onToggle={() => setIsExpanded(prev => !prev)}
            items={items}
            onCancelAll={() => {
                /* cancel pending + in-progress uploads */
            }}
            onRetryAll={() => {
                /* retry all errored items */
            }}
            onItemCancel={id => {
                /* cancel single item */
            }}
            onItemRetry={id => {
                /* retry single item */
            }}
            onItemRemove={id => {
                /* remove item from list */
            }}
        />
    );
}
```

## 运行命令

您的终端应该留在寄存器根目录的位置, 即 `frontend-mono`。允许 Nx 运行针对您的项目的行动,或者在必要时运行多个项目. 不导航到 `packages/group-shared-features/uploads-manager` 以运行命令.

项目的命令使用 Nx 使用的语法运行 :

```
Syntax: yarn nx <target name> <project name> <option overrides>
                      |              |                |
Example: yarn nx    test         products         --watch
```

## 可用命令

所有使用 Nx 的命令都可以在 `project.json` 文档.

-   `nx storybook uploads-manager` - 发射UI组件的开发环境.
-   `nx build-storybook uploads-manager` - 建立静态版本的故事书 与所有的故事.
-   `nx build uploads-manager` - 使用 `shared-feature-builder` 执行器从 `automation` 软件包.
-   `nx build uploads-manager --watch` - 以启用 -- watch 旗构建软件包,用于重建 `dist` 内容基于 `src`。 。 。 .
-   `nx lint uploads-manager` - 运行linter过包文件.
-   `nx test uploads-manager` - 进行故事书测试(视觉/互动)和笑话测试,最后编写报道报告.
-   `nx test-storybook uploads-manager` - 做故事书测试 需要先在单独的终端开始故事本才能成功.
-   `nx test-storybook-local-coverage uploads-manager` - 进行故事书测试,并在最后制作报道报告。 需要运行的故事书实例.
-   `nx test-storybook-ci uploads-manager` - 建立故事书,并进行故事书测试,提供覆盖产出。 设计为CI使用.
-   `nx test-jest uploads-manager` - 运行滑稽单元测试, 产生代码覆盖结尾.
-   `nx sonar uploads-manager` - 使用声纳Qube工具对代码进行静态分析,以检测出臭虫和代码的气味。 集成为CI进程的步骤之一.
-   `nx chromatic uploads-manager` - 上传供审查的故事手册构建到框色相上,并对用户界面的变化与基线进行可视比较.
-   `nx prepare uploads-manager` - 在Nx Release安排的软件包出版过程中运行命令.

## 所有权

该特性的代码属于home-web. 拥有团队的职责包括控制代码质量,提供修改指南,并与其他团队在修改方面保持一致. 征求拥有或请求哪个团队负责修改守则,将是一种良好做法.

## 翻译

每个地方 `i18n/*.js` 档案由莫吉·詹金斯管道生成和完成。 共享特性构建器复制到 `dist/i18n/` 期间 `build`中的软件包 `i18n.config.js` 下级 `translationDependencies`。 。 。 .

## 常见问题

### 如何安装 @box/uploads-manager？

在项目目录运行 npm install @box/uploads-manager，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0）、react-dom（^18\.0\.0）、react-intl（^6\.4\.2）、@box/item-icon（^3\.6\.39）、@box/blueprint-web（^18\.10\.3）、react-aria-components（1\.16\.0）、@box/blueprint-web-assets（^5\.15\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @box/uploads-manager 支持 TypeScript 吗？

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

### @box/uploads-manager 支持 ESM 还是 CommonJS？

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

### @box/uploads-manager 可以商用吗？

@box/uploads-manager 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @box/uploads-manager 的下载量有多少？

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

### @box/uploads-manager 还在维护吗？

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