# @fluidframework/counter 中文文档

规范地址：https://npmcn.com/package/%40fluidframework/counter/

版本：3\.12\.0
npm 元数据更新时间：2026-11-10T22:53:24.651Z
中文译文更新时间：2026-11-15T02:07:22.698Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：132 kB，72 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2020-09-01T04:26:37.629Z
- 最新版本发布：2026-11-10T22:53:24.516Z
- 近 30 天下载量：14226（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：695（近 12 个月 48 个）

## 中文简介

计数器

## 安装

```sh
npm install @fluidframework/counter
```

也可以使用：`pnpm add @fluidframework/counter`、`yarn add @fluidframework/counter`、`bun add @fluidframework/counter`

## README

# @ fluidframework/ counter

## 使用 Fluid 框架库

对于依赖流体框架库的公共API,我们建议 `^` (caret)版本范围. 例如,使用 `^1.3.4`。 。 。 .

依赖不稳定的API,例如: `beta` API,我们推荐一个更具限制性的版本范围. 例如,使用一个 `~` 版本范围.

## 安装

运行此命令以安装软件包 :

```bash
npm i @fluidframework/counter
```

## 从此软件包导入

此软件包使用 [packet.json 导出](https://nodejs.org/api/packages.html#exports) 通过支持级别将API分离. 有关支助保障的信息改为: [API 支持级别](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels)。 。 。 .

导入 `public` API 从 `@fluidframework/counter`。 。 。 .

导入 `legacy` API 从 `@fluidframework/counter/legacy`。 。 。 .

## API 文档

读取 **@ fluidframework/ counter** API 文档 [https://fluidframework.com/docs/apis/counter (中文(简体) )](https://fluidframework.com/docs/apis/counter)。 。 。 .

## 共享客户

这个 `SharedCounter` 分布式数据结构(DDS)用于存储一个整数计数器,可以被多个客户同时修改. 数据结构通过数据结构使共享价值增减 `increment` 方法。 减少是通过提供负值来实现的.

这个 `SharedCounter` 是一个专门 [优化 DDS](https://fluidframework.com/docs/build/dds/#optimistic-data-structures)。 。 。 . 它运作于通信 _三角洲_ (共同价值应增减的数值),而不是直接改变共同价值. 这样可以避免使用更简单的合并策略的 DDS 的陷阱,其中一个用户的编辑可能会对另一个用户的(参见: [下级](https://npmcn.com/package/%40fluidframework/counter/#readme-why-a-specialized-dds)) (中文(简体) ).

注意 `SharedCounter` 仅在整数上运行.

### 为什么是专门的DDS?

你可能会问自己,为什么不直接将共享整数存储在另一个DDS中,像一个 [共享地图](https://fluidframework.com/docs/data-structures/map)? 吗? 为什么还要花另一跑步时间?

这里答案的关键是,DDS具有更简单的合并策略(比如: `SharedMap`(b) 采取某种残忍的武力办法合并同时编辑. 对于像计数器这样的语义数据类型,这会导致不良行为.

#### 共享映射示例

让我们举个例子来说明这个问题.

考虑一下投票部分. 部件显示一个选项列表,并允许用户单击复选框对某个选项进行投票. 在列表中的每个选项旁边,显示一个显示该项目的票数的活盘.

每当用户检查一个选项时,所有用户都应该看到该选项递增1对应的计数器.

在这个例子中,应用程序将其选票数储存在 [共享地图](https://fluidframework.com/docs/data-structures/map),在地图键的位置 `strings` 表示选项的标识,值为 `numbers` 代表相关票数.

为了简单起见,我们将考虑一种设想,即两个用户大约同时投票支持同一个选项.

具体来说, **用户 A** 单击复选框作为选项 **Oo**,当前已有 **0 个** 选票. 然后,该应用程序乐观地更新了该对象的投票计数,写下了更新后的对数值: **1个** 选项 **Oo** 联合国 `SharedMap`。 。 。 .

值变化操作(op)随后被传输到服务中被排序,并最终在协作会话中被发送到其他用户.

大约在同一时间, **用户 B** 单击复选框作为选项 **Oo**,目前他们认为 **0 个** 选票. 与以前类似,该应用程序乐观地更新了相关的对数值至 **1个**,并转发自己的更新行动.

服务收到来自 **用户 A** 首先,并排序其行动更新 **Oo** 改为 **1个** 作为 **执行部分第0段**。 。 。 . **用户 B**'行动收到后,顺序为: **执行部分第1段**。 。 。 .

两个用户随后收到其更新的确认,并收到 **执行部分第0段** 财务报告和审定财务报表 **执行部分第1段** 将按顺序适用. 两个客户都申请 **执行部分第0段** 设置 **Oo** 改为 **1个**。 。 。 . 然后两个客户都申请 **执行部分第1段** 设置 **Oo** 改为 **1个**。 。 。 .

但这样不对. 两个不同的用户投票支持选项 **Oo**但现在柜台显示 **1个**。 。 。 .

`SharedCounter` 通过以下列方式表达其行动来解决这个问题: _递增_ 财务报告和审定财务报表 _减少_ 而不是直接更新价值.

因此,对于上述情况,如果系统在使用 `SharedCounter`代表计票人, **用户 A** 将提交一份行动 _递增_ **Oo** 以 **+1 键**,而不是更新 **Oo** 从 **0 个** 改为 **1个**。 。 。 . 大约在同一时间, **用户 B** 将提交自己的 **+1 键** 行动 **Oo**。 。 。 .

假设顺序相同,两个用户首先适用 **执行部分第0段** 并增加其计数器 **Oo** 以 **+1 键** (从) **0 个** 改为 **1个**) (中文(简体) ). 其次,两者都适用 **执行部分第1段** 并增加其计数器 **Oo** 以 **+1 键** 第二次(从 **1个** 改为 **2个**) (中文(简体) ).

现在两个用户都看到正确的票数 `Foo`来啊!

## 使用量

这个 `SharedCounter` 对象提供一个简单的 API 表面,用于管理一个共享整数,其值可由合作者增减.

一个新的 `SharedCounter` 数值将初始化并设定为 `0`。 。 。 . 如果您希望初始化计数器的数值不同,您可以 [修改值](https://npmcn.com/package/%40fluidframework/counter/#readme-incrementing--decrementing-the-value) 在装入容器之前,或在储存在另一个共享物体(如: `SharedMap`。 。 。 .

## 安装

包含 `SharedCounter` 库是 [@ fluidframework/ 共享对决](https://www.npmjs.com/package/@fluidframework/counter)。 。 。 .

要启动, 请从您的仓库中的终端运行以下操作 :

```bash
npm install @fluidframework/shared-counter
```

### 创建

创建工作流程 `SharedCounter` 和我们许多其它的DS一样. 关于如何创建工作流程的例子,请参见我们的工作流程实例 [共享映射创建](https://fluidframework.com/docs/data-structures/map/#creation)。 。 。 .

### 增减值

一旦你创造了你的 `SharedCounter`,可以使用 [递增](https://fluidframework.com/docs/apis/counter/isharedcounter-interface#increment-methodsignature) 方法. 此方法接受正或负 _整数_ 适用于共同价值.

```javascript
sharedCounter.increment(3); // Adds 3 to the current value
sharedCounter.increment(-5); // Subtracts 5 from the current value
```

### `incremented` 事件

这个 [递增](https://fluidframework.com/docs/apis/counter/isharedcounterevents-interface#_call_-callsignature) 当协作会话中的客户端通过 `increment` 方法.

签署:

```javascript
(event: "incremented", listener: (incrementAmount: number, newValue: number) => void)
```

通过监听此事件,可以接收并应用来自其他合作者的更改. 配置反相部件时考虑以下代码:

```javascript
const sharedCounter = container.initialObjects.sharedCounter;
let counterValue = sharedCounter.value;

const incrementButton = document.createElement("button");
button.textContent = "Increment";
const decrementButton = document.createElement("button");
button.textContent = "Decrement";

// Increment / decrement shared counter value when the corresponding button is clicked
incrementButton.addEventListener("click", () => sharedCounter.increment(1));
decrementButton.addEventListener("click", () => sharedCounter.increment(-1));

const counterValueLabel = document.createElement("label");
counterValueLabel.textContent = `${counterValue}`;

// This function will be called each time the shared counter value is incremented
// (including increments from this client).
// Update the local counter value and the corresponding label being displayed in the widget.
const updateCounterValueLabel = (delta) => {
    counterValue += delta;
    counterValueLabel.textContent = `${counterValue}`;
};

// Register to be notified when the counter is incremented
sharedCounter.on("incremented", updateCounterValueLabel);
```

在以上代码中,当用户按下增量或减量按钮时 `sharedCounter.increment` 以 +/- 1 调用 . 这导致 `incremented` 向打开此容器的所有客户发送事件.

自兹 `updateCounterValueLabel` 正在倾听所有人 `incremented` 事件,该视图将随时以适当的更新值刷新,每次合作者递增或降低对应值.

## 客户最低要求

Fluid框架客户端库支持此文档中的平台. 这些要求有意具有限制性. 在一个主要的版本系列中,我们可以放松这些要求,但我们不能使其更严格. 对于长期支持(LTS)版本,我们可能需要支持这些平台几年.

其他配置可以奏效,但Fluid框架不支持. 如果一个不支持的配置停止工作, 我们不会将此归类为错误 . 要请求支持未列出的配置, 请存档 . 产品组会评估你的要求. 在此问题上,请具体说明配置的现状:

-   配置有效但需要官方支持.
-   配置不起作用,需要更改.

### 支持的运行时间

-   Fluid框架支持节点.js版本22和24同时收到 [上游支助](https://nodejs.org/en/about/previous-releases)。 。 。 .
    -   流体框架将停止支持第22版 [当上游支持于2027-04-30结束时](https://github.com/nodejs/release#release-schedule)。 。 。 .
    -   流体框架不支持节点.js与 `--no-experimental-fetch` 旗帜.
-   Fluid框架支持支持ES2022标准库的现代浏览器.

### 支持的工具

-   [类型脚本 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0)数字 :
    -   流体框架支持全部 [`strict`](https://www.typescriptlang.org/tsconfig) 选项.
    -   设定建设目标(`lib`, (中文(简体) ), `target`改为: `ES2022` 或后会.
    -   启用 [`strictNullChecks`](https://www.typescriptlang.org/tsconfig)。 。 。 .
    -   流体框架不支持 [在 TypeScript 6.0 中贬值的配置选项](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0)。 。 。 .
    -   流体框架不完全支持 `exactOptionalPropertyTypes`。 。 。 . 如果您启用此选项, 请不要使用 `in`, (中文(简体) ), `Reflect.has`, (中文(简体) ), `Object.hasOwn`,或 `Object.prototype.hasOwnProperty` 改为Fluid框架类型的窄成员. 这些方法可以错误地排除 `undefined` 从可能的值.
-   [网络软件包](https://webpack.js.org/) 页:1
    -   我们不需要一个特定的捆绑者. 其他处理ES模块的捆绑机可以工作,但我们只积极测试网页包.

### 模块分辨率

在类型脚本中 `compilerOptions`,使用时 [`Node16`, (中文(简体) ), `Node20`, (中文(简体) ), `NodeNext`,或 `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) 模块分辨率. 这些设置遵循 [节点.js v12+无害环境管理 分辨率和加载算法](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm)。 。 。 .

不使用 `Node10` 模块分辨率.

### 模块格式

-   ES模块: 使用ES模块来消耗Fluid框架客户端软件包,包括在Node.js中.
-   常见JS : Fluid Framework在3.0版本或后期不正式支持CommonJS.

## 贡献准则

你们可以 [贡献](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) 通过这些方式实现流体框架:

-   回答问题 [GitHub 讨论](https://github.com/microsoft/FluidFramework/discussions)。 。 。 .
-   [提交错误报告](https://github.com/microsoft/FluidFramework/issues) 并且帮助验证修正.
-   审查 [源代码更改](https://github.com/microsoft/FluidFramework/pulls)。 。 。 .
-   [贡献错误修正](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md)。 。 。 .

详细指示改为: [repo 文档](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md)。 。 。 .

本项目遵循 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息,改为: [《行为守则》经常被问到的问题](https://opensource.microsoft.com/codeofconduct/faq/)。 。 。 . 问题或评论,联系 [打开码@ microsoft.com](mailto:opencode@microsoft.com)。 。 。 .

这个项目可能包含微软项目的商标或标志,产品,或服务. 这些商标或标志的使用必须遵循微软 [商标和品牌准则](https://www.microsoft.com/trademarks)。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 帮助

读取 [流体框架文件](https://fluidframework.com/docs/) 用于了解流体框架概念和API.

要求提供文件未载列的资料, [创建问题](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md)。 。 。 .

## 商标

这个项目可能包含微软项目的商标或标志,产品,或服务.

这些商标或标志的使用必须遵循微软的 [商标和品牌准则](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)。 。 。 .

在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 常见问题

### @fluidframework/counter 是什么？

计数器

### 如何安装 @fluidframework/counter？

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

### @fluidframework/counter 支持 TypeScript 吗？

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

### @fluidframework/counter 支持 ESM 还是 CommonJS？

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

### @fluidframework/counter 可以商用吗？

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

### @fluidframework/counter 的下载量有多少？

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

### @fluidframework/counter 还在维护吗？

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