扩展迁移指南#

JupyterLab 4.4 到 4.5#

文件浏览器更新#

现在，当选定的文件和文件夹发生变化时，文件浏览器会发出 selectionChanged 信号。

如果您维护一个实现 DirListing 子类并改变选择的扩展，建议在选择改变时发出 selectionChanged 信号。这将确保 selectionChanged 信号的任何监听器都会收到更改通知。

API 更新#

NbConvert.IManager 接口已修复，不再要求实现该接口的类提供具体的 NbConvertManager 类。此外，此接口现在包含一个可选的 exportAs 方法，用于将笔记本导出（并可选地下载）为特定格式。
NbConvertManager.IExportFormats 接口已移至 NbConvert 命名空间。您现在应该使用 NbConvert.IExportFormats 而不是 NbConvertManager.IExportFormats。但是，为了向后兼容，NbConvertManager.IExportFormats 仍然保留。

`extra_labextensions_path` 排序#

默认的 labextension 路径现在优先于 extra_labextensions_path 中找到的路径。换句话说，BaseExtensionApp.labextensions_path 现在列出了 LabApp.labextensions_path 中的扩展，然后再列出 extra_labextensions_path 中找到的扩展。

JupyterLab 4.3 到 4.4#

图标#

@jupyterlab/debugger 图标已移至 @jupyterlab/ui-components。正在使用的图标位于 ui-components/style/icons/debugger 文件夹中，而 @jupyterlab/debugger 包中未使用的图标位于 ui-components/style/unused/ 文件夹中。

更新的导入#
之前	之后
`import { closeAllIcon } from '@jupyterlab/debugger/lib/icons';`	`import { closeAllIcon } from '@jupyterlab/ui-components';`
`import { continueIcon } from '@jupyterlab/debugger/lib/icons';`	`import { runIcon } from '@jupyterlab/ui-components';` 或 `import { runIcon as continueIcon } from '@jupyterlab/ui-components';`
`import { exceptionIcon } from '@jupyterlab/debugger/lib/icons';`	`import { exceptionsIcon } from '@jupyterlab/ui-components';` 或 `import { exceptionsIcon as exceptionIcon } from '@jupyterlab/ui-components';`
`import { openKernelSourceIcon } from '@jupyterlab/debugger/lib/icons';`	`import { openKernelSourceIcon } from '@jupyterlab/ui-components';`
`import { pauseIcon } from '@jupyterlab/debugger/lib/icons';`	`import { pauseIcon } from '@jupyterlab/ui-components';`
`import { stepIntoIcon } from '@jupyterlab/debugger/lib/icons';`	`import { stepIntoIcon } from '@jupyterlab/ui-components';`
`import { stepOutIcon } from '@jupyterlab/debugger/lib/icons';`	`import { stepOutIcon } from '@jupyterlab/ui-components';`
`import { stepOverIcon } from '@jupyterlab/debugger/lib/icons';`	`import { stepOverIcon } from '@jupyterlab/ui-components';`
`import { stopIcon } from '@jupyterlab/debugger/lib/icons';`	`import { stopIcon } from '@jupyterlab/ui-components';` 或 `import { stopIcon as terminateIcon } from '@jupyterlab/ui-components';`
`import { variableIcon } from '@jupyterlab/debugger/lib/icons';`	`import { variableIcon } from '@jupyterlab/ui-components';`
`import { viewBreakpointIcon } from '@jupyterlab/debugger/lib/icons';`	`import { viewBreakpointIcon } from '@jupyterlab/ui-components';`

TypeScript 更新#

作为 TypeScript 5.5 更新的后续，@jupyterlab/buildutils 包的 tsconfig.json 配置将 module 选项从 commonjs 更改为 Node16

index 7095bede4bd5..8c5bff0d45d8 100644
--- a/buildutils/tsconfig.json
+++ b/buildutils/tsconfig.json
@@ -3,7 +3,7 @@
  "compilerOptions": {
    "outDir": "lib",
    "rootDir": "src",
-   "module": "commonjs",
+   "module": "Node16",
    "moduleResolution": "node16"
  },
  "include": ["src/*"],

GroupItem 中条件渲染的支持#

自 JupyterLab 4.4 起，GroupItem 组件现在支持元素的条件渲染。此改进允许组件优雅地处理 null 或 undefined 子元素，从而无需使用 <div></div> 等占位符元素。

推荐的扩展作者更新： 检查您对 GroupItem 的使用，并将任何用作占位符的空元素替换为 null 值。此更改可确保代码更清晰、更易于维护，同时利用更新的渲染逻辑。

示例更新

之前

<GroupItem spacing={8}>
  {condition ? <SomeComponent /> : <div></div>}
</GroupItem>

之后

<GroupItem spacing={8}>
  {condition ? <SomeComponent /> : null}
</GroupItem>

此更改改善了使用 GroupItem 组件的扩展的渲染性能和可维护性。

API 更新#

ConfigSection.create(options: ConfigSection.IOptions) 函数已弃用。
这以前是一个辅助函数，用于在 Jupyter Server 上创建配置部分。相反，在插件中请求 IConfigSectionManager 令牌，然后使用 create 方法创建配置部分

const plugin: JupyterFrontEndPlugin<void> = {
  id: 'example',
  requires: [IConfigSectionManager],
  activate: (
    app: JupyterFrontEnd,
    configSectionManager: ConfigSection.IManager
  ): void => {
     const section = configSectionManager.create({ name: 'notebook' });
  }
};

插件#

@jupyterlab/application-extension 从 4.3 到 4.4
- @jupyterlab/application:mimedocument 插件 ID 已重命名为 @jupyterlab/application-extension:mimedocument
@jupyterlab/help-extension 从 4.3 到 4.4
- @jupyterlab/help-extension:licences 插件 ID 已移至 @jupyterlab/apputils-extension 扩展，现在分为 @jupyterlab/apputils-extension:licenses-client 和 @jupyterlab/apputils-extension:licenses-plugin
@jupyterlab/lsp-extension 从 4.3 到 4.4
- @jupyterlab/lsp:ILSPCodeExtractorsManager 插件 ID 已重命名为 @jupyterlab/lsp-extension:code-extractor-manager
@jupyterlab/translation-extension 从 4.3 到 4.4
- @jupyterlab/translation:translator 插件 ID 已重命名为 @jupyterlab/translation-extension:translator
@jupyterlab/workspaces-extension 从 4.3 到 4.4
- @jupyterlab/workspaces:commands 插件 ID 已重命名为 @jupyterlab/workspaces-extension:commands

JupyterLab 4.2 到 4.3#

CSS 样式#

以前，JupyterLab 会全局泄漏 CSS 规则。从 4.3 开始，这种情况不再发生。对扩展的副作用是

附加到应用程序 shell 外部的 DOM 元素可能样式损坏。要解决此问题，您应该将类 jp-ThemedContainer 添加到应用程序 shell 外部添加的 DOM 元素中。
DOM 元素 code、kbd、pre、samp 和 tt 可能样式损坏。要解决此问题，请在您的规则前加上类 .jp-ThemedContainer；例如 .jp-Inspector-content pre 变为 .jp-ThemedContainer .jp-Inspector-content pre

jp-Inspector-default-content 类已重命名为 jp-Inspector-placeholderContent。此上下文帮助类的名称现在与等效的目录和属性检查器类保持一致。

