JupyterLab 扩展多应用兼容指南：让同一扩展同时运行于 JupyterLab 与 Notebook 7

JupyterLab 扩展多应用兼容指南让同一扩展同时运行于 JupyterLab 与 Notebook 7【免费下载链接】jupyterlabJupyterLab computational environment.项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlabJupyter Notebook 7 的前端由 JupyterLab 的组件构建而成二者共享同一套 Lumino 组件与 JupyterLab API因此一个扩展可以在 JupyterLab、Notebook 7 乃至任何基于 JupyterLab 组件构建的前端中运行而只需很少甚至不需要修改。本文以官方文档《Targeting Multiple Applications》为骨架结合本仓库JupyterLab 源码中的插件系统实现系统讲解多应用兼容的原理、策略与两种核心编码模式可选特性检测与必需特性切换帮助你写出一次编写、多端运行的扩展。背景为什么 Notebook 7 与 JupyterLab 共享扩展生态Jupyter Notebook 7 是使用 JupyterLab 组件重新构建的两个应用使用相同的构建块因此扩展可以在两者或任何用 JupyterLab 组件构建的前端上工作具体是否需要修改、修改多少取决于扩展的设计方式。本指南将先介绍兼容性特性概览再提供覆盖相关主题的教程与参考代码。如果你还不了解如何编写扩展可先阅读扩展教程与扩展开发文档。扩展通常从模板项目起步模板的下载与配置方式同样见扩展教程模板就绪后即可开始添加组件与功能。兼容性如何工作共享的构建块与插件机制一个 JupyterLab以及 Notebook 7扩展由一系列打包的插件组成这些插件通常使用界面工具包 Lumino等来构建扩展的外观与行为。Lumino 与 JupyterLab API 均以 TypeScript 编写。这正是基本兼容特性的来源两个应用使用相同的构建块和方法。例如JupyterLab 与 Notebook 7 都接受 Lumino widget 作为界面组件两个应用都允许你通过指定一个区域area把 widget 添加到界面中两个应用的扩展都使用相同的JupyterFrontEndPlugin类型。源码证据JupyterFrontEndPlugin与JupyterFrontEnd在本仓库中JupyterFrontEndPlugin类型定义于 packages/application/src/frontend.tsexport type JupyterFrontEndPlugin T, U extends JupyterFrontEnd.IShell JupyterFrontEnd.IShell, V extends string desktop | mobile IPluginJupyterFrontEndU, V, T;它本质上是 LuminoApplication中IPlugin类型的别名因此任何遵循此类型的插件都能被基于 JupyterFrontEnd 的应用加载。JupyterFrontEnd抽象类继承自 Lumino 的Application见 packages/application/src/frontend.ts这就是两个应用同构的根基。如何实现兼容性总体策略有些简单场景下兼容性不需要额外工作即可达成但对于复杂场景——扩展使用了某个应用独有、其他应用没有的特性——你就需要决定如何在其他应用中处理这些特性。技术层面的兼容方案本质上提供两类手段在某些应用中禁用特定功能检测某个应用或特性是否存在然后相应调整行为。此外还有一些设计模式能让扩展更容易实现兼容。以下是几条通用建议尽量使用公共特性这些特性无需额外工作即可获得兼容性避免不经检查就使用应用专属特性如 JupyterLab 状态栏应在扩展加载时或运行期间先检查其可用性下文详述尽量将应用专属特性与两个应用都支持的公共特性分离对依赖应用专属能力的功能决定取舍可以使用下文列出的技术在其他应用中禁用或修改这些功能。只用公共特性零成本兼容如果你的扩展只使用 JupyterLab 与 Notebook 7 都具备的特性安装后即可在两个应用中无缝工作。例如一个向界面顶部栏添加独立文本 widget 的扩展完全不需要做任何兼容性工作——两个应用都有可容纳该 widget 的顶部区域安装并启动后 widget 在两个应用中都会显示。需要特别注意的是使用非公共特性如 JupyterLab 状态栏——JupyterLab 有而 Notebook 7 没有会破坏那些不提供该特性的应用中的兼容性除非采取下文介绍的特殊步骤。用插件元数据驱动兼容requires与optionalJupyterLab 的扩展系统设计为插件之间可以相互依赖并复用特性。其关键机制是Provider-Consumer提供者-消费者模式一种依赖注入模式详见扩展开发文档这正是本文兼容方案的基础。每个插件通过requires和optional属性请求它需要的特性这些特性由已加载进 JupyterLab 的其他插件提供。当插件请求特性时系统会在特性可用时把它们传给插件的activate函数。利用这两个属性即可构建兼容扩展requires列表将某个特性放入requiresJupyterLab 只在该特性可用时加载你的插件optional列表将某个特性放入optionalJupyterLab 会传入对应的对象若可用或null若不可用。因此这些能力构成了扩展兼容性的骨干。你可以用它们在扩展中做检查使其在 JupyterLab、Jupyter Notebook 7及其他应用中都能工作。JupyterLab 自身通过内置插件提供了大量特性即 Provider详见公共扩展点文档。构建扩展时应当尽量使用这些扩展点此时你充当了 Provider-Consumer 模式中的Consumer角色。源码证据optional与requires在 JupyterLab 内置插件中的使用JupyterLab 自己的内置插件也遵循同一套规则。例如在 packages/application/src/lab.ts 中应用对插件的元数据结构id、description、autoStart、requires、optional进行统一处理在 packages/application/src/mimerenderers.ts 中mime 渲染器插件把ILayoutRestorer声明为optional把IRenderMimeRegistry与ITranslator声明为requirespackages/application/src/mimerenderers.ts——这与你在自己的扩展中写法的完全一致。模式一测试可选特性Optional Features把应用专属特性标记为可选并在使用前检查其是否可用是达成兼容的一种技巧。下面看来自 extension-examples 仓库的 shout-button-message 示例扩展的片段const plugin: JupyterFrontEndPluginvoid { id: jupyterlab-examples/shout-button:plugin, description: An extension that adds a button and message to the right toolbar, with optional status bar widget in JupyterLab., autoStart: true, // The IStatusBar is marked optional here. If its available, it will // be provided to the plugin as an argument to the activate function // (shown below), and if not it will be null. optional: [IStatusBar], // Make sure to list any requires and optional features as arguments // to your activate function (activate is always passed an Application, // then required arguments, then optional arguments) activate: (app: JupyterFrontEnd, statusBar: IStatusBar | null) { // ... Extension code ... } };该插件把IStatusBar标记为可选并在activate函数中为其添加参数扩展加载时由 JupyterLab 调用。如果IStatusBar不可用——例如在 Jupyter Notebook 7 中加载——activate的第二个参数就是null。扩展始终创建公共的主 widget但在需要使用状态栏时先检查IStatusBar是否可用只有可用时才创建状态栏条目。这使得扩展在 JupyterLab 和 Jupyter Notebook 7 中都能成功运行// Create a ShoutWidget and add it to the interface in the right sidebar const shoutWidget: ShoutWidget new ShoutWidget(); shoutWidget.id JupyterShoutWidget; // Widgets need an id app.shell.add(shoutWidget, right); // Check if the status bar is available, and if so, make // a status bar widget to hold some information if (statusBar) { const statusBarWidget new ShoutStatusBarSummary(); statusBar.registerStatusItem(shoutStatusBarSummary, { item: statusBarWidget }); // Connect to the messageShouted to be notified when a new message // is published and react to it by updating the status bar widget. shoutWidget.messageShouted.connect((widget: ShoutWidget, time: Date) { statusBarWidget.setSummary( Last Shout: widget.lastShoutTime?.toString() ?? (None) ); }); }注意activate的参数顺序是固定的先Application再requires声明的参数最后optional声明的参数。源码证据IStatusBar与registerStatusItem的实现IStatusBar是 JupyterLab 官方提供的 token定义于 packages/statusbar/src/tokens.tsexport const IStatusBar new TokenIStatusBar( jupyterlab/statusbar:IStatusBar, A service for the status bar on the application. Use this if you want to add new status bar items. );其接口只有一个方法registerStatusItem(id, statusItem)见 packages/statusbar/src/tokens.ts而 packages/statusbar/src/statusbar.ts 中的StatusBar类实现了该方法返回一个可dispose的IDisposable以移除条目。状态栏条目的配置项IStatusBar.IItem支持alignright | left | middle、rank排序rank 越高越靠近中间、priority缩放优先级、isActive与activeStateChanged等字段见 packages/statusbar/src/tokens.ts。了解这些字段有助于你在使用状态栏时写出更精细的配置。模式二使用必需特性切换行为Required Features另一种模式是从扩展中导出一个插件列表每个插件使用不同的requires特性根据扩展当前运行的应用选择不同行为。下面来自 extension-examples 仓库的 clap-button-message 示例扩展它在 JupyterLab 的顶部区域添加一个clap按钮在 Jupyter Notebook 7 的右侧栏添加/** * Data for the jupyterlab-examples/clap-button JupyterLab plugin. */ const pluginJupyterLab: JupyterFrontEndPluginvoid { id: jupyterlab-examples/clap-button:pluginLab, description: Adds a clap button to the top area JupyterLab, autoStart: true, requires: [ILabShell], activate: (app: JupyterFrontEnd, labShell: ILabShell) { console.log( JupyterLab extension jupyterlab-examples/clap-button is activated! ); // Create a ClapWidget and add it to the interface in the top area const clapWidget new ClapWidget(); clapWidget.id JupyterLabClapWidgetLab; app.shell.add(clapWidget, top); } }; /** * Data for the jupyterlab-examples/clap-button Jupyter Notebook plugin. */ const pluginJupyterNotebook: JupyterFrontEndPluginvoid { id: jupyterlab-examples/clap-button:pluginNotebook, description: Adds a clap button to the right sidebar of Jupyter Notebook 7, autoStart: true, requires: [INotebookShell], activate: (app: JupyterFrontEnd, notebookShell: INotebookShell) { console.log( Jupyter Notebook extension jupyterlab-examples/clap-button is activated! ); // Create a ClapWidget and add it to the interface in the right area const clapWidget new ClapWidget(); clapWidget.id JupyterNotebookClapWidgetNotebook; app.shell.add(clapWidget, right); } }; /** * Gather all plugins defined by this extension */ const plugins: JupyterFrontEndPluginvoid[] [ pluginJupyterLab, pluginJupyterNotebook ]; export default plugins;如上所示扩展导出一个插件列表每个插件用不同的requires特性在应用之间切换行为本例中是切换不同的布局区域。第一个插件requiresILabShellJupyterLab 提供第二个插件requiresINotebookShellJupyter Notebook 7 提供。源码证据ILabShell与INotebookShelltokenILabShell是本仓库jupyterlab/application包提供的官方 token定义于 packages/application/src/shell.tsexport const ILabShell new TokenILabShell( jupyterlab/application:ILabShell, A service for interacting with the JupyterLab shell. The top-level application object also has a reference to the shell, but it has a restricted interface in order to be agnostic to different shell implementations on the application. Use this to get more detailed information about currently active widgets and layout state. );从 token 的描述可以看出设计意图顶层的application对象虽然也有 shell 引用但它刻意使用受限的接口以对不同 shell 实现保持中立——这正是多应用兼容的设计基础。ILabShell.Area类型见 packages/application/src/shell.ts定义了 widget 可放置的区域main | header | top | menu | left | right | bottom | down这也是app.shell.add(widget, top)中第二个参数的合法取值集合。INotebookShell则由 Jupyter Notebook 7 前端提供作为 Notebook 特有的 shell token 存在。该模式的适用边界在插件加载时测试 shell 的方式并不是编写兼容扩展的首选方法因为粒度较粗只能做非常宽泛的行为切换通用性较差shell 通常特定于某个应用但它可以用来制作专门针对某个应用的特性。一般情况下应优先采用测试可选特性模式并瞄准上文提到的公共扩展点。小结两种模式的取舍维度测试可选特性Optional必需特性切换Requires机制optional传入 token 或null运行时判断多个插件各自requires不同应用专属 shell粒度细可按功能点逐个开关粗只能在插件级别整体切换通用性高适用于任意差异特性低依赖特定应用的 shell典型场景状态栏等有则用、无则跳过的能力为某个应用定制专属功能推荐度首选仅在需要针对单一应用做专有功能时使用无论采用哪种模式都建议将应用专属代码与公共代码分离并优先使用 公共扩展点文档 中列出的 JupyterLab 官方扩展点。进一步阅读想深入了解 JupyterLab 插件系统与 Provider-Consumer 模式依赖注入请阅读扩展开发文档扩展入门请阅读扩展教程JupyterLab 各包提供的公共扩展点清单见公共扩展点文档JupyterLab API 的类型参考见开发者 API 文档若正在从旧版 JupyterLab 迁移扩展可参考扩展迁移指南。【免费下载链接】jupyterlabJupyterLab computational environment.项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考