@ fluidframework/matrix (英语)
共享Matrix是一个长方形的2D值阵列. 矩阵值是包含嵌入式IFluidHandle对流体对象的引用的JSON序列式类型的超集.
使用 Fluid 框架库
对于依赖流体框架库的公共API,我们建议 ^ (caret)版本范围.
例如,使用 ^1.3.4。 。 。 .
依赖不稳定的API,例如: beta API,我们推荐一个更具限制性的版本范围.
例如,使用一个 ~ 版本范围.
安装
运行此命令以安装软件包 :
npm i @fluidframework/matrix
从此软件包导入
此软件包使用 packet.json 导出 通过支持级别将API分离. 有关支助保障的信息改为: API 支持级别。 。 。 .
导入 public API 从 @fluidframework/matrix。 。 。 .
导入 legacy API 从 @fluidframework/matrix/legacy。 。 。 .
API 文档
读取 @ fluidframework/matrix (英语) API 文档 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.
- 它使我们能够在调和远程客户端的操作时"时间旅行"到以前的矩阵版本.
为了支持调和,我们使用每个PermutationVector的并购Tree. 合并Tree是命令7的B -Tree 临时保存一些额外的元数据,以调节当前协作窗口内的操作.
物理储存
单元格数据被存储在类似四面体的数据结构中,这种结构是16x16瓦的递归分出. 这个 执行杠杆 莫顿编码 将它作为级联执行 快速 1D 阵列访问 .
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级 是两行主和 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同时收到 上游支助。 。 。 .
- 流体框架将停止支持第22版 当上游支持于2027-04-30结束时。 。 。 .
- 流体框架不支持节点.js与
--no-experimental-fetch旗帜.
- Fluid框架支持支持ES2022标准库的现代浏览器.
支持的工具
- 类型脚本 6.0数字 :
- 流体框架支持全部
strict选项. - 设定建设目标(
lib, (中文(简体) ),target改为:ES2022或后会. - 启用
strictNullChecks。 。 。 . - 流体框架不支持 在 TypeScript 6.0 中贬值的配置选项。 。 。 .
- 流体框架不完全支持
exactOptionalPropertyTypes。 。 。 . 如果您启用此选项, 请不要使用in, (中文(简体) ),Reflect.has, (中文(简体) ),Object.hasOwn,或Object.prototype.hasOwnProperty改为Fluid框架类型的窄成员. 这些方法可以错误地排除undefined从可能的值.
- 流体框架支持全部
- 网络软件包 页:1
- 我们不需要一个特定的捆绑者. 其他处理ES模块的捆绑机可以工作,但我们只积极测试网页包.
模块分辨率
在类型脚本中 compilerOptions,使用时 Node16, (中文(简体) ), Node20, (中文(简体) ), NodeNext,或 Bundler 模块分辨率.
这些设置遵循 节点.js v12+无害环境管理 分辨率和加载算法。 。 。 .
不使用 Node10 模块分辨率.
模块格式
- ES模块: 使用ES模块来消耗Fluid框架客户端软件包,包括在Node.js中.
- 常见JS : Fluid Framework在3.0版本或后期不正式支持CommonJS.
贡献准则
你们可以 贡献 通过这些方式实现流体框架:
详细指示改为: repo 文档。 。 。 .
本项目遵循 Microsoft 开源行为守则。 。 。 . 更多信息,改为: 《行为守则》经常被问到的问题。 。 。 . 问题或评论,联系 打开码@ microsoft.com。 。 。 .
这个项目可能包含微软项目的商标或标志,产品,或服务. 这些商标或标志的使用必须遵循微软 商标和品牌准则。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.
帮助
读取 流体框架文件 用于了解流体框架概念和API.
要求提供文件未载列的资料, 创建问题。 。 。 .
商标
这个项目可能包含微软项目的商标或标志,产品,或服务.
这些商标或标志的使用必须遵循微软的 商标和品牌准则。 。 。 .
在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.