@ fluidframework/ 容器装入器

主题如下:

• @ fluidframework/ 容器装入器
  • 使用 Fluid 框架库
  • 安装
  • 从此软件包导入
  • API 文档
  • 流体装入器
  • 创建和装入已确认摘要
  • 主机执行者的期望
  • 集装箱运行时间和数据库执行者的期望值
  • 集装箱寿命
    • 正在装入
    • 连通性
    • 结束
      • Container.close()
      • Container.dispose()
  • 观众
  • 客户身份和客户身份
  • 处理错误
  • 连接事件
  • 连接状态过渡流程图
  • 只读状态
    • readonly
    • permissions
    • forced
    • storageOnly
  • 脏事
  • 客户最低要求
    • 支持的运行时间
    • 支持的工具
    • 模块分辨率
    • 模块格式
  • 贡献准则
  • 帮助
  • 商标

涉及其他地方的相关专题:

• 法定人数和提案

使用 Fluid 框架库

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

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

安装

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

npm i @fluidframework/container-loader

从此软件包导入

此软件包使用 packet.json 导出 通过支持级别将API分离. 有关支助保障的信息改为: API 支持级别。 。 。 .

导入 public API 从 @fluidframework/container-loader。 。 。 .

导入 legacy API 从 @fluidframework/container-loader/legacy。 。 。 .

API 文档

读取 @ fluidframework/ 容器装入器 API 文档 https://fluidframework.com/docs/apis/container-loader (中文(中国大陆) )。 。 。 .

流体装入器

装载器构成流体运行时间的最小内核. 此内核负责提供访问 流动存储以及就客户法定人数达成共识.

存储包括快照以及活的和持续的操作流.

共识系统允许协作窗口内的客户就容器的属性达成一致. 一个 实例是 npm 软件包,该软件包应装入处理适用于容器的操作.

创建和装入已确认摘要

loadSummarizerContainerAndMakeSummary 装入一个摘要容器,请求一份摘要,并在尝试后处理该容器. 成功需要摘要提交和广播. 装载器没有明确等待服务ACK,尽管运行时间可能等待作为其再试行为的一部分. 回来的 summaryResults.summaryInfo.handle 确定广播摘要建议. 无法保证识别一个可以装入 LoaderHeader.version。 。 。 . 使用 version 返回时间 loadAndSummarize 当需要一个确认的快照版本时.

迁移使用直接摘要 API 生成摘要然后加载其确认的版本的代码, 使用 loadAndSummarize数字 :

import { LoaderHeader } from "@fluidframework/container-definitions/legacy";
import {
    loadExistingContainer,
    loadAndSummarize,
} from "@fluidframework/container-loader/legacy";

// props supplies codeLoader, urlResolver, documentServiceFactory, and request.
const { version, referenceSequenceNumber } =
    await loadAndSummarize(props);
const container = await loadExistingContainer({
    ...props,
    request: {
        ...props.request,
        headers: { ...props.request.headers, [LoaderHeader.version]: version },
    },
});
// Use container, then dispose it when finished.

loadAndSummarize 返回时 { version, referenceSequenceNumber } 服务后确认并拒绝错误. version 来自 summaryAckOp.contents.handle,适合 LoaderHeader.version 用于支持加载快照版本的驱动程序. referenceSequenceNumber 来源于匹配的概要建议并识别摘要所捕获的文档状态. 总结容器在确认前保持活性. NACK,运行时间超时,断开,关闭,或处置导致尝试失败. 如果服务ACK未到达,运行时间会处理简要的重试和出站时间. 装载器除了运行时间的总结超时外,没有额外超时. 装入器用新容器重试每一次失败的尝试, 不论是否可重试 . 这遵循了在《公约》中引入的一次性复习办法 PR #25977 (英语)。 。 。 . 如果一个瞬态状态得到解决,但恢复得不到保证,新鲜的负载就可以成功. 两个返回的值都描述了成功的尝试.

主机执行者的期望

