# @fluidframework/driver-web-cache 中文文档

规范地址：https://npmcn.com/package/%40fluidframework/driver-web-cache/

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

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

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

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

- 包体积（解压后）：243 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2022-03-18T22:14:15.621Z
- 最新版本发布：2026-11-10T22:25:29.649Z
- 近 30 天下载量：4154（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：480（近 12 个月 48 个）

## 中文简介

为网页浏览器执行驱动程序缓存 API

## 安装

```sh
npm install @fluidframework/driver-web-cache
```

也可以使用：`pnpm add @fluidframework/driver-web-cache`、`yarn add @fluidframework/driver-web-cache`、`bun add @fluidframework/driver-web-cache`

## README

# @fluidframework/driver-web-cache (英语)

该套方案提供了执行《公约》和 `IPersistedCache` 界面。 此缓存启用 在用户的机器上存储用户内容,以便在打开同一流体时提供更快的启动体验 集装箱不止一次。 此执行依赖于索引db,所以它只打算用于浏览器 上下文.

## 使用 Fluid 框架库

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

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

## 安装

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

```bash
npm i @fluidframework/driver-web-cache
```

## 从此软件包导入

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

导入 `legacy` API 从 `@fluidframework/driver-web-cache/legacy`。 。 。 .

## API 文档

读取 **@fluidframework/driver-web-cache (英语)** API 文档 [https://fluidframework.com/docs/apis/driver-web-cache 页面存档备份,存于互联网档案馆](https://fluidframework.com/docs/apis/driver-web-cache)。 。 。 .

## 使用量

```typescript
import { FluidCache } from "@fluidframework/driver-web-cache";

new FluidCache({
    partitionKey: userId,
    logger,
    maxCacheItemAge,
});
```

### 参数

-   `partitionKey` - 用于确定缓存的分区正在使用中,并且可以防止多个用户在 同一机器从共享快照缓存。 如果您绝对知道用户不会共享缓存, 也可以设置为 `null`。目前是可选的,但提议在下一次大碰头时需要. 建议使用此键来区分缓存数据的用户.
-   `logger` - 可选择性地执行伐木合同,其中可记录诊断数据.
-   `maxCacheItemAge` - 缓存追踪每个条目的时间戳。 此旗帜指定了最大年龄( 毫秒) 用于缓存条目。 此旗帜不能控制缓存内容被删除时, 因为不同的情况以及 对于同一数据,应用程序可能有不同的停滞阈值.

## 原子最新情况`update`(中文(简体) )

`FluidCache` 暴露一个 `update` 用于执行原子读取-修改-写作的方法。 现取者 值是读取的,更新器的回调则在单个索引数据库内决定是否以及写什么 `readwrite` 交易。 这使得所有消费者的语义一致更新 基础索引 DB 实例(例如多个浏览器标签竞相持续下线等待状态).

```typescript
// Conditional overwrite (active tab wins): only write if our revision is higher.
const wrote = await fluidCache.update(entry, (existing, set) => {
    const existingRev = (existing as { rev?: number } | undefined)?.rev ?? -1;
    if (mine.rev > existingRev) {
        set(mine);
    }
});

// Read-modify-write: increment a counter atomically.
await fluidCache.update(entry, (existing, set) => {
    const prev = (existing as { count: number } | undefined)?.count ?? 0;
    set({ count: prev + 1 });
});
```

这个 `updater` 引用回调 `(existing, set)`。 。 。 . `existing` 实值 `undefined` 当缓存 线条是隐形的 `get` —— 即不存在密钥的条目, 现有条目属于 不同的分区,或者现有条目比 `maxCacheItemAge`写作,打电话 `set(value)`; 不动缓存, 不拨号返回 `set`。 。 。 .

通话 `set(undefined)` 删除键上的行(相当于 `removeEntry` 里面一样 原子交易). `get` 已崩溃“ 无条目” 和“ 未定义存储的条目” 可见的结果,所以在未定义的语义上删除给呼叫者一个原子条件删除 对于任何有意义的使用案例,都不得含糊不清.

更新器本身必须是同步的 `set` 必须从里面调用。 索引数据库 交易自动关闭任何非IDB等待,这将静悄悄地打破导致 更新正确。 两名警卫大叫而不是沉默: `set` 更新器后 已返回丢出 `UsageError` 在呼叫地点(因此推迟)`set` 喜欢引用它的模式 从a `setTimeout` ; 返回一个可处理文件——例如,宣布更新程序 `async` ——在更新器返回后检测出,中止交易,并在下方登录 `FluidCacheUpdateCallbackError`。如果更新器调用 `set` 不止一次,最后一个值获胜. 如果更新器抛出——包括拨打后 `set` - 交易已中止,且已存在 行被保留.

何时 `set` 被称作,写(或删除)在解剖上取代键上存在的任意行, 包括更新者认为的横分行或斜行 `undefined` (比对无条件 覆盖行为 `put`) (中文(简体) ). 必须保留分行的呼叫者不应使用 `update`。 。 。 .

`update` 返回时 `true` 若为 `set` 曾被召唤,而作过文 `false` 若为 更新器未拨号即返回 `set`,丢出,或发生美洲开发银行错误.

**比较和设置的呼叫者 :** 页:1 `false` 返回崩溃三种不同的结果——更新器 返回时不打电话 `set` (一个失落的种族),被丢弃的更新器(包括aync-update器被误用) ),而美洲开发银行的写作本身也失败了。 需要区分的呼叫者必须咨询 遥测: 更新器- 侧失败日志 `FluidCacheUpdateCallbackError`; IDB- write 失败日志 下级 `FluidCachePutError`。丢失的比较赛和赛跑没有记录.

## 清除缓存条目

当任何流体内容被装入启用的 Web 缓存时, 将会安排一个任务来清除所有的“ stale” 缓存 条目。 这项任务安排在 `setIdleCallback` 浏览器 API. 我们定义 Stale 缓存项为任何缓存 过去4周内没有使用(读取或写入)的条目。 缓存已清除所有 stale 缓存 与所有文档相对应的条目,而不仅仅是正在装入的流体文档.

这个 `deleteFluidCacheIndexDbInstance` API 应用程序可用于清除快照的全部内容 随时缓存 。 我们建议在用户明确签名时给这个API打电话. 托管应用程序 确保负责任地使用快照缓存能力,以满足任何相关的需要 客户承诺,如酌情清理储存或在某些情况下断裂快取, 例如,当知道时,用户会被登录在公共计算机上.

```typescript
import { deleteFluidCacheIndexDbInstance } from "@fluidframework/driver-web-cache";

// We put a catch here because Firefox Incognito will throw an error here. This is why we claim this method is a "best effort", since sometimes the browser won't let us access storage
deleteFluidCacheIndexDbInstance().catch(() => {});
```

## 客户最低要求

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/driver-web-cache 是什么？

为网页浏览器执行驱动程序缓存 API

### 如何安装 @fluidframework/driver-web-cache？

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

### @fluidframework/driver-web-cache 支持 TypeScript 吗？

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

### @fluidframework/driver-web-cache 支持 ESM 还是 CommonJS？

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

### @fluidframework/driver-web-cache 可以商用吗？

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

### @fluidframework/driver-web-cache 的下载量有多少？

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

### @fluidframework/driver-web-cache 还在维护吗？

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