JupyterLab 4.3 已将其对 @lumino/widget 的依赖更新到 2.5.0 版本，该版本删除了以下小部件的全局样式

.lm-Widget {
  overflow: hidden;
}

如果您发现扩展的样式存在一些不一致之处，您可能需要将此通用规则重新添加到扩展的 CSS 中，或者（最好）将其作用域限定为相关小部件。

使用 Galata 进行测试#

Playwright 已更新到版本 1.46.1（或更高版本）。版本 1.46.0 的更新日志提到了在定义对象数组的 fixture 值时可能存在的破坏性更改。

有关更多信息，请参阅 Playwright 1.46.0 发行说明。

共享模型#

现在，共享单元格模型上设置的输出预计将封装在 Y.Map 对象中，而不是作为普通对象提供（或者在后端设置时，作为 pycrdt Map 对象而不是字典提供）。此外，对于 "stream" 类型的输出，"text" 条目现在必须指定为 Array<string> 对象，以实现更好的性能。使用普通对象已被弃用，并将在未来版本中停止工作。有关参考，请参阅 PRs

JupyterLab 4.1 到 4.2#

API 更新#

CodeEditor.ICoordinate 接口已更正，不包含 toJSON()、x、y、width 和 height；这些属性从未由返回 ICoordinate 的方法设置，也从未由接受它的方法使用。
CodeEditor.getCoordinateForPosition 的返回类型已更正，以澄清它可以返回 null；以前，尽管返回类型表明它将始终返回非空 ICoordinate 值，但仍可能返回 null。
命令 workspace-ui:save 和 workspace-ui:save-as 已从 @jupyterlab/apputils-extension:workspaces 插件移至一个新的专用 @jupyterlab/workspaces-extension 包，可以通过请求 IWorkspaceCommands 令牌显式要求。此令牌默认由新的 @jupyterlab/workspaces-extension:commands 插件提供。@jupyterlab/apputils-extension:workspaces 插件现在仅定义用于将 .jupyterlab-workspace 扩展名的文件作为 JupyterLab 工作区打开的工作区 MIME 类型渲染器。
单元格工具栏节点已从单元格节点移动到单元格输入节点。因此，单元格工具栏的父级已更改，不能再直接用于检索相应的单元格节点。

快捷方式扩展重做#

@jupyterlab/shortcuts-extension 包经过重做，以修复多个错误并提高类型安全性。尽管此包不公开任何编程 API，并且主题更改最小，但包的主要版本已增加到 5.0，以反映更改的范围。

扩展作者无需采取任何行动（除非您使用了 /lib 中的非公共组件），但建议在 JupyterLab 组件之上构建应用程序的作者升级到此新版本，因为它能显著改善用户体验。

JupyterLab 4.0 到 4.1#

插件管理器和扩展锁定#

在 JupyterLab 4.1 之前，没有以下机制： - 用户无法禁用/启用单个插件（而不是整个扩展） - 管理员无法完全阻止用户启用/禁用某些扩展

此版本的 JupyterLab 通过添加插件管理器实现了这两者。

如果您的安装禁用了任何插件，这些插件将在首次启动时自动锁定，以确保用户公开的功能没有变化。插件管理器本身可以使用 jupyter labextension 命令禁用和锁定，但我们建议根据需要锁定单个插件。

如果您的扩展以前包含自定义启用/禁用设置，您可能可以用指向插件管理器的说明来替换它。但是，请考虑您的扩展是否可能用于不包含插件管理器或已禁用插件管理器的分发。

`StaticNotebook` 的超类 `WindowedList` 中 CSS 类名更改#

类 .jp-WindowedPanel-window 已重命名为 .jp-WindowedPanel-viewport。
笔记本滚动容器现在是 .jp-WindowedPanel-outer 而不是 .jp-Notebook
Galata 笔记本辅助函数 getCell 和 getCellCount 已相应更新

笔记本焦点处理的变化影响命令模式快捷方式选择器#

以前，在切换到命令模式时，笔记本中的焦点会恢复到笔记本 HTML 节点，这会阻止单元格之间的 Tab 导航，尤其会影响有辅助功能需求的用户。在 JupyterLab 4.1+ 中，切换到命令模式时焦点会停留在活动单元格上；这要求所有快捷方式选择器都按如下方式调整

.jp-Notebook:focus.jp-mod-commandMode、.jp-Notebook:focus 和 [data-jp-traversable]:focus 应替换为： - JupyterLab 4.1.0+ 的 .jp-Notebook.jp-mod-commandMode :focus:not(:read-write) - JupyterLab 4.1.1+ 的 .jp-Notebook.jp-mod-commandMode:not(.jp-mod-readWrite) :focus
[data-jp-kernel-user]:focus 应替换为： - JupyterLab 4.1.0+ 的 [data-jp-kernel-user] :focus:not(:read-write) - JupyterLab 4.1.1+ 的 [data-jp-kernel-user]:not(.jp-mod-readWrite) :focus:not(:read-write)

请注意，:not(:read-write) 片段在文本字段（如单元格编辑器）获得焦点时禁用快捷方式，以避免拦截用户键入文本字段的字符。但是，如果您的快捷方式不对应任何键/印刷字符（例如，大多数带有 Ctrl 修饰符的快捷方式），如果您希望快捷方式在文本字段中也处于活动状态，您可能更喜欢删除此片段。

此外，JupyterLab 4.1.1 引入了指示符类 .jp-mod-readWrite，当活动元素接受键盘输入（由 :read-write 选择器定义）时，该类应用于笔记本节点。此指示符类是检测嵌套在开放影子 DOM（例如 Panel 框架小部件）中的 :read-write 元素所必需的。

如果您的框架使用封闭影子 DOM，或者期望在浏览器 :read-write 选择器的启发式方法未识别为可编辑的元素上进行键盘交互，您需要在外层主机元素上设置数据属性 lm-suppress-shortcuts 以禁止快捷方式。

为了防止破坏用户体验，这些更改在后台透明地进行，但会发出警告，并且扩展开发人员应在下一个主要 JupyterLab 版本发布之前在源代码中进行更改。

高放大率下 `StatusBar` 元素的可见性#

在高放大率/低分辨率下，状态栏项默认隐藏，以防止使用高放大率应用程序的用户重叠。
IStatusBar.registerStatusItem 方法的选项中添加了一个额外的 priority 属性，以允许状态栏项保持可见；其预期用途是用于小状态栏项，这些项在高放大率下特别有用，或者否则无法访问。

JupyterLab 3.x 到 4.x#

由于 JupyterLab 3.x 到 4.x 的显著类型更改，我们建议为每个主要版本的 JupyterLab 发布新主要版本的扩展。有关 Lab 3 和 Lab 4 使用不同主要版本的扩展示例，请参阅 jupyterlab-vim 和 jupyter-ai。

使用升级脚本升级扩展#

JupyterLab 4.x 提供了一个脚本来升级现有扩展以使用新的扩展系统和打包。

注意

备份您的扩展 - 最好使用像 git 这样的版本控制，在新分支上工作。

首先，请务必更新到 JupyterLab 4 并安装 copier 和一些依赖项。使用 pip

pip install -U jupyterlab[upgrade-extension]

或使用 conda

conda install -c conda-forge jupyterlab=4 "copier=9" jinja2-time

然后，在扩展的根文件夹中，运行