预计主机会收听本文档其他章节所描述的各种事件,并正确(以某种形式)向用户传递信息,以确保用户了解各种情况,不会丢失数据. 关于这些状态和事件的更详细情况,请参见具体章节 -- -- 本节仅作为摘要而未详列.

1. "断开"和"接通" 事件:主机既可通知用户没有连接(如果关闭容器,则可能丢失数据),也可拒绝编辑 Container.forceReadonly(true)
2. "关闭" 事件: 如果提出错误,主机负责以某种形式将错误传递给用户. 容器关闭时( 是否出错) 处于断开状态( read only) .
3. "只读" 事件:主机应向用户显示不能编辑容器。 用户权限可以在集装箱的寿命期间改变,但不能每个连接会话改变(换句话说,权限的改变会导致断开并重联). 建议主机在每次重联时重新检查此属性 .
4. 脏事:主机应该有一些合理的UX/工作流程,以确保用户不会出乎意料地丢失编辑. I.e. 有足够的信号(可能包括屏蔽关闭容器的用户)确保所有用户编辑完成存储,除非用户明确选择丢失这种编辑.
5. 封闭或处置集装箱: 在大多数情况下,您应当使用 IContainer.dispose(...) API 释放资源. 如果您打算在关闭后使用集装箱,或者需要向集装箱传递一些重大错误,请使用 IContainer.close(...) API (英语).

集装箱运行时间和数据库执行者的期望值

1. 尊重 "只读"状态。在此状态的容器运行时间(和数据存储)中,不应允许更改当地状态,因为这些变化将在关闭容器时丢失.
2. 维护 在飞行中,直到观察到它们被服务器确认。 在重新连接时重新提交任何丢失的 Ops 。 由DDS在Fluid框架提供的容器和数据库运行时间的库存执行中完成
3. 尊重 ""断开"和"接通" 状态,在断开时不提交操作.
4. 尊重 "处理" 事件,并将其作为"只读"和"断开"状态的组合处理. I. e. 它应该完全可以操作(放弃内容),但不允许编辑。 这相当于为主机在容器上的"封闭"事件,但范围更广(包括容器的代码版本升级).
5. 通过 IContainContext.update Dirty Container State 调用通知集装箱存在或缺少未保存的更改。 这需要用于 脏事 以正确表示用户编辑到主机的状态.

集装箱寿命

正在装入

