文档

JupyterLab 可以通过多种方式进行扩展

• 扩展（顶层）：应用程序扩展扩展了 JupyterLab 本身的功能，我们在 开发扩展 中介绍了它们。

• 文档小部件扩展（底层）：文档小部件扩展扩展了添加到应用程序的文档小部件的功能，我们在本节中介绍了它们。

在本节中，术语“文档”指的是任何以磁盘上存储的文件为后盾的视觉内容（即使用 Contents API）。

文档架构概述

JupyterLab 中的“文档”由实现 IModel 接口的模型实例表示。模型接口有意地非常小，并且专注于表示文档中的数据并向该数据发出更改信号。每个模型都与一个关联的 context 实例相关联。模型的上下文是文档内部数据（存储在模型中）与文件元数据和对文件可能的操作（例如保存和还原）之间的桥梁。由于许多对象都需要上下文和模型，因此上下文在其 .model 属性中包含对模型的引用。

单个文件路径可以有多个不同的模型（因此有多个不同的上下文）来表示该文件。例如，笔记本可以用笔记本模型和文本模型打开。同一文件路径的不同模型不会直接相互通信。

模型包含一个 ISharedDocument 实例，该实例充当模型内容的数据存储。从 JupyterLab 4 开始，默认数据存储实现是基于 YDocument 的 Yjs，这是一个用于构建协作应用程序的高性能 CRDT。接口和实现均由包 @jupyter/ydoc 提供。

文档小部件 表示文档模型的视图。可以有多个文档小部件与单个文档模型相关联，并且它们自然地保持同步，因为它们是同一底层数据模型的视图。

文档注册表 是注册文档类型和工厂的地方。插件可以要求文档注册表实例并注册其内容类型和提供程序。

文档管理器 使用文档注册表为文档创建模型和小部件。文档管理器处理应用程序中文档的生命周期。

文档注册表

JupyterLab 应用程序中的文档小部件扩展可以注册

• 文件类型

• 特定文件类型的模型工厂

• 特定模型工厂的小部件工厂

• 小部件扩展工厂

注意

我们建议您查看 文档示例 以帮助理解实际案例。

小部件工厂

为给定文件创建小部件。

示例

• 创建 NotebookPanel 小部件的笔记本小部件工厂。

模型工厂

为给定文件创建模型。

模型通常通过用于获取模型的内容选项（例如文本、base64、笔记本）来区分。

小部件扩展工厂

为小部件类型添加附加功能。为每个小部件实例创建一个扩展实例，使扩展能够为每个小部件添加功能或观察小部件及其上下文。

示例

• 为 NotebookPanel 小部件创建的 ipywidgets 扩展。

• 在每个 NotebookPanel 小部件的工具栏中添加一个按钮。

文件类型

添加一种新的文件类型，以便通过 JupyterLab 中的 mimetype 和文件扩展名来理解。

文档模型

由模型工厂创建，并传递给小部件工厂和小部件扩展工厂。模型是与文档数据交互的方式。对于简单的文本文件，我们通常只使用 to/fromString() 方法。更复杂的文档（如笔记本）包含更多交互点，例如笔记本元数据。

文档上下文

由文档管理器创建，并传递给小部件工厂和小部件扩展。上下文包含模型作为其属性之一，以便我们可以传递单个对象。

它们用于为给定模型提供来自 @jupyterlab/services 的会话和内容 API 的抽象接口。它们可以在小部件之间共享。

单独的上下文和模型的原因是，它可以轻松创建模型工厂，而上下文的繁重工作留给文档管理器。上下文不应被子类化或重新实现。相反，上下文旨在成为文档模型和更广泛的应用程序之间的粘合剂。

共享模型

@jupyter/ydoc 包包含一个 ISharedNotebook 和一个 ISharedFile，它们是如果您想操作笔记本或文本文件，则可以针对其进行操作的抽象接口。

这些模型包装了一个 Yjs 文档 (Y.Doc)，它表示客户端之间的共享文档，并保存多个共享对象。它们使您能够共享不同的 数据类型，如文本、数组、映射或集合，以创建不同类型的协作应用程序。

此外，共享模型具有一个 Awareness 属性。此属性与 Y.Doc 链接，这意味着每个文档都有一个 Awareness 对象，用于共享光标位置和存在信息。Awareness 是 Yjs 的实现细节，不是 ISharedDocument 接口的一部分。

请查看 @jupyter/ydoc 文档 以了解有关此包的更多信息。

文档管理器

文档管理器处理

• 文档模型

• 文档上下文

文件浏览器使用 文档管理器来打开文档并管理它们。