python -m jupyterlab.upgrade_extension .

升级脚本创建打包 JupyterLab 扩展为 Python 包所需的文件。脚本会询问您所有文件是否要覆盖它们。默认情况下，配置文件将为新版本覆盖。特别是，如果您以前使用 Python setuptools（即 setup.py 和/或 setup.cfg），您可能需要更新 pyproject.toml 文件（请参阅 PEP 示例）。

升级脚本还将 package.json 中的依赖项更新到 ^4.0.0 包。

有关新文件结构和扩展打包的更多详细信息，请查看扩展教程：扩展教程

注意

如果您的扩展受到以下 API 更改的影响，您将需要修改您的代码。

jlpm#

实用程序 jlpm 使用 Yarn 3（以前是 Yarn 1）。这将需要更新您的包配置。

创建包含以下内容的 .yarnrc.yml 文件

enableImmutableInstalls: false
nodeLinker: node-modules

添加到 .gitignore

.yarn/

运行 jlpm install 这将重置您的 yarn.lock 内容，因为其格式已更改。

注意

您可以在 Yarn 文档中找到有关将 Yarn 从版本 1 升级到版本 3 的更多信息。

如果您遇到同一包的多个版本（如 @lumino/widgets），TypeScript 可能会抱怨类型不匹配。一个可能的解决方案是使用以下命令强制包去重

jlpm dlx yarn-berry-deduplicate

API 破坏性更改#

注意

随着 JupyterLab 4.x 的发布，npm 包版本策略发生了变化，除非需要，否则不会与 Python 包一起升级主要版本，以简化扩展兼容性。

以下是 JupyterLab npm 包中遇到 API 更改并因此升级了其主要版本（遵循 semver 约定）的列表。我们特别想指出 @jupyterlab/documentsearch 和 @jupyterlab/toc API 已完全重做。

@jupyterlab/application 从 3.x 到 4.x
- 主要版本升级是为了允许 JupyterFrontEnd 中的替代 ServiceManager 实现。具体来说，这允许使用模拟管理器。这还使 JupyterLab.IOptions 更具包容性，在提供选项时不要求 shell，并允许符合 ILabShell 接口的 shell。因此，所有其他 @jupyterlab/ 包的主要版本也随之升级。有关更多详细信息，请参阅 jupyterlab/jupyterlab#11537。
- 将令牌 @jupyterlab/apputils:IConnectionLost 重命名为 @jupyterlab/application:IConnectionLost。
@jupyterlab/apputils 从 3.x 到 4.x
- 将 IToolbarWidgetRegistry.registerFactory 重命名为 IToolbarWidgetRegistry.addFactory
- ISanitizer 和 ISanitizer.IOptions 已弃用，取而代之的是 @jupyterlab/rendermime-interfaces 中的 IRenderMime.ISanitizer 和 IRenderMime.ISanitizerOptions。
- 全局 sessionContextDialogs 已删除；您应该请求令牌 ISessionContextDialogs（来自 @jupyterlab/apputils）。
@jupyterlab/attachments 从 3.x 到 4.x
从 IAttachmentsModel.IOptions 中删除了 modelDB。
@jupyterlab/buildutils 从 3.x 到 4.x
- create-theme 脚本已删除。如果您想创建一个新的主题扩展，您应该使用 TypeScript 扩展模板（选择 theme 作为 kind）代替。
- add-sibling 脚本已删除。请查看源扩展的开发工作流程。
- exitOnUuncaughtException 实用函数已重命名为 exitOnUncaughtException（修复拼写错误）。
@jupyterlab/cells 从 3.x 到 4.x
- MarkdownCell.toggleCollapsedSignal 重命名为 MarkdownCell.headingCollapsedChanged 为了支持笔记本窗口化，单元格小部件的子级（例如编辑器或输出区域）在单元格附加到笔记本时不会实例化。您可以测试 isPlaceholder() 以查看单元格是否已完全实例化，或者等待 Promise ready 得到解决。此外，inViewport 属性和 inViewportChanged 信号可用于测试单元格是否附加到 DOM。如果您在笔记本外部实例化独立单元格，您可能需要将构造函数选项 placeholder 设置为 false 以确保单元格的直接渲染。
- InputArea.defaultContentFactory 和 Cell.defaultContentFactory 已删除。如果需要，您可以从 @jupyterlab/codeeditor 请求令牌 IEditorServices。然后您可以使用 new Cell.ContentFactory({ editorFactory: token.factoryService.newInlineEditor });。
@jupyterlab/celltags 从 3.x 到 4.0 @jupyterlab/celltags 包已删除，并由 @jupyterlab/celltags-extension 中的小部件取代。此小部件现在使用 @jupyterlab/metadataform 渲染。
@jupyterlab/codeeditor 从 3.x 到 4.0
- CodeEditor.IEditor 已更改
  
  resizeToFit() 已删除
  
  addKeydownHandler() 已删除 - 您应该使用 EditorView.domEventHandlers 添加 CodeMirror 扩展，并使用
  Prec.high（以确保它不会被键盘快捷键捕获）。
  
  injectExtension() 作为实验性功能添加，用于注入 CodeMirror 扩展 - 您应该优先使用
  IEditorExtensionRegistry 注册新扩展。
- CodeEditor.IOptions 有两个新的可选属性
  
  extensions?: Extensions[] 用于在编辑器实例化时提供自定义扩展
  
  inline?: boolean 表示编辑器是否是文档（如笔记本）的子部分。
- CodeEditorWrapper.IOptions 已更改为 { factory, model, editorOptions }。
- CodeViewerWidget.IOptions 已更改为 { factory, model, editorOptions }。
@jupyterlab/codemirror 从 3.x 到 4.0
- 配置参数更改
  
  fontFamily、fontSize 和 lineHeight：分组在子字典 customStyles 中。
  
  insertSpaces：更改为 indentUnit，其值可以在 ['Tab', '1', '2', '4', '8'] 之间。
  
  lineWrap：已更改 - 现在是一个布尔值。
  
  showTrailingSpace：重命名为 highlightTrailingWhitespace
  
  coverGutterNextToScrollbar：已删除
  
  electricChars：已删除
  
  extraKeys：已删除 - 您应该使用 CodeMirror 扩展 keymap.of(KeyBinding[]) 注册新的键映射。
  
  handlePaste：已删除
  
  keymap：已删除
  
  lineSeparator：已删除 - 行分隔符标准化为 \n
  
  lineWiseCopyCut：已删除 - 这是默认行为
  
  scrollbarStyle：已删除
  
  styleSelectedText：已删除
  
  selectionPointer：已删除
  
  wordWrapColumn：已删除
