# @commercetools-frontend-extensions/operations 中文文档

规范地址：https://npmcn.com/package/%40commercetools-frontend-extensions/operations/

版本：5\.5\.0
npm 元数据更新时间：2026-11-02T10:14:04.103Z
中文译文更新时间：2026-11-10T12:02:50.722Z
软件包许可：Proprietary

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

原始 npm 页面：https://www.npmjs.com/package/%40commercetools-frontend-extensions/operations
原文对照：https://npmcn.com/package/%40commercetools-frontend-extensions/operations/?lang=original

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

- 包体积（解压后）：1.1 MB，270 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react 17\.x \|\| 19\.x，react-intl 6\.x \|\| 7\.x，@emotion/react 11\.x，@emotion/styled 11\.x，@commercetools-frontend/i18n 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/sentry 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/ui-kit 19\.x \|\| 20\.x，@commercetools-frontend/constants 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/fullstory 2\.x \|\| 3\.x \|\| 4\.x，@commercetools-frontend/permissions 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/actions-global 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/application-shell 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/application-components 24\.x \|\| 25\.x \|\| 27\.x，@commercetools-frontend/application-shell-connectors 24\.x \|\| 25\.x \|\| 27\.x
- 首次发布：2025-11-24T11:04:14.814Z
- 最新版本发布：2026-11-02T10:14:03.939Z
- 近 30 天下载量：6687（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：110（近 12 个月 110 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @commercetools-frontend-extensions/operations
```

也可以使用：`pnpm add @commercetools-frontend-extensions/operations`、`yarn add @commercetools-frontend-extensions/operations`、`bun add @commercetools-frontend-extensions/operations`

## README

# 共享成套业务

共享跨多个前端应用程序和扩展的进出口业务功能.

## 安装

```bash
pnpm add @commercetools-frontend-extensions/operations
```

## 钩子

### `useFileUpload`

使用基于任务的导入流程( 创建容器 ) 上传文件的钩子 .

```typescript
const { upload, isUploading, progress, validationProgress } = useFileUpload({
  projectKey: string,
  pollingInterval?: number,
  maxPollingAttempts?: number
})
```

**参数:**

-   `projectKey` (必须): 商务工具项目关键
-   `pollingInterval` (可选) : 投票间隔为ms. 默认 : `5000`
-   `maxPollingAttempts` (可选):最大投票尝试. 默认 : `200`

**回返情况:**

-   `upload` - 启动上传的功能
-   `isUploading` - 上传是否在进行
-   `progress` - 上传进度(0-100)
-   `validationProgress` - 说吧 `{ processed: number, isValidating: boolean }`
    -   `processed`: 迄今已验证的资源数量(来自后端)
    -   `isValidating`: 是否在验证中

**上传配置选项 :**

-   `file` (必须): 要上传的文件
-   `resourceType` (必须): 资源类型
-   `fileType` (可选):文件类型(`'csv'` 或者说 `'json'`)发往API.
-   `settings` (可选):导入设置(格式,小数分隔符.)
-   `autoProcess` (可选) : 何时 `true`,后端在验证完成后自动开始处理. 默认 : `false`
-   `skipValidationPolling` (可选) : 何时 `true`中,跳过全部验证投票,并在工作完成后返回 `processing` 状态。 用于防火和遗忘的上传 `autoProcess: true`默认 : `false`
-   `abortSignal` (可选) : 取消符号
-   `onSuccess` (需要):上传完成后回电
-   `onError` (可选) : 回调错误
-   `onProgress` (可选的):召回上传进度 (0-100)
-   `onValidationProgress` (可选的):召回验证进度

**用法 :**

```typescript
import { useFileUpload } from '@commercetools-frontend-extensions/operations'

const { upload, isUploading, progress, validationProgress } = useFileUpload({
  projectKey,
})

const abortController = new AbortController()

await upload({
  file: File,
  resourceType: 'product' | 'category' | ...,
  fileType?: 'csv' | 'json', // override derived file type
  settings?: {
    format?: 'CSV' | 'JSON',
    decimalSeparator?: '.' | ',',
    resourceType?: 'product-draft' | 'category' | ...,
    options?: {
      publishAllChanges?: boolean,
      unpublishAllChanges?: boolean
    }
  },
  autoProcess?: boolean, // default: false
  skipValidationPolling?: boolean, // default: false
  abortSignal: abortController.signal,
  onSuccess: (result) => {
    // result.containerKey - Import container key
    // result.summary - { total, valid, invalid, fields, ignoredFields, results }
    // result.jobId - Job ID
    // result.job - Full job object
  },
  onError: (error) => { /* ... */ },
  onProgress: (progress) => { /* 0-100 */ },
  onValidationProgress: (job) => { /* ... */ }
})

