文档#

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

  • 扩展(顶层):应用程序扩展扩展了 JupyterLab 本身的功能,我们将在开发扩展中介绍它们。

  • 文档小部件扩展(较低层): 文档小部件扩展扩展了添加到应用程序的文档小部件的功能,我们将在本节中介绍它们。

在本节中,“文档”一词指的是任何由存储在磁盘上的文件支持的可视化事物(即使用 Contents API)。

文档架构概述#

JupyterLab 中的“文档”由实现 IModel 接口的模型实例表示。模型接口有意设计得相当小,并专注于表示文档中的数据和发出该数据的更改信号。每个模型都有一个关联的 上下文 实例。模型的上下文是文档内部数据(存储在模型中)与文件元数据以及文件上可能的操作(例如保存和恢复)之间的桥梁。由于许多对象都需要上下文和模型,因此上下文包含对其模型的引用作为其 .model 属性。

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

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

文档小部件 表示文档模型的一个视图。单个文档模型可以关联多个文档小部件,它们之间自然会保持同步,因为它们是相同底层数据模型的视图。

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

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

文档注册表#

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

  • 文件类型

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

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

  • 小部件扩展工厂

注意

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

小部件工厂#

为给定文件创建一个小部件。

如果多个小部件工厂与同一文件类型关联,用户将能够在文件浏览器上下文菜单中使用“打开方式”列表选择其中一个。

版本 4.4 中新增: 小部件工厂现在可以接受 contentProviderId 参数,允许小部件修改内容提供方式。例如,使用自定义提供者可以分块而不是一次性获取文档内容。

示例

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

模型工厂#

为给定文件创建模型。

模型通常通过用于获取模型的内容选项(例如文本、base64、笔记本)进行区分。

小部件扩展工厂#

向小部件类型添加额外功能。为每个小部件实例创建一个扩展实例,使扩展能够向每个小部件添加功能或观察小部件和/或其上下文。

示例

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

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

文件类型#

通过 JupyterLab 中的 mimetype 和文件扩展名添加要理解的新文件类型。

文档模型#

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

文档上下文#

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

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

上下文和模型分开的原因是为了方便创建模型工厂,而上下文的繁重工作则留给文档管理器。上下文不应被子类化或重新实现。相反,上下文旨在成为文档模型和更广泛应用程序之间的桥梁。

共享模型#

@jupyter/ydoc 包包含一个 ISharedNotebook 和一个 ISharedFile,它们是如果您想操作笔记本或文本文件时要使用的抽象接口。

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

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

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

文档管理器#

文档管理器处理

  • 文档模型

  • 文档上下文

文件浏览器使用文档管理器打开和管理文档。