- Mode 已删除。您可以改为请求令牌 IEditorLanguageHandler。它提供了类似的 API： - Mode.registerModeInfo -> IEditorLanguageHandler.addLanguage - Mode.ensure() -> IEditorLanguageHandler.getLanguage() - Mode.modeList -> IEditorLanguageHandler.getLanguages() - Mode.run() -> IEditorLanguageHandler.highlight() - Mode.findBest() -> IEditorLanguageHandler.findBest() - Mode.findByName() -> IEditorLanguageHandler.findByName() - Mode.findByMIME() -> IEditorLanguageHandler.findByMIME() - Mode.findByExtension() -> IEditorLanguageHandler.findByExtension()
- EditorSyntaxStatus 移至 @jupyterlab/fileeditor
@jupyterlab/codemirror-extension 从 3.x 到 4.0
- 已移动的命令： - codemirror:change-theme -> fileeditor:change-theme（移至 @juptyerlab/fileeditor-extension） - codemirror:change-mode -> fileeditor:change-language（移至 @juptyerlab/fileeditor-extension） - codemirror:find -> fileeditor:find（移至 @juptyerlab/fileeditor-extension） - codemirror:go-to-line -> fileeditor:go-to-line（移至 @juptyerlab/fileeditor-extension）
- 已删除的命令：codemirror:change-keymap
- 已移动的插件： - @jupyterlab/codemirror-extension:commands 已集成到 @jupyterlab/fileeditor-extension:plugin 中 - @jupyterlab/codemirror-extension:editor-syntax-status -> @jupyterlab/fileeditor-extension:editor-syntax-status - @jupyterlab/codemirror-extension:editor-syntax-status -> @jupyterlab/fileeditor-extension:editor-syntax-status
@jupyterlab/completer 从 3.x 到 4.x
主要版本已升级，以实现性能改进和更轻松的第三方集成。
- 添加自定义完成建议（项目）
  
  在 3.x 及更早版本中，添加自定义完成项需要使用旧管理器提供的 ICompletionManager 令牌的 register 方法为每个文件/单元格重新注册完成器连接器；在 4.x 中，此令牌和关联的 ICompletableAttributes 接口已删除，并添加了注册自定义完成源（完成提供者）的适当方法。要为 JupyterLab 创建完成提供者，用户需要实现 ICompletionProvider 接口，然后使用 ICompletionProviderManager 令牌注册此提供者。
  
  在 3.x 中，合并来自不同源的完成必须通过创建内部合并其他连接器结果的连接器来执行。在 4.x 中，IProviderReconciliator 用于合并来自多个提供者的完成，并且可以在构造函数中为自定义完成处理程序 (CompletionHandler) 进行自定义；在 JupyterLab 管理的完成器中自定义协调器目前尚不可能。
- 使用 Completer.IRenderer 进行渲染
  
  在 3.x 中，无法轻松交换 JupyterLab 管理的完成器的渲染器。在 4.x 中，现在将使用排名最高的完成提供者的渲染器用于所有 JupyterLab 管理的完成器。此行为未来可能会进行修订（请留下反馈）。
  
  完成器框现在对屏幕外内容使用延迟渲染，以提高顶部建议的首次绘制时间。为了在不渲染所有项目的情况下定位完成器，我们使用启发式方法搜索最宽的项目，该方法可以在自定义渲染器 (itemWidthHeuristic) 中进行调整。
  
  文档面板现在实现了一个加载指示器（进度条），可以通过可选的 createLoadingDocsIndicator 渲染器方法进行自定义。
  
  createItemNode 已删除，取而代之的是 createCompletionItemNode，后者现在是必需的。
  
  createCompletionItemNode 不再负责标签的净化，现在这是模型（参见下文）的责任。
- 模型
  
  在 3.x 中，无法轻松交换 JupyterLab 管理的完成器的模型。在 4.x 中，现在将使用排名最高的完成提供者的模型工厂用于 JupyterLab 管理的完成器。此行为未来可能会进行修订（请留下反馈）。
  
  用于更新和访问完成项的旧方法：setOptions、options 和 items 已删除，取而代之的是 completionItems 和 setCompletionItems，它们现在是 Completer.IModel 的必需成员。
  
  添加了新信号 queryChanged，必须由模型发出。
  
  模型现在负责净化标签并在 insertText 属性上保留原始标签（如果尚未定义）；此更改是为了正确处理 HTML 标签的转义。
