扩展迁移指南#
JupyterLab 4.1 到 4.2#
API 更新#
The
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 类型渲染器。单元格工具栏节点已从单元格节点移动到单元格输入节点。因此，单元格工具栏的父节点已更改，不能再直接用于检索相应的单元格节点。
快捷键扩展重做#
The @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-NotebookGalata 笔记本助手 getCell 和 getCellCount 已相应更新
笔记本焦点处理的更改影响命令模式快捷键选择器#
以前，当切换到命令模式时，笔记本中的焦点会恢复到笔记本 HTML 节点，这会阻止在单元格之间进行 Tab 导航，尤其会影响有可访问性需求的用户。在 JupyterLab 4.1+ 中，焦点在切换到命令模式时会保留在活动单元格上；这要求所有快捷键选择器按如下方式调整
.jp-Notebook:focus.jp-mod-commandMode、.jp-Notebook:focus和[data-jp-traversable]:focus应该被替换为： -.jp-Notebook.jp-mod-commandMode :focus:not(:read-write)用于 JupyterLab 4.1.0+ -.jp-Notebook.jp-mod-commandMode:not(.jp-mod-readWrite) :focus用于 JupyterLab 4.1.1+[data-jp-kernel-user]:focus应该被替换为： -[data-jp-kernel-user] :focus:not(:read-write)用于 JupyterLab 4.1.0+ -[data-jp-kernel-user]:not(.jp-mod-readWrite) :focus:not(:read-write)用于 JupyterLab 4.1.1+
请注意，:not(:read-write) 片段在文本字段（如单元格编辑器）获得焦点时禁用快捷键，以避免拦截用户输入文本字段的字符，但是，如果您的快捷键不对应于任何键/排版字符（例如大多数使用 Ctrl 修饰符的快捷键），您可能更愿意删除此片段，如果您希望快捷键在文本字段中处于活动状态。
此外，JupyterLab 4.1.1 引入了指示器类 .jp-mod-readWrite，该类在活动元素接受键盘输入时应用于笔记本节点，如 :read-write 选择器定义。此指示器类是检测 :read-write 元素所必需的，这些元素嵌套在打开的 shadow DOM 中（例如 Panel 框架小部件）。
如果您的框架使用关闭的 shadow DOM，或者期望对浏览器启发式识别为可编辑的 :read-write 选择器以外的元素进行键盘交互，则需要在外部主机元素上设置数据属性 lm-suppress-shortcuts 来抑制快捷键。
为了防止破坏用户体验，这些更改在后台透明地进行，但会发出警告，扩展开发人员应在下一个主要 JupyterLab 版本发布之前在源代码中进行更改。
高放大倍率下 StatusBar 元素的可见性#
在高放大倍率/低分辨率下，状态栏项目现在默认隐藏，以防止那些在高放大倍率下使用应用程序的用户出现重叠。
已将一个额外的
priority属性添加到IStatusBar.registerStatusItem方法的选项中，以允许状态栏项目保持可见；预期用途是用于那些在高缩放时特别有用或否则无法访问的小状态栏项目。
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 文档 中找到有关从版本 1 升级到版本 3 的更多信息。
如果您遇到同一包的多个版本（例如 @lumino/widgets），TypeScript 可能会抱怨类型不匹配。一个可能的解决方案是使用以下方法强制包去重
jlpm dlx yarn-berry-deduplicate
API 更改#
注意
在 JupyterLab 4.x 中，npm 包版本策略已更改为，除非需要简化扩展兼容性，否则不会随着 Python 包一起提升主版本。
以下是遇到 API 更改并因此提升了主版本（遵循 semver 约定）的 JupyterLab npm 包列表。我们想特别指出 @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.addFactoryISanitizer和ISanitizer.IOptions已被弃用，取而代之的是IRenderMime.ISanitizer和IRenderMime.ISanitizerOptions，位于@jupyterlab/rendermime-interfaces中。全局
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.xMarkdownCell.toggleCollapsedSignal重命名为MarkdownCell.headingCollapsedChanged为了支持笔记本窗口化，当单元格附加到笔记本时，单元格小部件子项（例如编辑器或输出区域）不会被实例化。您可以测试isPlaceholder()来查看单元格是否已完全实例化，或者等待 promiseready被解析。此外，还提供了一个属性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.0CodeEditor.IEditor已更改resizeToFit()已移除addKeydownHandler()已移除 - 您应该添加一个 CodeMirror 扩展EditorView.domEventHandlers，其中包含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：重命名为highlightTrailingWhitespacecoverGutterNextToScrollbar：已移除electricChars: 已移除extraKeys: 已移除 - 您应该使用 CodeMirror 扩展keymap.of(KeyBinding[])注册新的键映射handlePaste: 已移除keymap: 已移除lineSeparator: 已移除 - 行分隔符已标准化为\nlineWiseCopyCut: 已移除 - 这是默认行为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 及更早版本中，添加自定义完成项目需要使用
register方法重新注册每个文件/单元格的完成器连接器，该方法由ICompletionManager令牌提供的旧管理器提供；在 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已被删除，取而代之的是现在必需的Completer.IModel成员completionItems和setCompletionItems。添加了新的信号
queryChanged，模型必须发出此信号。模型现在负责清理标签，并在
insertText属性上保留原始标签（如果尚未定义）；此更改是正确处理 HTML 标签转义所必需的。
@jupyterlab/codeeditor从 3.x 到 4.x删除
ISelectionStyle（因此删除defaultSelectionStyle和IEditor.selectionStyle）。这最初是为了实时协作而设想的。但这在最终实现中没有使用。
@jupyterlab/console从 3.x 到 4.xIConsoleHistory.sessionContext的类型已更新为ISessionContext | null，而不是ISessionContext。这可能会破坏访问ConsoleHistory中的sessionContext的插件的编译，特别是那些启用了严格空检查的插件。
@jupyterlab/coreutils从 3.x 到 4.xTime命名空间不再使用moment库来管理日期。而是改用现在在现代 Web 浏览器中可用的IntlAPI。Time.format函数仍然可用，但不再接受timeFormat参数。
@jupyterlab/debugger从 3.x 到 4.x命令
debugger:pause命令 ID 已重命名为debugger:pause-on-exceptions，以避免与暂停当前运行线程的歧义。
@jupyterlab/docmanager从 3.x 到 4.xrenameDialog现在接收DocumentRegistry.Context而不是路径。接口
DocumentManager.IWidgetOpener现在是IDocumentWidgetOpener，由一个新的插件@jupyterlab/docmanager-extension:opener提供。IDocumentWidgetOpener接口现在还定义了一个`opened`信号，当打开小部件时发出。从接口
DocumentManager.IOptions中删除了属性docProviderFactory。
@jupyterlab/docregister从 3.x 到 4.xTextModelFactory.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设置器。
@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.xIMainMenu.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.xNotebookWidgetFactory.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.xMarkdown 解析器已被提取到它自己的插件
@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-statusHoverBox组件已从@jupyterlab/apputils移至@jupyterlab/ui-components。从公共 API 中移除
STATUSBAR_PLUGIN_ID。
@jupyterlab/terminal从 3.x 到 4.xXterm.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 的接口不匹配。删除
CollapseReact 组件。- 表单组件注册表更改
将插件
'@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>。这是为了确保自定义渲染器不会用于具有相同名称但不同模式的属性。
@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 的更新，一些接口的定义发生了改变。
anchor参数HoverBox.IOptions现在是DOMRect而不是ClientRect。CodeEditor.ICoordinate接口现在扩展了DOMRectReadOnly而不是JSONObject, ClientRect。React 18.2.0 更新 React 18.2.0（从 17.0.1）的更新也应该传播到扩展。 以下是关于 迁移到 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 Python 包的 jupyterlab.galata 中。 它需要通过添加以下行来更新你的 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。
扩展开发变更#
在
4.0中，与@jupyterlab/application-topprivate包对应的dev_mode/package.json文件中的externalExtensions字段现已移除。如果您使用此字段针对 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#
异步可迭代支持#
对于事件服务，我们使用的是 ES2018 中引入的 JavaScript 功能。如果您的代码使用的是 ES2017 目标的 TypeScript（如 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，而是打开到 YDocWebSocketHandler 的 WebSocket 连接，该连接在外部 jupyter 服务器扩展 中实现。
此外，共享模型的包已移至名为 @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#
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 核心包代码库 中查找，并简单地采用那里使用的相关库的版本。
在 package.json 中更新调试器扩展的库#
在 package.json 中更新快捷方式 UI 扩展的库#
提示
在这些示例中，请注意我们使用的是许多库的 2.0.0-beta.x 版本。这是为了在最终版本发布之前，针对 JupyterLab 2.0 beta 版本测试扩展。对于最终版本，您的 package.json 应该依赖于这些包的 ^2.0.0 版本。
从 @phosphor 迁移到 @lumino ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-
JupyterLab 使用的基础包现在都以 NPM 命名空间 @lumino 为前缀，而不是 @phosphor。这些包的 API 没有改变。需要将 @phosphor 命名空间的导入更新为新的 @lumino 命名空间的包。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
警告
p- 前缀的 CSS 类、data-p- 属性和 p- DOM 事件已弃用。它们将继续工作，直到 Lumino 的下一个主要版本发布。
.p-CSS 类（如.p-Widget）应更新为.lm-，例如.lm-Widgetdata-p-属性（如data-p-dragscroll）应更新为data-lm-，例如data-lm-dragscrollp-DOM 事件（如p-dragenter）应更新为lm-，例如lm-dragenter
更新以前的 @jupyterlab/coreutils 导入 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-
JupyterLab 2.0 引入了几个新的包，其中包含已从 @jupyterlab/coreutils 移动到其自身包中的类和令牌。这些导出已被移动。
提示
在更新这些库时，删除 node_modules 和 yarn.lock 可能会有所帮助。
导出 |
包 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
使用 Session 和 SessionContext 管理内核会话#
注意
有关如何使用 @jupyterlab/services 的完整 API 文档和示例，请参阅存储库。
ConsolePanel 和 NotebookPanel 现在公开了一个 sessionContext: ISessionContext 属性，允许以统一的方式与内核会话进行交互。
任何与 interface IDocumentWidget 匹配的小部件都具有一个 context: DocumentRegistry.IContext 属性，其中包含一个 sessionContext: ISessionContext 属性。
例如，考虑 @jupyterlab/debugger 扩展的 DebuggerService 如何更新其 isAvailable() 方法。
注意
await kernel.ready 在内核连接 kernel 可用之前不再需要。内核消息将在内核连接上线时根据需要进行缓冲，因此您应该能够立即使用内核连接。如果您想检索内核信息（或者出于其他原因，您想等到至少有一条消息从新的内核连接返回），您可以执行 await kernel.info。
使用新的图标系统和 LabIcon#
注意
有关完整 API 文档和如何使用基于 LabIcon 的新图标支持的示例，请参阅 @jupyterlab/ui-components，查看仓库。