# @cplieger/actions 中文文档

规范地址：https://npmcn.com/package/%40cplieger/actions/

版本：4\.0\.0
npm 元数据更新时间：2026-11-04T16:27:38.356Z
中文译文更新时间：2026-11-10T21:29:12.632Z
软件包许可：Apache-2\.0

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

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

弃用说明：Moved into @cplieger/ui: import @cplieger/ui/actions \(and @cplieger/ui/actions/testing in tests\)\. Guide: https://github\.com/cplieger/ui/blob/main/docs/migrating\.md

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

- 包体积（解压后）：126 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-03T15:34:47.649Z
- 最新版本发布：2026-11-01T20:21:59.482Z
- 近 30 天下载量：4768（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

TypeScript 声明化的 Aync UI 操作框架

## 安装

```sh
npm install @cplieger/actions
```

也可以使用：`pnpm add @cplieger/actions`、`yarn add @cplieger/actions`、`bun add @cplieger/actions`

## README

# 动作

[![npm](https://img.shields.io/npm/v/@cplieger/actions)](https://www.npmjs.com/package/@cplieger/actions) [![JSR](https://jsr.io/badges/@cplieger/actions)](https://jsr.io/@cplieger/actions) [![Mutation (TS)](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/actions/badges/mutation-ts.json)](https://github.com/cplieger/actions/issues?q=label%3Astryker-tracker)

动作会给您 TypeScript UI 中的每个服务器调用相同的待处理状态、重试、回滚和信件, 从每个动作一个声明.

它取代了加载旗,错误消息和撤消代码,否则您会在每一个更改服务器数据的呼叫周围写入. 优化的更新和重试都是选入的,不需要UI框架. 它需要TypeScript 5.0或更晚,以及一个无害环境管理捆绑器. 这取决于 [`@cplieger/reactive`](https://github.com/cplieger/reactive) 财务报告和审定财务报表 [`@cplieger/fetch`](https://github.com/cplieger/fetch) 并且根据Apache-2.0获得许可.

## 为什么用它

动作是为香草 TypeScript 前端构建的,这些前端希望每个服务器呼叫中的行为相同.

-   乐观的更新在请求前更改了UI,并在失败或取消时回滚取消.
-   以指数方式重试后退,只重试您标记为瞬态的故障,并在浏览器下线时暂停.
-   `scope` 运行同一键的发送顺序, `dedupe` 将它们合并为一个请求 `abort()` 或一个 `AbortSignal` 转至 `dispatch()` 取消单一发送.
-   `isPending` 财务报告和审定财务报表 `pendingCount` 反应通过 `@cplieger/reactive`,因此一个按钮可以在动作运行时自行禁用.
-   失败或取消解决发送到 `null` 而不是拒绝,与 [两种例外情况](https://npmcn.com/package/%40cplieger/actions/docs/lifecycle.md#order-of-a-dispatch),以及 `handle.outcome` 告诉三个结局分开.
-   `onSuccess`, (中文(简体) ), `onError` 财务报告和审定财务报表 `onSettled` 跟着TanStack Query的变异回调,和 `configureApi` 跟踪 RTK 查询 `fetchBaseQuery`。 。 。 .
-   仅 `bindLoadingState` 财务报告和审定财务报表 `withAsyncFeedback` 需要一个DOM。 其余也运行于节点.

考虑 [TanStack 查询](https://tanstack.com/query/latest) 如果您还需要服务器状态缓存, 在突变后缓存无效, 以及像 React 这样的框架钩钩 `useMutation`。 。 。 .

## 安装

```sh
npx jsr add @cplieger/actions
# or
npm i @cplieger/actions
```

## 使用量

启动时连接您的通知显示, 在模块范围定义每个动作, 然后从事件处理器中发送 .

```typescript
import { configure, apiAction, retryNetwork } from "@cplieger/actions";

configure({
  success: (msg) => showToast("success", msg),
  error: (msg, retry) => showToast("error", msg, retry?.onClick),
});

const deleteItem = apiAction<string>({
  name: "items.delete",
  request: (id) => ({ method: "DELETE", path: `/api/items/${id}` }),
  error: "Could not delete the item",
  retryable: retryNetwork,
  retry: { count: 2, delay: 300 },
});

await deleteItem.dispatch(itemId);
```

`dispatch()` 决定结果,或 `null` 在失败或取消之后。 失败后, 错误消息已经显示 。 重试需要两个设置 . `retryable` 决定哪些失败是短暂的,以及 `retry` 设置尝试和等待的次数。 与 `retry` 单枪匹马 什么都没有被重审.

乐观更新返回回滚需要恢复的内容 :

```typescript
const toggleDone = apiAction<{ id: string; done: boolean }, Todo, Todo>({
  name: "todos.toggle",
  request: ({ id, done }) => ({ method: "PATCH", path: `/api/todos/${id}`, body: { done } }),
  optimistic: ({ id, done }) => {
    const previous = store.get(id);
    store.setDone(id, done);
    return previous;
  },
  rollback: ({ id }, previous) => {
    if (previous) store.set(id, previous);
  },
  scope: ({ id }) => `todo:${id}`,
});
```

`rollback` 运行在错误或取消上,永远不会成功. `scope` 使同一项目的两个切换相继运行.

在动作运行时禁用按钮, 并读取结果状态 :

```typescript
bindLoadingState("todos.toggle", toggleButton);

const outcome = await toggleDone.dispatch({ id, done: true }).outcome;
if (outcome.status === "error") console.warn(outcome.error.message);
```

## API 密码

-   设置, 启动时一次 : `configure` 连接您的通知显示,并 `configureApi` 设置 HTTP 动作的基础 URL、信头和证书. `configureTransport` 将频道连接成流命令,例如端点,其答复通过服务器发送事件到达.
-   工厂: `defineAction` 对于任何同步函数, `apiAction` 用于HTTP请求, `transportAction` 对流指令.
-   帮助者 : `debouncedDispatch`, (中文(简体) ), `pollAction`, (中文(简体) ), `pollUntil`, (中文(简体) ), `bindLoadingState`, (中文(简体) ), `withAsyncFeedback`, (中文(简体) ), `registerCleanup`。 。 。 .
-   状况和活动: `isPending`, (中文(简体) ), `pendingCount`, (中文(简体) ), `subscribeToActions`, (中文(简体) ), `subscribeByName`, (中文(简体) ), `getActionLog`。 。 。 .
-   错误和预设 : `ActionError`, (中文(简体) ), `retryNetwork`, (中文(简体) ), `classifyFetchError`, (中文(简体) ), `hasErrorString`, (中文(简体) ), `RETRY_STANDARD`, (中文(简体) ), `IDEMPOTENCY_HEADER`, (中文(简体) ), `IDEMPOTENCY_COMMAND_FIELD`。 。 。 .
-   测试 : `resetActionFramework` 从 `@cplieger/actions/testing`,用于 `beforeEach`。 。 。 .

本文全文取自文件评论 [日 尔](https://jsr.io/@cplieger/actions/doc)。 。 。 .

## 服务器文本和参数需要注意

-   错误消息可以包含服务器响应的文本.  `configure` 适配器使它成为文本,而不是HTML.
-   单位 `decodeError`, (中文(简体) ), `info.body` 是解析失败响应的正文 。 在读出字段之前检查它的形状 .
-   与 `baseUrl` 设置,请求路径不能改变来源。 无 `baseUrl`,路径 `fetch()` 没有改变, 因此永远不要从服务器文本中构建整个路径 .
-   动作日志,它的收听器和重试按钮保留了每个调度的参数并产生内存. 设定 `sensitive: true` (a) 其论点或结果含有秘密、象征或个人资料的行动。 它的日志条目然后不包含参数,结果或错误,也不需要重试. 见 [敏感行动](https://npmcn.com/package/%40cplieger/actions/docs/lifecycle.md#sensitive-actions)。 。 。 .

## 不支持设计

| 特性 | 原因 |
| --- | --- |
| 查询缓存, stale- while- revalidate | 这是动作跑车,不是数据缓存。 并用 TanStack 查询 . |
| 缓存无效, 重新验证 | 数据缓存问题. |
| React, Vue 或 Svelte 的框架适配器 | 香草TypeScript设计. 框架约束属于单独的包. |
| 视觉 DevTools 面板 | 一个单独的包裹. `getActionLog` 财务报告和审定财务报表 `subscribeByName` 给它数据. |
| 安全部门改革和水合 | 动作是必须的突变, 没有状态可以从服务器到客户端 . |
| 跳过 `maxWait` | 刻意简化. 打电话 `flush()` 当一个调度必须开火. |
| 喉管辅助器 | 并非专门针对行动。 在你打电话前发抖 `dispatch()`。 。 。 . |
| `condition` 或执行前警卫 | 一个 `if` 来电者会这么做. `dedupe` 涵盖主案. |
| `onProgress` 回调 | 交通专用. 报告进展情况 `run()` 函数. |
| 批量发送 | 一个商店的担心, 而这个图书馆没有一家商店. |
| `dispose()` 或行动注销登记 | 一个闲置的动作几乎没有记忆,所以一个现实的应用不会泄露. |

## 文档

-   [调度生命周期](https://npmcn.com/package/%40cplieger/actions/docs/lifecycle.md) 包括通知、重试、货币、注销、回调和输入结果.
-   [HTTP 和流动动作](https://npmcn.com/package/%40cplieger/actions/docs/http.md) 覆盖 `configureApi`,请求路径,响应解码和 `transportAction`。 。 。 .
-   [UI 和 投票助手](https://npmcn.com/package/%40cplieger/actions/docs/helpers.md) 包括解封,投票,装入状态,按钮反馈,可观察性和测试.

## 捐款

欢迎提出问题和拉动请求。 见 [捐款额](https://npmcn.com/package/%40cplieger/actions/CONTRIBUTING.md)。 。 。 .

## 免责声明

这个项目是精心设计的,遵循安全最佳做法,但打算供个人/自发使用。 不保证生产环境的适宜性. 自己冒险使用.

这个项目是利用AI辅助工具,使用 [克劳德](https://claude.com/), (中文(简体) ), [常规](https://openai.com/),以及 [基罗](https://kiro.dev/)人类维护者界定建筑、监督实施和作出所有最后决定.

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://npmcn.com/package/%40cplieger/actions/LICENSE)。 。 。 .

## 常见问题

### @cplieger/actions 是什么？

TypeScript 声明化的 Aync UI 操作框架注意：该包已被作者标记为弃用——Moved into @cplieger/ui: import @cplieger/ui/actions \(and @cplieger/ui/actions/testing in tests\)\. Guide: https://github\.com/cplieger/ui/blob/main/docs/migrating\.md

### 如何安装 @cplieger/actions？

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

### @cplieger/actions 支持 TypeScript 吗？

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

### @cplieger/actions 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cplieger/actions 可以商用吗？

@cplieger/actions 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cplieger/actions 的下载量有多少？

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

### @cplieger/actions 还在维护吗？

最新版本 4\.0\.0 发布于 2026/11/02（9 天前）；至今共发布 48 个版本，其中过去 12 个月发布了 48 个；首次发布于 2026/06/03。作者已将其标记为弃用，新项目建议寻找替代方案。