@jupyterlab/codeeditor 从 3.x 到 4.x
- 删除 ISelectionStyle（以及因此的 defaultSelectionStyle 和 IEditor.selectionStyle）。这是为了实时协作而设想的。但在最终实现中未使用。
@jupyterlab/console 从 3.x 到 4.x
IConsoleHistory.sessionContext 的类型已更新为 ISessionContext | null，而不是 ISessionContext。这可能会破坏访问 ConsoleHistory 中的 sessionContext 的插件的编译，特别是那些启用了严格空检查的插件。
@jupyterlab/coreutils 从 3.x 到 4.x
Time 命名空间不再使用 moment 库来管理日期。相反，它切换到使用现代 Web 浏览器中现在可用的 Intl API。Time.format 函数仍然可用，但不再接受 timeFormat 参数。
@jupyterlab/debugger 从 3.x 到 4.x
- 命令 debugger:pause 命令 ID 已重命名为 debugger:pause-on-exceptions，以避免与暂停当前运行线程产生歧义。
@jupyterlab/docmanager 从 3.x 到 4.x
- renameDialog 现在接收 DocumentRegistry.Context 而不是路径。
- 接口 DocumentManager.IWidgetOpener 现在是 IDocumentWidgetOpener，由新插件 @jupyterlab/docmanager-extension:opener 提供。IDocumentWidgetOpener 接口现在还定义了一个 `opened` 信号，当小部件打开时会发出该信号。
- 从接口 DocumentManager.IOptions 中删除了属性 docProviderFactory。
@jupyterlab/docregister 从 3.x 到 4.x
- TextModelFactory.preferredLanguage(path: string) 将始终返回 ''。编辑器语言并非全局可用。如果需要，您可以通过从 @jupyterlab/codemirror 请求令牌 IEditorLanguageHandler 来恢复该功能。然后您可以使用 token.findByFileName(widget.context.path)?.name ?? ''。
@jupyterlab/docprovider 从 3.x 到 4.x
此包不再存在于 JupyterLab 中。有关实时协作的文档，请查看 RTC 的文档
@jupyterlab/docregistry 从 3.x 到 4.x
- 从接口 Context.IOptions 中删除了属性 docProviderFactory。
- 类 DocumentModel 的构造函数接收参数 DocumentModel.IOptions。
- 方法 IModelFactory.createNew 接收参数 DocumentRegistry.IModelOptions。
- 方法 TextModelFactory.createNew 接收参数 DocumentModel.IOptions。
@jupyterlab/documentsearch 从 3.x 到 4.x
- @jupyterlab/documentsearch:plugin 已重命名为 @jupyterlab/documentsearch-extension:plugin
- @jupyterlab/documentsearch:labShellWidgetListener 已重命名为 @jupyterlab/documentsearch-extension:labShellWidgetListener
这可能会影响应用程序配置（例如，如果插件被禁用）。搜索提供者 API 已完全重做。但逻辑类似，对于新类型文档，您需要向 ISearchProviderRegistry 注册一个 ISearchProviderFactory。该工厂将为文档小部件构建一个 ISearchProvider。
@jupyterlab/extensionmanager 从 3.x 到 4.x
前端 API 已大幅缩减，以从后端获取所有信息。现在建议您根据需要实现自定义 ExtensionManager 类，而不是覆盖前端插件。有关使用 PyPI.org 和 pip 的示例，请参阅 jupyterlab/extensions/pypi.py。然后，您可以通过在 Python 包中定义入口点来注册您的管理器；请参阅 pyproject.toml::project.entry-points."jupyterlab.extension_manager_v1"。
@jupyterlab/fileeditor 从 3.x 到 4.x
删除了类 FileEditorCodeWrapper，取而代之的是，您可以使用 @jupyterlab/codeeditor 中的 CodeEditorWrapper。
@jupyterlab/filebrowser 从 3.x 到 4.x
- 从接口 IFileBrowserFactory 中删除了属性 defaultBrowser。默认浏览器现在由其自身的插件提供，方法是请求令牌 IDefaultFileBrowser。
- 从 FileBrowser 类中删除了 useFuzzyFilter setter。
@jupyterlab/filebrowser-extension 从 3.x 到 4.x
移除命令 filebrowser:create-main-launcher。您可以替换为 launcher:create（行为相同）。所有启动器创建操作都移至 @jupyterlab/launcher-extension。
@jupyterlab/imageviewer-extension 从 3.x 到 4.x
从公共 API 中删除了 addCommands
@jupyterlab/mainmenu 从 3.x 到 4.x
- IMainMenu.addMenu 签名从 addMenu(menu: Menu, options?: IMainMenu.IAddOptions): void 更改为 addMenu(menu: Menu, update?: boolean, options?: IMainMenu.IAddOptions): void
- 从公共 API 中删除了 createEditMenu、createFileMenu、createKernelMenu、createViewMenu、createRunMenu、createTabsMenu、createHelpMenu。
@jupyterlab/notebook 从 3.x 到 4.x
- NotebookWidgetFactory.IOptions 不再有 sessionDialogs 选项。
- NotebookPanel._onSave 方法现在是 private。
- NotebookActions.collapseAll 方法重命名为 NotebookActions.collapseAllHeadings。
- 命令 Collapsible_Headings:Toggle_Collapse 重命名为 notebook:toggle-heading-collapse。
- 命令 Collapsible_Headings:Collapse_All 重命名为 notebook:collapse-all-headings。
- 命令 Collapsible_Headings:Expand_All 重命名为 notebook:expand-all-headings。
- 为了支持窗口化，新增了 scrollToItem(index, behavior) 方法，用于滚动到任何可能或可能不在 DOM 中的单元格。并且新增了 cellInViewportChanged 信号，用于监听单元格进入或离开视口（在窗口化模式下）。scrollToCell(cell) 现在返回一个 Promise<void>，内部调用 scrollToItem。
- fullyRendered、placeholderCellRendered 和 remainingCellToRenderCount 已删除。延迟渲染模式仍然存在。它将在空闲 CPU 时间渲染一些单元格。
- 设置 numberCellsToRenderDirectly、remainingTimeBeforeRescheduling、renderCellOnIdle、observedTopMargin 和 observedBottomMargin 已删除。取而代之的是，添加了 windowingMode（值为 *defer*、*full* 或 *none*）和 overscanCount 来管理渲染模式。
- 向接口 NotebookModel.IOptions 添加了属性 sharedModel。
- 方法 NotebookModelFactory.createNew 接收参数 NotebookModelFactory.IModelOptions。
- 默认笔记本工具栏的 restart-and-run 按钮现在指向命令 notebook:restart-run-all，而不是 runmenu:restart-and-run-all。
- StaticNotebook.defaultContentFactory 已删除。如果需要，您可以从 @jupyterlab/codeeditor 请求令牌 IEditorServices。您可以通过请求 new NotebookPanel.ContentFactory({ editorFactory: token.factoryService.newInlineEditor }); 来获取它。
- notebooktools 模块不再提供 ActiveCellTool、NotebookMetadataEditorTool 和 CellMetadataEditorTool。所有这些小部件都被 @jupyterlab/notebook-extension 中的小部件取代，并使用 @jupyterlab/metadataform 渲染。KeySelector 也已删除，因为不再使用，取而代之的是使用 @jupyterlab/metadataform 提供元数据键的选择。
@jupyterlab/rendermime 从 3.x 到 4.x
- Markdown 解析器已提取到其自己的插件 @jupyterlab/markedparser-extension:plugin 中，该插件提供了一个新的令牌 IMarkdownParser（在 @jupyterlab/rendermime 中定义）。因此，IRendererFactory.createRenderer 有一个新选项 markdownParser。
- [不中断] IRenderMime.IExtension 有一个新的可选 description: string 属性用于文档。
@jupyterlab/rendermime-interfaces 从 3.x 到 4.x 删除了 IRenderMime.IRenderer.translator? 属性；如果渲染器工厂需要，翻译器对象仍会传递给构造函数。
@jupyterlab/services 从 6.x 到 7.x
- 删除 Contents.IDrive.modelDBFactory 和 Contents.IManager.getModelDBFactory。
- 添加了 Contents.IDrive.sharedModelFactory 和 Contents.IManager.getsharedModelFactory。
@jupyterlab/shared-models 从 3.x 到 4.x
此包不再存在于 JupyterLab 中。有关共享模型的文档，请查看 @jupyter/ydoc 文档。
@jupyterlab/statusbar 从 3.x 到 4.x
- 设置 @jupyterlab/statusbar-extension:plugin . startMode 移至 @jupyterlab/application-extension:shell . startMode
- 插件 @jupyterlab/statusbar-extension:mode-switch 重命名为 @jupyterlab/application-extension:mode-switch
- 插件 @jupyterlab/statusbar-extension:kernel-status 重命名为 @jupyterlab/apputils-extension:kernel-status
- 插件 @jupyterlab/statusbar-extension:running-sessions-status 重命名为 @jupyterlab/apputils-extension:running-sessions-status
- 插件 @jupyterlab/statusbar-extension:line-col-status 重命名为 @jupyterlab/codemirror-extension:line-col-status
- HoverBox 组件已从 @jupyterlab/apputils 移至 @jupyterlab/ui-components。
- 从公共 API 中移除了 STATUSBAR_PLUGIN_ID。
@jupyterlab/terminal 从 3.x 升级到 4.x
- Xterm.js 从 4.x 升级到 5.x
- IThemeObject.selection 重命名为 selectionBackground
@jupyterlab/terminal-extension 从 3.x 升级到 4.x
从公共 API 中删除了 addCommands
@jupyterlab/toc 从 3.x 升级到 4.x
@jupyterlab/toc:plugin 重命名为 @jupyterlab/toc-extension:registry。这可能会影响应用程序配置（例如，如果插件被禁用）。命名空间 TableOfContentsRegistry 已重命名为 TableOfContents。API 已完全重做。新的目录提供者必须实现一个工厂 TableOfContents.IFactory，该工厂将为受支持的小部件创建一个模型 TableOfContents.IModel<TableOfContents.IHeading>。该模型提供一个由 text 和 level 描述的标题列表，可选地还包括 prefix、collapsed 状态和 dataset（DOM 数据属性字典）。
@jupyterlab/ui-components 从 3.x 升级到 4.x
- 在移除 Blueprint JS 依赖后，主版本号已提升。使用代理组件（如 Checkbox、Select 或 Intent）的扩展需要从 Blueprint JS 库中显式导入它们。使用 Button、Collapse 或 InputGroup 的扩展可能需要切换到 Blueprint 组件，因为 JupyterLab 中这些组件的接口与 Blueprint JS 的接口不匹配。
- 移除 Collapse React 组件。
- 表单组件注册表更改
  
  将插件 '@jupyterlab/ui-components-extension:form-component-registry' 重命名为 '@jupyterlab/ui-components-extension:form-renderer-registry'
  
  将 IFormComponentRegistry 令牌重命名为 IFormRendererRegistry，从 @jupyterlab/ui-components:ISettingEditorRegistry 到 @jupyterlab/ui-components:IFormRendererRegistry。
  
  FormRendererRegistry 注册 IFormRenderer 而不是 Field 渲染器。IFormRenderer 定义了一个 fieldRenderer（这是为了向后兼容而设置的渲染器）或一个 widgetRenderer。渲染器 ID 必须遵循约定 <ISettingRegistry.IPlugin.id>.<propertyName>。这是为了确保自定义渲染器不会用于具有相同名称但不同 schema 的属性。
