JupyterLab插件游乐场

一个JupyterLab扩展，可以在JupyterLab内部编写和加载简单的JupyterLab插件。

安装

此扩展需要JupyterLab 3。使用pip安装此扩展

pip install jupyterlab-plugin-playground

如何使用插件游乐场

此扩展提供了一个新的命令，将当前文件加载为扩展，可在文本编辑器中使用。

例如，通过创建一个新的文本文件并粘贴以下小的JupyterLab插件到其中来打开文本编辑器。此插件将在命令面板中创建一个简单的命令我的超级酷切换，可以打开和关闭。

import { ICommandPalette } from '@jupyterlab/apputils';

const plugin = {
  id: 'my-super-cool-toggle:plugin',
  autoStart: true, // Activate this plugin immediately
  requires: [ICommandPalette],
  activate: function (app, palette) {
    let commandID = 'my-super-cool-toggle:toggle';
    let toggle = true; // The current toggle state
    app.commands.addCommand(commandID, {
      label: 'My Super Cool Toggle',
      isToggled: function () {
        return toggle;
      },
      execute: function () {
        // Toggle the state
        toggle = !toggle;
      }
    });

    palette.addItem({
      command: commandID,
      // Sort to the top for convenience
      category: 'AAA'
    });
  }
};

export default plugin;

在文本编辑器中，通过调用命令面板并执行 将当前文件加载为扩展 来在 JupyterLab 中加载此插件。再次调用命令面板，您将看到一个新的命令“我的超级酷切换”。执行此新命令将切换命令旁边的复选框。

作为另一个更高级的例子，我们使用 RequireJS 从云端加载 bqplot Jupyter 小部件库。这假设您已安装了 ipywidgets JupyterLab 扩展。

// IJupyterWidgetRegistry token is provided with Plugin Playground
import { IJupyterWidgetRegistry } from '@jupyter-widgets/base';
// Use RequireJS to load the AMD module. '@*' selects the latest version
// and `/dist/index.js` loads the corresponding module containing bqplot
// from the CDN configured in Settings (`requirejsCDN`).
import bqplot from "bqplot@*/dist/index";

const plugin = {
  id: 'mydynamicwidget',
  autoStart: true,
  requires: [IJupyterWidgetRegistry],
  activate: function(app, widgets: IJupyterWidgetRegistry) {
    widgets.registerWidget({
        name: 'bqplot',
        version: bqplot.version,
        exports: bqplot
    });
  }
}
export default plugin;

与在 JupyterLab 扩展中编写插件相比，在插件游乐场中编写插件有一些不同之处。

• 游乐场更易于理解：您可以使用类似于 JavaScript 的代码，而不是完全类型的 TypeScript，它仍然可以编译。
• 您只能加载具有给定 ID 的插件一次，但先前版本不会被卸载。如果您对插件进行了更改，请保存它，并刷新 JupyterLab 页面以重新加载。
• 要从外部包加载代码，使用 RequireJS（它隐藏在 ES6 兼容的导入语法后面），这意味着需要略微修改导入语句，以指向包中适当的版本或文件。
  • 除了 JupyterLab 和 Lumino 包之外，只能导入 AMD 模块；ES6 模块以及为 Webpack/Node 编译的模块在当前版本中不会工作，尝试加载此类模块将导致 Uncaught SyntaxError: Unexpected token 'export' 错误。
• 虽然游乐场会尝试导入具有 .ts 后缀的相对文件、作为字符串的 SVG 以及加载 plugin.json 架构，但这些是用于快速原型设计的实验性功能，具体细节可能会更改；其他资源，如 CSS 样式，尚不支持（但计划支持）。

从 0.3.0 版本迁移

版本 0.3.0 仅支持基于对象的插件和基于 require.js 的导入。虽然定义插件的基于对象的语法仍然得到支持，但现在使用 require 全局引用已被弃用。

未来的版本将删除 require 对象，以防止 require.js 的 require 和本地 require 语法之间的混淆；请使用具有相同签名的别名函数 requirejs 或迁移到 ES6 语法插件。ES6 语法基于的插件中不可用 Require.js。

要迁移到 ES6 兼容的语法

• 将插件对象分配给变量，例如 const plugin = { /* 不更改的插件代码 */ };，
• 添加 export default plugin; 行，
• 将 require() 调用转换为 ES6 默认导入。

高级设置

插件游乐场的高级设置允许您配置插件以在 JupyterLab 启动时加载。自动加载的插件可以以两种方式配置

• urls 是一个 URL 列表，当 JupyterLab 启动时将自动获取和加载作为插件。例如，您可以指向 GitHub gist 或您在本地服务器上托管并像上述示例那样提供文本文件的文件。
• plugins 是字符串的插件文本列表，如上面的示例，当 JupyterLab 启动时将自动加载。由于 JSON 字符串不能有多个行，您需要将插件文本中的任何新行直接编码为 \n\（第二个反斜杠是为了允许字符串在下一行继续）。例如，这里是一个用户设置，用于编码在启动时运行的小插件

  {
    plugins: [
      "{ \n\
        id: 'MyConsoleLoggingPlugin', \n\
        autoStart: true, \n\
        activate: function(app) { \n\
          console.log('Activated!'); \n\
        } \n\
      }"
    ]
  }
  

贡献

开发安装

您需要 NodeJS 来构建扩展包。

# Clone the repo to your local environment
# Change directory to the jupyterlab-plugin-playground directory
# Install package in development mode
pip install -e .
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm run build

您可以在不同的终端中同时监视源目录并运行 JupyterLab，以监视扩展源的变化并自动重新构建扩展。

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm run watch
# Run JupyterLab in another terminal
jupyter lab

当监视命令运行时，每次保存的更改都会立即在本地构建并提供给您正在运行的 JupyterLab。刷新 JupyterLab 以在浏览器中加载更改（您可能需要等待几秒钟，直到扩展被重新构建）。

默认情况下，jlpm run build 命令会为该扩展生成源映射，以便使用浏览器开发者工具更容易地进行调试。若要同时为 JupyterLab 核心扩展生成源映射，可以运行以下命令

jupyter lab build --minimize=False

开发模式下的卸载

pip uninstall jupyterlab-plugin-playground

在开发模式下，您还需要删除 jupyter labextension develop 命令创建的符号链接。要找到其位置，可以运行 jupyter labextension list 来确定 labextensions 文件夹的位置。然后您可以在该文件夹中删除名为 @jupyterlab/plugin-playground 的符号链接。

打包扩展

请参阅 RELEASE