# @fluidframework/matrix 中文文档 规范地址：https://npmcn.com/package/%40fluidframework/matrix/ 版本：3\.12\.0 npm 元数据更新时间：2026-11-10T22:56:06.817Z 中文译文更新时间：2026-11-15T02:06:43.762Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fluidframework/matrix 原文对照：https://npmcn.com/package/%40fluidframework/matrix/?lang=original 项目主页：https://fluidframework.com/ 源码仓库：https://github.com/microsoft/FluidFramework ## 关键信息（来自 npm 元数据） - 包体积（解压后）：690 kB，144 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：13 个 - 首次发布：2020-09-01T04:28:01.003Z - 最新版本发布：2026-11-10T22:56:06.644Z - 近 30 天下载量：14461（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：695（近 12 个月 48 个） ## 中文简介 分布式矩阵 ## 安装 ```sh npm install @fluidframework/matrix ``` 也可以使用：`pnpm add @fluidframework/matrix`、`yarn add @fluidframework/matrix`、`bun add @fluidframework/matrix` ## README # @ fluidframework/matrix (英语) 共享Matrix是一个长方形的2D值阵列. 矩阵值是包含嵌入式IFluidHandle对流体对象的引用的JSON序列式类型的超集. ## 使用 Fluid 框架库 对于依赖流体框架库的公共API,我们建议 `^` (caret)版本范围. 例如,使用 `^1.3.4`。 。 。 . 依赖不稳定的API,例如: `beta` API,我们推荐一个更具限制性的版本范围. 例如,使用一个 `~` 版本范围. ## 安装 运行此命令以安装软件包 : ```bash npm i @fluidframework/matrix ``` ## 从此软件包导入 此软件包使用 [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/matrix`。 。 。 . 导入 `legacy` API 从 `@fluidframework/matrix/legacy`。 。 。 . ## API 文档 读取 **@ fluidframework/matrix (英语)** API 文档 [https://fluidframework.com/docs/apis/matrix 页面存档备份,存于互联网档案馆](https://fluidframework.com/docs/apis/matrix)。 。 。 . ## 业务 共享Matrix目前支持以下操作: - `insertCols(col, numCols)` 编号 : `removeCols(col, numCols)` - `insertRows(row, numRows)` 编号 : `removeRows(row, numRows)` - `setCells(row, col, numCols, values)` (值是按行主序排列的 1D 阵列) 插入/去除操作使用Fluid序列语义调节,而SetCells()则使用Fluid映射语义. ## 执行情况 共享Matrix数据结构包括: - 用于处理行/ Col 插入和去除操作的“ 参数” - 用于保存单元格值的稀有四棵树状"物理商店" ### 传动矢量 “ PermutationVectors” 提供了当前逻辑行/ Col( 例如 ) 之间的一层间接 , `R2`)和 `[x,y]` 在存储单元格值的物理存储库中协调. 例如,存储下列矩阵: ``` A B C D <- logical col +-------- 1 | . . . 3 logical row -> 2 | . . . . 3 | 8 . . . 4 | C . . F ``` SparseMatrix 从物理存储中分配了3行和2列: ``` 0 . . 1 <- column allocs +-------- 0 | . . . 3 . | . . . . row allocs -> 1 | 8 . . . 2 | C . . F ``` 并将单元格值写入这些位置: ``` 0 1 <- physical col +---- 0 | . 3 physical row -> 1 | 8 . 2 | C F ``` 插入的下一行/一栏被分配到下一个可用的物理地址,无论 在逻辑上插入行/行。 已删除的行/ 缩写在清理物理存储后被回收 . 逻辑行/col和存储行/col之间的这种间接关系提供了三种功能: 1. 它用来去除空行和相体,提高存储密度. 2. 它避免了在行/行被插入并删除时复制单元格值(只是逻辑 - > 存储向量 页:1. 3. 它使我们能够在调和远程客户端的操作时"时间旅行"到以前的矩阵版本. 为了支持调和,我们使用每个PermutationVector的并购Tree. 合并Tree是命令7的B -Tree 临时保存一些额外的元数据,以调节当前协作窗口内的操作. ### 物理储存 单元格数据被存储在类似四面体的数据结构中,这种结构是16x16瓦的递归分出. 这个 执行杠杆 [莫顿编码](https://en.wikipedia.org/wiki/Z-order_curve) 将它作为级联执行 快速 1D 阵列访问 . ```ts const keyHi = r0c0ToMorton2x16(row >>> 16, col >>> 16); const keyLo = r0c0ToMorton2x16((row << 16) >>> 16, (col << 16) >>> 16); const level0 = this.root[keyHi]; if (level0 !== undefined) { const level1 = level0[byte0(keyLo)]; if (level1 !== undefined) { const level2 = level1[byte1(keyLo)]; if (level2 !== undefined) { const level3 = level2[byte2(keyLo)]; if (level3 !== undefined) { return level3[byte3(keyLo)]; } } } } return undefined; // Empty region ``` 将单元格数据存储在 [Z级](https://en.wikipedia.org/wiki/Z-order_curve) 是两行主和 col-major traversal从预接和缓存一致性中受益. 阅读/写到物理存储 相较于按顺序访问缓存本地热 JavaScript 数组,轴通常在数量顺序之内. ### 从 Last Write Win( LWW) 模式切换到 First Write Win( FWW) 模式 共享矩阵允许从LWW到FWW的单向切换. 这是用来处理冲突的 当多个客户端同时初始化一个单元格时. 使用 FWW 帮助客户获取 `conflict` 发生时的事件 他们的改变被拒绝。 他们可以用他们在事件中收到的新信息来解决冲突. 此事件仅在 SetCell 解析策略为 First Write( FWW) 时发布 。 当两个客户端发售时会发出此信息 种族和发送更改而不互相观察更改,最后排序的更改将被拒绝 只有更改被拒绝的客户才会通过这次活动得到通知,并期望合并更改 以会计方式提供新的信息(比赛获胜者提供的情况). 记录 LWW 期间如何应用或拒绝 Set 操作更改的一些案例 - > FWW 切换到一些客户端 使用 FWW 模式,有些则使用 LWW 模式。 当应用程序调用时 `switchSetCellPolicy` 策略改为 FWW 模式 立即,然后通过下一个SetOp向其他客户端通报,这是在矩阵上制作的. **案例1:** 当所有客户端已经切换到 FWW 模式时, 2 Set Op 之间的任何比赛都会导致一个 `conflict` 事件 在失败的客户端,直到它收到自己的最新Set op。 例如,客户端已经为单元格C1发送了操作. 接收远程 行动R1和R2为单元格C1。 它会首先提高 `conflict` 当它收到R1然后收到另一个时 `conflict` 当 它接收R2。 这将不断发生,直到它收到自己的行动,这样它的变化就不会因为冲突而失去. **案例2:** 客户端将策略切换到本地 FWW 。 尚未制作 SetOp 。 该客户端尚未待修改 。 收到时 远程 Set 操作, 此客户端将全部应用 . **案例3:** 客户端将策略切换到本地 FWW 。 此客户端正在等待单元格 C1 的更改 。 打开 接收远程 LWW 设定 C1 的操作, 这个客户端将拒绝它, 因为它自己的操作将最终应用 。 所以第一个FWW SetOp在某种意义上仍被视为LWW op. 现在让我们说,它已经收到了一个远程 FWW op for C1 而不是LWW op,然后 远程操作本可以被应用 导致客户的政策 转移到FWW与该操作。 也会引发冲突 本地事件作为其单元格 C1 的 Op 将被其他客户拒绝,因为它是一个失败者 Op . **案例4:** 在FWW模式下,当没有冲突时,客户端仍然能够覆盖单元格. 我们追踪序列 每个单元格上次编辑时的编号,并跟踪进行此修改的客户端ID。 如果收到 Op 为 单元格 C1 ,其对应序列号为 QQ ,以表示上次编辑的序列号,然后单元格为 覆写. 否则,如果同一客户端做出修改,那么操作仍将如客户端所知被应用 上一个编辑. **案例5:重联:** 当一个客户端在 LWW 模式下为单元格 C1 做断开状态的 op, 那么当它上线时 稍后,并赶上它看到一个FWW业务 对于C1,它会提高 `conflict` c1 事件,并且不会发送自己的操作. 在追赶过程中它会收到很多C1的操作,并且会提高 `conflict` 以胜利者为单位 c1行动. ## 客户最低要求 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/matrix 是什么？ 分布式矩阵 ### 如何安装 @fluidframework/matrix？ 在项目目录运行 npm install @fluidframework/matrix，或使用 pnpm add / yarn add / bun add。 ### @fluidframework/matrix 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fluidframework/matrix 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @fluidframework/matrix 可以商用吗？ @fluidframework/matrix 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fluidframework/matrix 的下载量有多少？ 根据 npm 官方下载统计，@fluidframework/matrix 在 2026/10/15 – 2026/11/13 这 30 天内被下载 14,461 次，日均约 482 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fluidframework/matrix 还在维护吗？ 最新版本 3\.12\.0 发布于 2026/11/11（4 天前）；至今共发布 695 个版本，其中过去 12 个月发布了 48 个；首次发布于 2020/09/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。