@jupyterlab/translation 从 3.x 升级到 4.x。在 NullTranslator 中，将方法 locale 重命名为属性 languageCode。
@jupyterlab/vdom 和 @jupyterlab/vdom-extension 已被移除。底层 vdom Python 包无人维护。因此决定将其从核心包中删除。
jupyter.extensions.hub-extension 从 3.x 升级到 4.x
- 将 jupyter.extensions.hub-extension 重命名为 @jupyterlab/hub-extension:plugin。
- 将 jupyter.extensions.hub-extension:plugin 重命名为 @jupyterlab/hub-extension:menu。
TypeScript 5.0 更新。由于更新到 TypeScript 5.0，一些接口的定义已更改。HoverBox.IOptions 的 anchor 参数现在是 DOMRect 而不是 ClientRect。CodeEditor.ICoordinate 接口现在扩展 DOMRectReadOnly 而不是 JSONObject, ClientRect。
React 18.2.0 更新。从 React 17.0.1 更新到 18.2.0 也应传播到扩展。这是关于迁移到 React 18 的文档。

使用 Jest 进行测试#

Jest 已更新到 29.2.0（ts-jest 更新到 29.0.0）。因此，@jupyterlab/testutils 提供的 jest 配置与该版本兼容。特别是：

无人维护的报告器 jest-summary-reporter 已被新的默认 github-actions 报告器取代。
辅助函数 flakyIt 已被移除。你可以使用新的 jest.retryTimes 代替。

在 JupyterLab 4 中，我们修复了由于 testutils 包引起的循环依赖。所以它现在只是一个门面，用于从各种核心包中导出辅助函数。导出的辅助函数与以前相同，除了：

NBTestUtils.DEFAULT_CONTENT：已移除 - 你可以从 @jupyterlab/notebook/lib/testutils 导入，但我们强烈建议不要这样做，而是使用你自己的测试数据。
NBTestUtils.DEFAULT_CONTENT_45：已移除

使用 Galata 进行测试#

页面内辅助函数现在位于 JupyterLab 扩展中，以存在于公共 Webpack 共享作用域中。这个新扩展包含在 jupyterlab.galata 的 JupyterLab python 包中。它需要通过添加以下行来更新你的 Jupyter 服务器配置：

import jupyterlab
c.LabApp.extra_labextensions_path = str(Path(jupyterlab.__file__).parent / "galata")

注意

为了简化配置，我们引入了一个新的辅助函数 jupyterlab.galata.configure_jupyter_server。因此，你可以将服务器配置简化为 jupyterlab.galata.configure_jupyter_server(c)。

以下是 Javascript 包 @jupyterlab/galata 从 4.x 到 5.x 的更改：

ContentsHelper 和 galata.newContentsHelper 有新的构造函数参数，用于使用 Playwright API 请求对象：new ContentsHelper(baseURL, page?, request?) -> new ContentsHelper(request?, page?) galata.newContentsHelper(baseURL, page?, request?) -> galata.newContentsHelper(request?, page?) 你需要提供 request 或 page；它们都是 Playwright 提供的夹具。
galata.Mock.clearRunners(baseURL, runners, type) -> galata.Mock.clearRunners(request, runners, type)
页面内辅助函数现在位于 jupyterlab/galata/extension 中定义的扩展中，并存储在 @jupyterlab/galata/lib/extension 中。全局对象已重命名为 window.galata，而不是 window.galataip（它仍然存在但已弃用）。

已移除的弃用代码#

以下弃用 API 已被移除：

@jupyterlab/csvviewer：CSVDelimiter.delimiterChanged 已被移除 - 死代码。你可以直接从 CSVViewer 小部件访问分隔符。
@jupyterlab/mainmenu：IJupyterLabMenu 和 JupyterLabMenu 已被移除。你可以直接使用 IRankedMenu 和 RankedMenu 从 @jupyterlab/ui-components。
@jupyterlab/notebook：NotebookWidgetFactory 的默认工具栏现在为空，因为按钮辅助函数已弃用。
@jupyterlab/rendermime：RenderMimeRegistry.IUrlResolverOptions 不接受 session；你必须设置 path（通过 session.path 访问）。
@jupyterlab/ui-components:
- RankedMenu.menu : Menu 已被移除，因为 RankedMenu 继承自 Menu。
- LabIconStyle.IProps 不接受 kind 和 justify。你应该分别使用 stylesheet 或 elementPosition。

扩展开发变更#

dev_mode/package.json 文件中与 @jupyterlab/application-top private 包对应的 externalExtensions 字段已在 4.0 中移除。如果你曾使用此字段针对 JupyterLab 的开发版本开发源代码扩展，则应切换到联邦扩展系统（通过 --extensions-in-dev-mode 标志）或使用 --splice-source 选项。更多信息请参阅开发预构建扩展和源代码扩展的开发工作流。
@jupyterlab/builder 中的 webpack 依赖已更新到 5.72（或更新版本）。基本规则已更新为使用资产模块，而不是之前的 file-loader、raw-loader 和 url-loader。如果第三方扩展依赖于这些加载器的特定行为，这可能会产生影响。
在 JupyterLab 3.x 中，禁用预构建扩展的 CSS 仍然会在页面上加载。在 JupyterLab 4.0 中不再是这种情况。
使用 --expose-app-in-browser 标志启动 JupyterLab 时，不再暴露 window.jupyterlab。请改用 window.jupyterapp。

JupyterLab 3.5 到 3.6#

AsyncIterable 支持#

对于事件服务，我们正在使用 ES2018 中引入的 JavaScript 功能。如果你的代码使用 TypeScript 并且目标是 ES2017（如 JupyterLab 3.6），你将需要将目标更新为 ES2018，或者将 "ES2018" 添加到 TypeScript lib 选项中。

注意

JupyterLab 3.6.0 发布时更新了目标为“ES2018”。我们强烈建议更新到 3.6.1，该版本将目标恢复到“ES2017”。

Jest 配置更新#

如果您正在使用 jest 测试您的扩展，JupyterLab 3.6 中添加了一些新的 ES6 包依赖项。在使用 Jest 转换代码时需要忽略它们。您需要更新 transformIgnorePatterns 以匹配：

const esModules = [
  '@jupyterlab/',
  '@jupyter/ydoc',
  'lib0',
  'y\\-protocols',
  'y\\-websocket',
  'yjs'
].join('|');

// ...

transformIgnorePatterns: [`/node_modules/(?!${esModules}).+`]

有关更多信息，请参阅测试您的扩展。

实时协作#

在 JupyterLab v3.6 中，必须安装 Jupyter Server v2.0 才能使用实时协作。此要求是为了利用 Jupyter Server v2.0 中新的身份 API 而引入的。