// To cancel:
abortController.abort()
```

* * *

### `useFetchImportOperations`

获取带有可选投票的容器的导入操作.

```typescript
const { data, error, isLoading, refetch } = useFetchImportOperations({
  projectKey,
  importContainerKey,
  queryParams?: { limit, offset, ... },
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})
```

* * *

### `useFetchImportSummaries`

以可选投票方式获取导入摘要( 容器) .

```typescript
const { data, error, isLoading, refetch } = useFetchImportSummaries({
  projectKey,
  queryParams?: { limit, offset, states, ... },
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})
```

* * *

### `useFetchImportContainerDetails`

获取特定导入容器的细节.

```typescript
const { data, error, isLoading, refetch } = useFetchImportContainerDetails({
  projectKey,
  importContainerKey,
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})
```

* * *

### `useFetchExportOperations`

以可选投票方式获取输出操作 .

```typescript
const { data, error, isLoading, refetch } = useFetchExportOperations({
  projectKey,
  queryParams?: { limit, offset, resourceTypes, ... },
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})
```

* * *

### `useFetchFileImportJob`

为状态更新提供文件导入任务 .

```typescript
const { data, error, isLoading, refetch } = useFetchFileImportJob({
  projectKey,
  importContainerKey,
  jobId,
  pollingInterval?: number,
  shouldContinuePolling?: (job) => boolean
})
```

**任务说明 :** `queued` → `processing` → `validated` → `initializing` → `ready`

* * *

### `useFetchFileImportJobRecords`

从文件导入任务中获取记录( 错误或有效条目) , 并带有页码支持 。 在装入新页面时保持先前的数据可见 .

```typescript
const { data, error, isLoading, refetch } = useFetchFileImportJobRecords({
  projectKey,
  importContainerKey,
  jobId,
  limit?: number,
  offset?: number,
  isValid?: boolean,
  skip?: boolean
})
```

**参数:**

-   `projectKey`: 商务工具项目密钥
-   `importContainerKey`: 导入容器密钥
-   `jobId`: 文件导入任务ID
-   `limit` (可选):每页要获取的记录数量
-   `offset` (可选) : 位移
-   `isValid` (可选) : 以有效方式过滤( C)`true`)或无效(`false`() 记录
-   `skip` (可选) : 跳过取取( 用于有条件取取取)

**回返情况:**

-   `data` - 说吧 `{ results, total, limit, offset, count }` 或者说 `null`
-   `error` - 获取失败时出错对象
-   `isLoading` - 是否正在获取中
-   `refetch` - 手动触发反射功能

**用法示例( 贴出错误表) :**

```typescript
const pagination = usePaginationState()
const offset = (pagination.page.value - 1) * pagination.perPage.value

const { data, isLoading } = useFetchFileImportJobRecords({
  projectKey,
  importContainerKey: containerKey,
  jobId,
  offset,
  limit: pagination.perPage.value,
  isValid: false, // Fetch only invalid records (errors)
})

```

* * *

## 帮助函数

```typescript
import {
  isImportJobQueued,
  isImportJobProcessing,
  isImportJobValidated,
  isImportJobInitializing,
  isImportJobReady,
  shouldContinuePollingForImportValidation
} from '@commercetools-frontend-extensions/operations'
```

* * *

## 投票示例

```typescript
const { data, isLoading } = useFetchImportOperations({
  projectKey,
  importContainerKey,
  pollingInterval: 5000,
  shouldContinuePolling: (data) => {
    return data?.results?.some(op => op.state === 'processing') ?? false
  }
})
```

## 常见问题

### 如何安装 @commercetools-frontend-extensions/operations？

在项目目录运行 npm install @commercetools-frontend-extensions/operations，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（17\.x \|\| 19\.x）、react-intl（6\.x \|\| 7\.x）、@emotion/react（11\.x）、@emotion/styled（11\.x）、@commercetools-frontend/i18n（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/sentry（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/ui-kit（19\.x \|\| 20\.x）、@commercetools-frontend/constants（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/fullstory（2\.x \|\| 3\.x \|\| 4\.x）、@commercetools-frontend/permissions（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/actions-global（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/application-shell（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/application-components（24\.x \|\| 25\.x \|\| 27\.x）、@commercetools-frontend/application-shell-connectors（24\.x \|\| 25\.x \|\| 27\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @commercetools-frontend-extensions/operations 支持 TypeScript 吗？

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

### @commercetools-frontend-extensions/operations 支持 ESM 还是 CommonJS？

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

### @commercetools-frontend-extensions/operations 可以商用吗？

@commercetools-frontend-extensions/operations 使用 Proprietary 许可。声明的许可为 Proprietary，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @commercetools-frontend-extensions/operations 的下载量有多少？

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

### @commercetools-frontend-extensions/operations 还在维护吗？

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