# @fluidframework/aqueduct 中文文档

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

版本：3\.12\.0
npm 元数据更新时间：2026-11-10T22:55:32.079Z
中文译文更新时间：2026-11-15T01:50:12.413Z
软件包许可：MIT

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

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

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

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

## 中文简介

流体框架接口的一组执行.

## 安装

```sh
npm install @fluidframework/aqueduct
```

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

## README

# @ fluidframework/取水器

## 使用 Fluid 框架库

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

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

## 安装

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

```bash
npm i @fluidframework/aqueduct
```

## 从此软件包导入

此软件包使用 [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/aqueduct`。 。 。 .

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

## API 文档

读取 **@ fluidframework/取水器** API 文档 [https://fluidframework.com/docs/apis/取水管](https://fluidframework.com/docs/apis/aqueduct)。 。 。 .

![Aqueduct](https://publicdomainvectors.org/photos/johnny-automatic-Roman-aqueducts.png)

水管是用于在"流体框架"内建造流体物体和流体容器的库. 其目标是 在现有 Fluid 框架接口上提供一个薄的基层,使开发者能够快速启动.

## 流体对象开发

流体对象开发包括开发出数据对象和相应的数据对象工厂. 数据 对象定义了您流体对象的逻辑,而数据对象工厂则定义了如何初始化您对象.

## 数据对象开发

`DataObject` 财务报告和审定财务报表 `PureDataObject` 是图书馆提供的两个基础课程.

### 数据对象

这个 [数据对象](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/aqueduct/src/data-objects/dataObject.ts) 类扩展 [纯数据对象](https://npmcn.com/package/%40fluidframework/aqueduct/#readme-puredataobject) 并提供下列附加功能:

-   A 类 `root` 共享目录,使创建和存储分布式数据结构和对象变得容易.
-   Blob 存储执行使得存储和取回blobs更加容易.

**说明:** 大多数开发者将想要使用 `DataObject` 作为其基础阶级延伸.

### 纯数据对象

[纯数据对象](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/aqueduct/src/data-object-factories/pureDataObject.ts) 提供以下功能:

-   可装入流体容器的基本接口实施.
-   管理流体对象生命周期的函数.
    -   `initializingFirstTime(props: S)` - 第一次使用流体物体初始化,第一次才使用 它所装载的客户端.
    -   `initializingFromExisting()` - 除了第一次启动流体物体外,每次都呼叫 从先前创建的实例中加载实例的时间 .
    -   `hasInitialized()` - 每次打来 `initializingFirstTime` 或者说 `initializingFromExisting` 执行
-   用于在同一容器中创建和获取其他数据对象的帮助器功能.

**说明:** 您可能不想直接继承此数据对象, 除非您正在创建另一个基础数据 对象类。 如果数据对象不使用分布式数据结构,则应当使用 Control Services 用于管理对象.

### 数据对象示例

在下面的例子中,我们有一个简单的数据对象, _点击器_,这样就可以在页面按钮旁边产生一个值. 每次按下按钮,值就会递增。 由于这个数据对象使 DOM 也延伸 `IFluidHTMLView`。 。 。 .

```jsx
export class Clicker extends DataObject implements IFluidHTMLView {
    public static get Name() { return "clicker"; }

    public get IFluidHTMLView() { return this; }

    private _counter: SharedCounter | undefined;

    protected async initializingFirstTime() {
        const counter = SharedCounter.create(this.runtime);
        this.root.set("clicks", counter.handle);
    }

    protected async hasInitialized() {
        const counterHandle = this.root.get<IFluidHandle<SharedCounter>>("clicks");
        this._counter = await counterHandle.get();
    }

    public render(div: HTMLElement) {
        ReactDOM.render(
            <CounterReactView counter={this.counter} />,
            div,
        );
        return div;
    }

    private get counter() {
        if (this._counter === undefined) {
            throw new Error("SharedCounter not initialized");
        }
        return this._counter;
    }
}
```

## 数据对象 事实开发

这个 `DataObjectFactory` 用于创建流体对象并在上下文中初始化数据对象 集装箱 工厂可以与一个数据对象并肩生活,也可以在不同的包中生活. 这个 `DataObjectFactory` 定义 数据对象内部使用的分布式数据结构以及它所依赖的任何流体对象.

水管为每个数据对象提供一个工厂.

### 更多细节

-   [数据对象事实](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/aqueduct/src/data-object-factories/dataObjectFactory.ts)
-   [纯数据对象事实](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/aqueduct/src/data-object-factories/pureDataObjectFactory.ts)

### 数据对象事实实例

在下面的例子中,我们构建了一个 `DataObjectFactory` 联 合 国 [点击器](https://npmcn.com/package/%40fluidframework/aqueduct/#readme-dataobject-example) 上文的例子。 为了建立一个 `DataObjectFactory`我们需要提供工厂 用于我们内部的分布式数据结构 `DataObject`。在上述例子中,我们将一个手柄存储到 `SharedCounter` 内 `this.root` 追踪我们 `"clicks"`编辑 `DataObject` 带着 `SharedDirectory` (单位:千美元)`this.root`)已经初始化,所以我们只需要添加工厂用于 `SharedCounter`。 。 。 .

```typescript
export const ClickerInstantiationFactory = new DataObjectFactory({
    type: Clicker.Name,
    ctor: Clicker,
    sharedObjects: [SharedCounter.getFactory()],
});
```

这个厂商可以在提供创建实例时创建 Clickers .

```typescript
const myClicker = ClickerInstantiationFactory.createInstance(this.context) as Clicker;
```

### 数据对象的提供者

这个 `this.providers` 对象在 `PureDataObject` 在构造器中初始化并基于提供者生成 由集装箱提供。 要访问特定的提供者,您需要:

1.  定义通用名称中的类型 `PureDataObject`编号 :`DataObject`
2.  将符号添加到您的工厂( 见 [数据对象事实示例](https://npmcn.com/package/%40fluidframework/aqueduct/#readme-dataobjectfactory-example) (见下文)

如下例子: `IFluidUserInfo` 这样的界面 :

```typescript
interface IFluidUserInfo {
    readonly userCount: number;
}
```

以我们为例,我们要宣布: `IFluidUserInfo` 提供商并获得 `userCount` 如果集装箱 提供 `IFluidUserInfo` 供养.

```typescript
export class MyExample extends DataObject<IFluidUserInfo> {
    protected async initializingFirstTime() {
        const userInfo = await this.providers.IFluidUserInfo;
        if(userInfo) {
            console.log(userInfo.userCount);
        }
    }
}

// Note: we have to define the symbol to the IFluidUserInfo that we declared above. This is compile time checked.
export const ClickerInstantiationFactory = new DataObjectFactory({
    type: Clicker.Name
    ctor: Clicker,
    optionalProviders: { IFluidUserInfo }, // Provider Symbols see below
});
```

## 集装箱开发

集装箱是收集能够产生经验的数据对象和功能。 集装箱有实例 数据对象,以及定义可在集装箱内创建的数据对象。 因为这个数据 物体不能被消耗,除非它们在集装箱内.

水管图书馆提供 [DataStore 集装箱运行时间不及时](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/aqueduct/src/containerRuntimeFactories/containerRuntimeFactoryWithDefaultDataStore.ts) 让你可以作为一个容器 开发者到 :

-   定义可以创建的数据对象的登记册
-   宣告默认数据对象
-   使用提供者条目
-   申报集装箱级别 [请求处理器](https://npmcn.com/package/%40fluidframework/aqueduct/#readme-container-level-request-handlers)

## 容器对象示例

在下面的例子中,我们将写一个显示上述情况的集装箱 [点击器](https://npmcn.com/package/%40fluidframework/aqueduct/#readme-dataobject-example) 使用 [点击器厂](https://npmcn.com/package/%40fluidframework/aqueduct/#readme-dataobjectfactory-example)。您将在下面注意到,集装箱开发商定义了 流体对象的注册名称(数据对象类型). 我们也通过我们想要成为默认的数据对象的类型. 默认数据对象是在容器首次创建时创建的.

```typescript
export fluidExport = new ContainerRuntimeFactoryWithDefaultDataStore(
  ClickerInstantiationFactory.type, // Default data object type
  ClickerInstantiationFactory.registryEntry, // Fluid object registry
  [], // Provider Entries
  [], // Request Handler Routes
);
```

## 集装箱级请求处理员

您可以为容器提供自定义请求处理器。 这些请求处理器在系统处理器后注入,但 之前 `DataObject` 获得功能。 请求处理器允许您拦截到容器的请求并返回 自定义响应.

考虑一个你想创建随机颜色生成器的情景 。 我可以创造一个请求汉德勒 当有人 向集装箱提出请求,以便: `{url:"color"}` 将拦截并返回自定义 `IResponse` 联 合 国 `{ status:200, type:"text/plain", value:"blue"}`。 。 。 .

我们使用定制的处理器来构建集装箱服务模式.

## 客户最低要求

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/aqueduct 是什么？

流体框架接口的一组执行\.

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

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

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

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

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

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

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

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

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

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

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

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