集装箱因Loader.resolve()呼叫而返回。 装货机可以缓存容器,因此如果从同一装货机实例中请求同样的URI,则可以返回先前创建的容器. 这一点很重要,因为有些信头(如: pause由于集装箱的再利用,可能被忽视.

ILoaderHeader 内 装入器.ts 描述控制容器装载的属性.

连通性

通常当容器状态(和数据存储)从快照中还水时会返回容器. 除非我们.. IRequest.headers.pause 指定,将在某个时间(同步)和最近时间建立与订购服务的联系 操作将进行处理,允许本地更改将格式客户端流到服务器. Container.connectionState 说明是否建立了与订购服务的联系,以及 连接事件 正在通知连接变化。 虽然高度推荐听众在注册连接事件时检查初始状态,但新听众被要求注册以宣传当前状态. 即如果安装了"已连接"和"已连接"两个收听器时一个容器被断开,则新安装的用于"已连接"事件的收听器将会在注册时被调用.

结束

集装箱可以通过电话直接通过主机关闭 Container.close() 和(或) Container.dispose()。如果集装箱预计在关闭时使用,或者需要将自己的关键错误传递到集装箱上,则使用 close() API (英语). 否则,使用 dispose() API (英语). 以下各节详述这些方法之间的差异.

Container.close()

集装箱一旦关闭,就终止与订购服务的联系,任何本地变化(以前或将来)都不会传播给储存。 容器使用此方法 页:1 仍被期望使用,需要将容器切换为"安全"状态来取景. 例如,允许用户将内容从容器中复制出.

"封闭"状态有效意味着容器永远被断开,无法再连接.

如果一段时间后不再需要一个封闭的容器,请拨打 Container.dispose() 将处理运行时间资源 .

由于一些重大错误,集装箱也可自行关闭和(或)通过运行时间加以处置。 关键错误可以是内部的(如操作命令中违反不变量),也可以是外部的(文件被删除了). 请看 处理错误 更多细节.

集装箱关闭时,下列情况属实(无特定顺序):

1. 集装箱。 关闭财产被设定为真实
2. 带有可选错误对象的容器发生“关闭”事件起火(表明关闭的原因;如果缺失-关闭是由于主机关闭容器)
3. "只读"事件在 DeltaManager & Container (和 Container.只读属性设定为真实)上起火,向所有数据存储显示容器只读,数据存储不应该允许本地编辑,因为他们不会完成.
4. "断开"事件起火,如果连接在集装箱关闭时活动.

"closed" 活动在容器中可供主机使用.

Container.dispose()

一旦处置,集装箱将终止与订购服务的联系,任何局部变化(以前或未来)不会传播到储存中。 当容器是 没有 预期会再使用.

处置容器时,下列情况属实(无特定顺序):

1. 集装箱。 关闭财产被设定为真实
2. 集装箱被"处置"事件起火
3. "断开"事件起火,如果连接在容器处置时是活跃的.
4. 容器运行时间发生"处置"事件起火

"disposed" 活动在容器中可供主机使用. "dispose" 当容器被处置时,事件会交付给容器运行时间,但当提出新的代码建议,并且按照新版本的代码(和集装箱运行时间)被装入时,容器运行时间也会被处置.

观众

Container.audience 暴露一个跟踪所有连接客户端到同一容器的物体.

• getMembers() 可用于检索当前用户群
• getMember() 可用于获取特定客户端的 IClient 信息( 如果客户端没有连接则返回未定义)
• "addMember" 当新成员加入时,事件会提高
• "removeMember" 当一个较早连接的成员离开时( 与容器断开) , 事件会被提起

getMembers() 财务报告和审定财务报表 "addMember" 事件提供 用户 描述连接类型、权限和用户信息的界面:

• clientId 是密钥 - 它是唯一的会话的ID 。 请看 客户身份和客户身份 ,以及如何适当区分人与代理客户以及客户ID和用户ID之间的差异.
• IClient.mode尤其描述了客户端的连接模式:
  • "写"指客户端已经读取/写出连接,可以更改容器内容,并参加法定人数
  • "已读"表示客户端为已读连接. 这类客户不能修改容器,也不参加法定人数. 也就是说,"已读"并不表示客户端权限,即客户端可能拥有只读权限到一个文件,或可能暂时连接为只读权限,以减少服务器上的COGS,而不会"修改"容器(任何已读连接生成加入并留下更改容器并更改"由"属性所编辑"的信息)

请注意,如果客户端失去订购服务器的连接,那么此时的受众信息不会被重置. 它会在客户端断开时变得僵化,并在客户端连接回容器时刷新. 详情请见 连接事件 节

客户身份和客户身份

Container.clientId 揭发客户身份 订购服务会为所有连接的客户端分配独特的随机ID. 请注意,如果同一用户在3个不同的机器上打开同一个容器,那么会有3个客户端ID跟踪同一用户的3个会话.

连接到一个容器的单一用户可能导致容器的多个会话(从而导致多个客户端ID). 这是由于各种物剂(包括总结物剂)在人类身边工作所致. 你可以发挥杠杆作用 IClient.details.capabilities.interactive 区分人类和特工 当显示用户存在时( 如在coauth 画廊) 此属性应用来过滤 bots

IClient.user代表用户ID(存储中),可用于识别来自同名用户(来自同名或不同的机器)的会话.

处理错误

暴露错误有两种方式:

1. 在开放时间, 通过从 Loader.resolve () 或 Loader. request () 返回被拒绝的许诺
2. 作为一名 "closed" 当容器因严重错误而关闭时.
3. 作为一名 "warning" 在容器上的活动.

关键错误可以在#1 & #2工作流程中出现. 例如,数据存储URI可能指向被删除的文件,这将导致容器打开出错. 但文件也可以在打开容器时被删除,导致通过"error"处理器提升出相同的出错类型.

错误为 ICritical 容器错误 类型和警告 集装箱警告 类型。 两者都有 errorType 属性,描述错误类型(和错误对象的适当接口):

     readonly errorType: string;

错误有4个来源:

1. 容器错误类型 - 在加载器级别上提出的错误警告( w)
2. 驱动程序错误类型 - 可能从驾驶员一级引起的错误
3. Odsp 错误类型 财务报告和审定财务报表 路由错误类型 - ODSP和R11S驾驶员提出的错误.
4. 运行时出错, 如 "summarizingError", (中文(简体) ), "dataCorruptionError"。这一类错误不是预先确定的,而是取决于装入的容器的类型.

ICriticalContainerError.errorType 是字符串,它代表上面描述的由4个错误类型组成的结合。 主机应用程序可能包装不同的驱动程序并打开不同类型的容器,只有主机应用程序可能有足够的信息来列举此类情景中所有可能的错误代码.

主机必须听 "closed" 活动。 如果存在出错对象,则由于出错而关闭了容器,需要以某种方式向用户传达这些信息. 如果没有出错对象,则由于主机应用程序调用Container.close()而关闭(没有指定出错). 集装箱关闭时,不再与订购服务相接. 它也处于只读状态,与数据存储通信,不允许用户更改容器.

连接事件

集装箱举办了两次活动,向托管申请通报连接问题和连接状况.

• "connected" 当容器连接并更新时,即客户端和服务器之间正在变化时,事件会上升.
• "disconnected" 当容器失去连通性(出于任何原因)时,会提出事件.

集装箱也暴露 Container.connectionState 属性以显示当前状态.

在正常情况下,集装箱将试图尽快重新连接回订购服务。 但是如果计算机脱机,它会缩小复试范围. 因此,如果ITHROTLING警告 通过 "warning" 处理器,然后容器遵循存储节流政策,并在一段时间后试图重新连接(IThrottlingWarning.retryAfterSeconds) (中文(简体) ).

如果 Container.disconnect() 是在失去连接之前调用。 如果主机应用程序执行"用户离开"类型的体验来降低客户端和服务器在用户离开时保持连接的成本,这可能会有所帮助. 通话 Container.connect() 将可重复自动重联,但主机可能需要允许额外的重联时间,因为它可能涉及其他客户端在未连接时生成的许多Ops的象征性取取和处理.

数据存储器几乎永远不应该听到这些事件(详见 只读状态如果客户之间需要同步活动,则应使用协商一致的DS。 DDSs 监听这些事件,以便知道何时重新提交待定的操作.

主机应用程序可以使用这些事件,以便在用户更改没有通过系统传播时向用户表示,从而可以丢失(在浏览器标签被关闭上). 建议在显示这种UI之前使用一些延迟(如5秒),因为网络连接可能是间歇性的. 此外,如果集装箱由于 Container.disconnect() 被调用, 可能需要一段时间才能连接 和电流.

请注意,主机可以执行各种关于如何处理断开的战略. 有些人可能决定显示一些UX让用户知道,如果容器在断开时被关闭,可能丢失数据. 其他人可以在下线时强迫容器不允许用户编辑(见 只读状态) (中文(简体) ).

需要指出的是,被连接并不意味着所有的用户编辑都保存在容器关闭上. 系统存在耐用性,装载层在此不提供任何保证. 并不是每个执行都需要一个解决方案(游戏可能不关心),因此解决这个问题被推到框架层面(即拥有一个可以曝光的数据存储) 'dirtyDocument' 发送来自ContainerRuntime的信号并请求能够返回这种数据存储的路径.

连接状态过渡流程图

flowchart TD;
    A(Disconnected)-->B{Reconnect on error if \n AutoReconnect Enabled?};
    B--Yes-->C(Establishing Connection);
    B--No-->D[Connection during Container \n connect call];
    D-->C
    C-->E{Connection Success \n including any Retry?};
    E--No-->F[Error or container.close or container.disconnect];
    A-->F;
    F-->A;
    E--Yes-->G(Catching Up);
    G-->F;
    G-->H{Which Connection Mode?};
    H--Read-->I(Connected);
    H--Write-->J[Wait for Join Op];
    J-->I;
    I-->F;

只读状态

用户权限可在集装箱寿命期间发生变化。 它们不能在单个连接会话中改变(换句话说,权限的改变会导致断开并重新连接). 建议主机在每次重联时重新检查此属性 .

Delta经理会发射一个 "readonly" 事件。 只读事件可被数据存储和DS访问(通过ContainerRuntime.deltaManager). 预计数据存储会遵守要求并曝光只读(或"不编辑")的经验.

Container.readOnlyInfo (和 DeltaManager.readOnlyInfo)向主机显示文件是否可写. 它包含以下属性:

readonly

以下是:

• true: 集装箱只读. 下面列出的一个或数个其他属性将是: true。 。 。 .
• undefined: 运行时尚不知道文件是否可写入 。 目前我们在这里只得到一个信号 当websocket连接到服务器.
• false: Container. ForceReadlen () 从未被调用过,或者最后一次通话是用虚假的,此外,已知用户对文件有写权限.

permissions

有两个案子 true数字 :

1. 用户没有修改此容器的写权限( 此容器通常会映射到存储中存档, 且没有给定用户的写权限)
2. 集装箱因重大错误或主机关闭而关闭。 见 集装箱寿命 财务报告和审定财务报表 处理错误 更多细节.

forced

true 如果由于主机呼叫,容器处于只读模式 Container.forceReadonly(true)。 。 。 . 这对于下列情况可能有用:

• 互联互通的丧失,在主机选择防止用户编辑方法时会超过(或除此之外)显示断开的UX并警告用户关闭容器时可能的数据丢失.
• 主机中的特殊只查看模式 。 例如,主机可以用来预览与其他主机内容一起放置的容器内容,并借助全屏/单独的窗口体验进行编辑.

storageOnly

只存储模式是一种只读模式,其中容器不连接到三角洲流并无法提交或接收操作. 这对于查看文件的特定版本很有用.

脏事

集装箱运行时间可以与集装箱通信,以获得集装箱的当前状态. 作为回应,容器将提出两个事件 - "dirty" 财务报告和审定财务报表 "saved" 事件。 这两个事件之间的过渡表明存在(或缺乏)用户更改没有被保存到存储中. 换句话说,如果容器是脏的,此时关闭它将导致从用户角度上的数据丢失,因为并非所有的用户更改都让它被存储. 这些信息可以被一个主机用来构建适当的UX,让用户对平台有信心. 例如,一个主机可能会选择显示一个对话框,询问用户在关闭前是否想要保存他们的修改. 而不是,或除此之外,主机可能选择在UX某处显示"Save..."和"saved"文本. 再加上缺乏连接来订购服务(以及给用户适当通知),这可能给用户造成足够的连续通知,在关闭时不需要屏蔽对话框. 请注意,当一个活动连接到位时,改变会被冲出存储,只是时间问题,除非产生某种持续的局部变化源来阻止容器永远被完全保存. 但如果没有主动连接,例如因为用户已经下线,那么文档可能会在很长一段时间内处于肮脏状态.

Container.isDirty 可用于获取当前容器状态.

客户最低要求

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.

贡献准则

你们可以 贡献 通过这些方式实现流体框架:

• 回答问题 GitHub 讨论。 。 。 .
• 提交错误报告 并且帮助验证修正.
• 审查 源代码更改。 。 。 .
• 贡献错误修正。 。 。 .

详细指示改为: repo 文档。 。 。 .

本项目遵循 Microsoft 开源行为守则。 。 。 . 更多信息,改为: 《行为守则》经常被问到的问题。 。 。 . 问题或评论,联系 打开码@ microsoft.com。 。 。 .

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

帮助

读取 流体框架文件 用于了解流体框架概念和API.

要求提供文件未载列的资料, 创建问题。 。 。 .

商标

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

这些商标或标志的使用必须遵循微软的 商标和品牌准则。 。 。 .

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