另一方面，我们还更改了 JupyterLab 加载文档的方式（仅在协作模式下）。现在，提供程序不再使用内容 API，而是打开一个 WebSocket 连接到 YDocWebSocketHandler，后者在外部 jupyter server 扩展中实现。

此外，共享模型包已移至一个名为 @jupyter/ydoc 的外部包。所有依赖 @jupyterlab/shared-models 的扩展都需要更新为依赖 @jupyter/ydoc@~0.2.2；API 应该保持不变。

API 变更： 为了修复 RTC 并使其稳定。有必要更改 API 并进行一些重大更改。这些更改不应影响绝大多数扩展。它们只会影响少数专注于 RTC 的扩展。

有必要改变 JupyterLab 加载文档的范式，并替换后端中的锁定机制。它不再识别第一个打开文档的客户端，而是通过在后端实例化 YDoc 客户端来集中处理该过程。此客户端是唯一将文档内容加载到内存中并与其他所有连接的客户端共享的客户端。

涉及的包是：

@jupyterlab/docprovider:
- 接口 IDocumentProvider 现在继承自 IDisposable。已移除：acquireLock、releaseLock、setPath、destroy、requestInitialContent 和 putInitializedState。已添加：ready 和 isDisposed。
- IDocumentProviderFactory.IOptions 现在使用 T extends ISharedDocument = ISharedDocument 进行模板化。并且 ymodel 属性已重命名为 model，类型为 T（将类型从 YDocument 放宽到 ISharedDocument）。
- WebSocketProviderWithLocks 已重命名为 WebSocketProvider。它不再继承自 y-websocket 的 WebSocketProvider。
- WebSocketProvider.IOptions 有一个新的可选属性 user。
@jupyterlab/services:
- 接口 IManager 有一个新的可选属性 user，该属性实现 User.IManager。
- ServiceManager 类实现了 IManager 中的可选属性 user。

JupyterLab 3.0 到 3.1#

新的主菜单和上下文菜单定制#

JupyterLab 3.1 引入了一种将命令挂接到主菜单和上下文菜单的新方法。它允许最终用户通过设置自定义这些菜单，就像快捷方式已经可以做到一样。不再建议使用 API，除非创建动态菜单。

Jest 配置更新#

如果您正在使用 jest 测试您的扩展，JupyterLab 中添加了一些新的 ES6 包依赖项。在使用 Jest 转换代码时需要忽略它们。您需要更新 transformIgnorePatterns 以匹配：

const esModules = [
  '@jupyterlab/',
  'lib0',
  'y\\-protocols',
  'y\\-websocket',
  'yjs'
].join('|');

// ...

transformIgnorePatterns: [`/node_modules/(?!${esModules}).+`]

有关更多信息，请参阅测试您的扩展。

注意

以下是 @jupyterlab/git 扩展中更新到 JupyterLab 3.1 的拉取请求示例：jupyterlab/jupyterlab-git#files

JupyterLab 2.x 到 3.x#

以下是将扩展从 JupyterLab 2.x 迁移到 JupyterLab 3.x 的一些有用提示。

手动升级库版本#

要更新扩展以使其与 3.0 版本兼容，请更新 package.json 中 @jupyterlab 依赖项的兼容性范围。差异应类似于：

index 6f1562f..3fcdf37 100644
^^^ a/package.json
+++ b/package.json
   "dependencies": {
-    "@jupyterlab/application": "^2.0.0",
+    "@jupyterlab/application": "^3.0.0",

使用升级脚本升级库版本#

JupyterLab 3.0 提供了一个脚本来升级现有扩展，以使用新的扩展系统和打包方式。

首先，请确保更新到 JupyterLab 3.0 并安装 jupyter-packaging 和 cookiecutter。使用 pip：

pip install jupyterlab -U
pip install jupyter-packaging cookiecutter

或使用 conda

conda install -c conda-forge jupyterlab=3 jupyter-packaging cookiecutter

然后，在扩展的根文件夹中，运行

python -m jupyterlab.upgrade_extension .

升级脚本会创建将 JupyterLab 扩展打包为 Python 包所需的文件，例如 setup.py 和 pyproject.toml。

升级脚本还会将 package.json 中的依赖项更新为 ^3.0.0 包。以下是一个示例差异：

index 6f1562f..3fcdf37 100644
^^^ a/package.json
+++ b/package.json
@@ -29,9 +29,13 @@
   "scripts": {
-    "build": "tsc",
-    "build:labextension": "npm run clean:labextension && mkdirp myextension/labextension && cd myextension/labextension && npm pack ../..",
-    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "build": "jlpm run build:lib && jlpm run build:labextension:dev",
+    "build:prod": "jlpm run build:lib && jlpm run build:labextension",
+    "build:lib": "tsc",
+    "build:labextension": "jupyter labextension build .",
+    "build:labextension:dev": "jupyter labextension build --development True .",
+    "clean": "rimraf lib tsconfig.tsbuildinfo myextension/labextension",
+    "clean:all": "jlpm run clean:lib && jlpm run clean:labextension",
   "clean:labextension": "rimraf myextension/labextension",
   "eslint": "eslint . --ext .ts,.tsx --fix",
   "eslint:check": "eslint . --ext .ts,.tsx",
@@ -59,12 +63,12 @@
   ]
   },
   "dependencies": {
-    "@jupyterlab/application": "^2.0.0",
-    "@jupyterlab/apputils": "^2.0.0",
-    "@jupyterlab/observables": "^3.0.0",
+    "@jupyterlab/builder": "^3.0.0",
+    "@jupyterlab/application": "^3.0.0",
+    "@jupyterlab/apputils": "^3.0.0",
+    "@jupyterlab/observables": "^3.0.0",
   "@lumino/algorithm": "^1.2.3",
   "@lumino/commands": "^1.10.1",
   "@lumino/disposable": "^1.3.5",
@@ -99,6 +103,13 @@
-    "typescript": "~3.8.3"
+    "typescript": "~4.0.1"
   },
   "jupyterlab": {
-    "extension": "lib/plugin"
+    "extension": "lib/plugin",
+    "outputDir": "myextension/labextension/"
   }
}

在上面的差异中，我们看到还添加了额外的开发脚本，因为它们被新的扩展系统工作流使用。

差异还显示了新的 @jupyterlab/builder 作为 devDependency。@jupyterlab/builder 是将扩展构建为联邦（预构建）扩展所需的包。它隐藏了 webpack 等内部依赖项，并生成可以作为 Python 包的一部分分发的资产。

扩展开发者不需要直接与 @jupyterlab/builder 交互，而是可以使用 jupyter labextension build 命令。此命令会自动作为 build 脚本（jlpm run build）的一部分运行。

有关新文件结构和扩展打包的更多详细信息，请查看扩展教程：扩展教程

发布扩展到 PyPI 和 conda-forge#

从 JupyterLab 3.0 开始，扩展可以作为 Python 包分发。

扩展教程提供了打包扩展的说明，以便可以将其发布到 PyPI 和 conda forge：发布您的扩展。

注意

虽然发布到 PyPI 是向用户分发扩展的新推荐方式，但继续将扩展发布到 npm 仍然很有用，这样其他开发者可以在他们自己的扩展中扩展它们。

JupyterLab 1.x 到 2.x#

以下是将扩展从 JupyterLab 1.x 迁移到 JupyterLab 2.x 的一些有用提示。我们将查看两个涵盖大多数扩展作者可能正在使用的 API 的示例：

