文档#
JupyterLab 可以通过多种方式进行扩展
扩展(顶层):应用程序扩展扩展了 JupyterLab 本身的功能,我们将在开发扩展中介绍它们。
文档小部件扩展(较低层): 文档小部件扩展扩展了添加到应用程序的文档小部件的功能,我们将在本节中介绍它们。
在本节中,“文档”一词指的是任何由存储在磁盘上的文件支持的可视化事物(即使用 Contents API)。
文档架构概述#
JupyterLab 中的“文档”由实现 IModel 接口的模型实例表示。模型接口有意设计得相当小,并专注于表示文档中的数据和发出该数据的更改信号。每个模型都有一个关联的 上下文 实例。模型的上下文是文档内部数据(存储在模型中)与文件元数据以及文件上可能的操作(例如保存和恢复)之间的桥梁。由于许多对象都需要上下文和模型,因此上下文包含对其模型的引用作为其 .model 属性。
单个文件路径可以有多个不同的模型(因此有不同的上下文)来表示该文件。例如,笔记本可以以笔记本模型和文本模型打开。同一文件路径的不同模型不直接相互通信。
模型包含一个 ISharedDocument 实例,作为模型内容的数据存储。从 JupyterLab 4 开始,默认的数据存储实现是基于 Yjs 的 YDocument,Yjs 是一种用于构建协作应用程序的高性能 CRDT。接口和实现都由包 @jupyter/ydoc 提供。
文档小部件 表示文档模型的一个视图。单个文档模型可以关联多个文档小部件,它们之间自然会保持同步,因为它们是相同底层数据模型的视图。
文档注册表 是注册文档类型和工厂的地方。插件可以请求文档注册表实例并注册其内容类型和提供者。
文档管理器 使用文档注册表来为文档创建模型和小部件。文档管理器处理应用程序中文档的生命周期。
文档注册表#
JupyterLab 应用程序中的文档小部件扩展可以注册
文件类型
特定文件类型的模型工厂
特定模型工厂的小部件工厂
小部件扩展工厂
注意
我们建议您查看文档示例,以帮助理解实际案例。
小部件工厂#
为给定文件创建一个小部件。
如果多个小部件工厂与同一文件类型关联,用户将能够在文件浏览器上下文菜单中使用“打开方式”列表选择其中一个。
版本 4.4 中新增: 小部件工厂现在可以接受 contentProviderId
参数,允许小部件修改内容提供方式。例如,使用自定义提供者可以分块而不是一次性获取文档内容。
示例
创建 NotebookPanel 小部件的笔记本小部件工厂。
模型工厂#
为给定文件创建模型。
模型通常通过用于获取模型的内容选项(例如文本、base64、笔记本)进行区分。
小部件扩展工厂#
向小部件类型添加额外功能。为每个小部件实例创建一个扩展实例,使扩展能够向每个小部件添加功能或观察小部件和/或其上下文。
示例
为 NotebookPanel 小部件创建的 ipywidgets 扩展。
向每个 NotebookPanel 小部件的工具栏添加一个按钮。
文件类型#
通过 JupyterLab 中的 mimetype 和文件扩展名添加要理解的新文件类型。
文档模型#
由模型工厂创建并传递给小部件工厂和小部件扩展工厂。模型是我们与文档数据交互的方式。对于简单的文本文件,我们通常只使用 to/fromString()
方法。更复杂的文档(如笔记本)包含更多交互点,如笔记本元数据。
文档上下文#
由文档管理器创建并传递给小部件工厂和小部件扩展。上下文包含模型作为其属性之一,因此我们可以传递单个对象。
它们用于为给定模型提供 @jupyterlab/services
中的会话和 Contents API 的抽象接口。它们可以在小部件之间共享。
上下文和模型分开的原因是为了方便创建模型工厂,而上下文的繁重工作则留给文档管理器。上下文不应被子类化或重新实现。相反,上下文旨在成为文档模型和更广泛应用程序之间的桥梁。
文档管理器#
文档管理器处理
文档模型
文档上下文
文件浏览器使用文档管理器打开和管理文档。