@jupyterlab/debugger 迁移拉取请求：jupyterlab/debugger#files
@jupyterlab/shortcutui 迁移拉取请求：jupyterlab/jupyterlab-shortcutui#files

升级库版本#

JupyterLab 1.x 使用的 @phosphor/* 库已重命名为 @lumino/*。更新 package.json 很简单。最简单的方法是查看 JupyterLab 核心包代码库并简单地采用其中使用的相关库的版本。

Updating the debugger extension's libraries in package.json — 更新 `package.json` 中调试器扩展的库#

Updating the shortcuts UI extension's libraries in package.json — 更新 `package.json` 中快捷方式 UI 扩展的库#

提示

在这些示例中，请注意我们使用的是许多库的 2.0.0-beta.x 版本。这是为了在最终版本发布之前，针对 JupyterLab 2.0 测试版测试扩展。对于最终版本，您的 package.json 应该依赖这些包的 ^2.0.0 版本。

从 @phosphor 迁移到 @lumino ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-

JupyterLab 使用的基础包现在都以 NPM 命名空间 @lumino 开头，而不是 @phosphor。这些包的 API 没有改变。@phosphor 命名空间的导入需要更新为新的 @lumino 命名空间包：

从 `@phosphor/...` 更新到 `@lumino/...`#
`@phosphor/application`	`@lumino/application`
`@phosphor/collections`	`@lumino/collections`
`@phosphor/commands`	`@lumino/commands`
`@phosphor/coreutils`	`@lumino/coreutils`
`@phosphor/datagrid`	`@lumino/datagrid`
`@phosphor/datastore`	`@lumino/datastore`
`@phosphor/default-theme`	`@lumino/default-theme`
`@phosphor/disposable`	`@lumino/disposable`
`@phosphor/domutils`	`@lumino/domutils`
`@phosphor/dragdrop`	`@lumino/dragdrop`
`@phosphor/keyboard`	`@lumino/keyboard`
`@phosphor/messaging`	`@lumino/messaging`
`@phosphor/properties`	`@lumino/properties`
`@phosphor/signaling`	`@lumino/signaling`
`@phosphor/virtualdom`	`@lumino/virtualdom`
`@phosphor/widgets`	`@lumino/widgets`

警告

p- 前缀的 CSS 类、data-p- 属性和 p- DOM 事件已弃用。它们将继续工作直到 Lumino 的下一个主要版本。

.p- CSS 类（例如 .p-Widget）应更新为 .lm-，例如 .lm-Widget。
data-p- 属性（例如 data-p-dragscroll）应更新为 data-lm-，例如 data-lm-dragscroll。
p- DOM 事件（例如 p-dragenter）应更新为 lm-，例如 lm-dragenter。

更新以前的 @jupyterlab/coreutils 导入 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-

JupyterLab 2.0 引入了几个新包，其中包含已从 @jupyterlab/coreutils 移出到其各自包中的类和令牌。这些导出已被移动。

提示

更新这些库时，删除 node_modules 和 yarn.lock 可能会有所帮助。

导出	包
`DataConnector`	`@jupyterlab/statedb`
`Debouncer`	`@lumino/polling`
`DefaultSchemaValidator`	`@jupyterlab/settingregistry`
`IDataConnector`	`@jupyterlab/statedb`
`IObjectPool`	`@jupyterlab/statedb`
`IPoll`	`@lumino/polling`
`IRateLimiter`	`@lumino/polling`
`IRestorable`	`@jupyterlab/statedb`
`IRestorer`	`@jupyterlab/statedb`
`ISchemaValidator`	`@jupyterlab/settingregistry`
`ISettingRegistry`	`@jupyterlab/settingregistry`
`IStateDB`	`@jupyterlab/statedb`
`nbformat`	`@jupyterlab/nbformat`
`Poll`	`@lumino/polling`
`RateLimiter`	`@lumino/polling`
`RestorablePool`	`@jupyterlab/statedb`
`SettingRegistry`	`@jupyterlab/settingregistry`
`Settings`	`@jupyterlab/settingregistry`
`StateDB`	`@jupyterlab/statedb`
`Throttler`	`@lumino/polling`

使用 `Session` 和 `SessionContext` 管理内核会话#

注意

有关 @jupyterlab/services 的完整 API 文档和使用示例，请查阅存储库。

ConsolePanel 和 NotebookPanel 现在公开了一个 sessionContext: ISessionContext 属性，它提供了一种与内核会话交互的统一方式。

任何匹配 interface IDocumentWidget 的小部件都具有 context: DocumentRegistry.IContext 属性，该属性又包含 sessionContext: ISessionContext 属性。

例如，考虑 @jupyterlab/debugger 扩展的 DebuggerService 如何更新其 isAvailable() 方法。

Updating the isAvailable method of the debugger service — 来自将调试器扩展迁移到 JupyterLab 2.0 的 PR#

注意

在可以使用内核连接 kernel 之前，不再需要 await kernel.ready。内核消息将在内核连接上线时按需缓冲，因此您应该能够立即使用内核连接。如果您想检索内核信息（或者由于其他原因，您想等待至少一条消息从新的内核连接返回），您可以执行 await kernel.info。

使用新的图标系统和 `LabIcon`#

注意

有关基于 @jupyterlab/ui-components 中的 LabIcon 的新图标支持的完整 API 文档和使用示例，请查阅存储库。

扩展迁移指南#

JupyterLab 4.4 到 4.5#

文件浏览器更新#

API 更新#

extra_labextensions_path 排序#

JupyterLab 4.3 到 4.4#

图标#

TypeScript 更新#

GroupItem 中条件渲染的支持#

API 更新#

插件#

JupyterLab 4.2 到 4.3#

CSS 样式#

使用 Galata 进行测试#

共享模型#

JupyterLab 4.1 到 4.2#

API 更新#

快捷方式扩展重做#

JupyterLab 4.0 到 4.1#

插件管理器和扩展锁定#

Toolbar 和 ToolbarButtonComponent 使用 UI 工具包#

StaticNotebook 的超类 WindowedList 中 CSS 类名更改#

笔记本焦点处理的变化影响命令模式快捷方式选择器#

高放大率下 StatusBar 元素的可见性#

JupyterLab 3.x 到 4.x#

使用升级脚本升级扩展#

jlpm#

API 破坏性更改#

使用 Jest 进行测试#

使用 Galata 进行测试#

已移除的弃用代码#

扩展开发变更#

JupyterLab 3.5 到 3.6#

AsyncIterable 支持#

Jest 配置更新#

实时协作#

JupyterLab 3.0 到 3.1#

新的主菜单和上下文菜单定制#

Jest 配置更新#

JupyterLab 2.x 到 3.x#

手动升级库版本#

使用升级脚本升级库版本#

发布扩展到 PyPI 和 conda-forge#

JupyterLab 1.x 到 2.x#

升级库版本#

使用 Session 和 SessionContext 管理内核会话#

使用新的图标系统和 LabIcon#

此页面

`extra_labextensions_path` 排序#

`StaticNotebook` 的超类 `WindowedList` 中 CSS 类名更改#

高放大率下 `StatusBar` 元素的可见性#

使用 `Session` 和 `SessionContext` 管理内核会话#

使用新的图标系统和 `LabIcon`#