用户界面助手

JupyterLab 提供了一些助手，用于向用户显示或请求简单的信息。这些助手可加快开发速度，并确保通用外观和感受。

对话框

通用对话框

要显示通用对话框，请使用 @jupyterlab/apputils 中的 showDialog 函数。

可用选项如下：

showDialog({
  title: 'Dialog title', // Can be text or a react element
  body: 'Dialog body', // Can be text, a widget or a react element
  host: document.body, // Parent element for rendering the dialog
  buttons: [ // List of buttons
   {
     label: 'my button', // Button label
     caption: 'my button title', // Button title
     className: 'my-button', // Additional button CSS class
     accept: true, // Whether this button will discard or accept the dialog
     displayType: 'default' // applies 'default' or 'warn' styles
   }
  ],
  checkbox: { // Optional checkbox in the dialog footer
    label: 'check me', // Checkbox label
    caption: 'check me I\'magic', // Checkbox title
    className: 'my-checkbox', // Additional checkbox CSS class
    checked: true, // Default checkbox state
  },
  defaultButton: 0, // Index of the default button
  focusNodeSelector: '.my-input', // Selector for focussing an input element when dialog opens
  hasClose: false, // Whether to display a close button or not
  renderer: undefined // To define customized dialog structure
})

注意

如果未指定任何选项，对话框将只包含“确定”和“取消”按钮。

消息对话框

apputils 包中提供了向用户显示消息的辅助函数。当用户关闭对话框时，这些对话框会返回一个解析的 Promise。

有一个助手

• showErrorMessage：显示错误消息对话框。

输入对话框

apputils 包中 InputDialog 命名空间内提供了向用户请求单个输入的辅助函数。共有四个助手：

• getBoolean：通过复选框请求布尔值。

• getItem：从列表中请求一个项目；该列表可能是可编辑的。

• getNumber：请求一个数字；如果用户输入不是有效数字，则返回 NaN。

• getText：请求一个短文本。

• getPassword：请求一个短密码。

所有对话框均基于标准 Dialog 构建。因此，每个辅助函数都会返回一个解析为 Dialog.IResult 对象的 Promise。

// Request a boolean
InputDialog.getBoolean({ title: 'Check or not?' }).then(value => {
  console.log('boolean ' + value.value);
});

// Request a choice from a list
InputDialog.getItem({
  title: 'Pick a choice',
  items: ['1', '2']
}).then(value => {
  console.log('item ' + value.value);
});

// Request a choice from a list or specify your own choice
InputDialog.getItem({
  title: 'Pick a choice or write your own',
  items: ['1', '2'],
  editable: true
}).then(value => {
  console.log('editable item ' + value.value);
});

// Request a number
InputDialog.getNumber({ title: 'How much?' }).then(value => {
  console.log('number ' + value.value);
});

// Request a text
InputDialog.getText({ title: 'Provide a text' }).then(value => {
  console.log('text ' + value.value);
});

// Request a text
InputDialog.getPassword({ title: 'Input password' }).then(value => {
  console.log('A password was input');
});

文件对话框

filebrowser 包中的 FileDialog 命名空间下提供了两个辅助函数，用于请求用户打开文件或文件夹。

这是一个请求文件的示例。

const dialog = FileDialog.getOpenFiles({
  manager, // IDocumentManager
  filter: model => model.type == 'notebook' // optional (model: Contents.IModel) => boolean
});

const result = await dialog;

if(result.button.accept){
  let files = result.value;
}

以及请求文件夹的示例。

const dialog = FileDialog.getExistingDirectory({
  manager // IDocumentManager
});

const result = await dialog;

if(result.button.accept){
  let folders = result.value;
}

注意

可以通过请求 IFileBrowserFactory 令牌在插件中获取文档管理器。manager 将通过 factory.defaultBrowser.model.manager 访问。

通知

JupyterLab 有一个通知管理器，可以添加、更新或关闭通知。此功能由 @jupyterlab/apputils 包提供。

警告

限制发送通知的数量以尊重用户的注意力是一种良好的做法。因此，默认情况下，通知不会显示给用户。但状态栏会指示有新通知到达。这样用户可以点击指示器以查看所有通知。

对于重复通知，请尝试添加一个“不再向我显示”按钮，以允许用户快速筛选对他们重要的通知。

通知由以下元素描述：

{
  /**
   * Notification message
   *
   * ### Notes
   * Message can only be plain text with a maximum length of 140 characters.
   */
  message: string;
  /**
   * Notification type
   */
  type?:  'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
  /**
   * Notification options
   */
  options?: {
    /**
     * Autoclosing behavior - false (not closing automatically)
     * or number (time in milliseconds before hiding the notification)
     *
     * Set to zero if you want the notification to be retained in the notification
     * center but not displayed as toast. This is the default behavior.
     */
    autoClose?: number | false;
    /**
     * List of associated actions
     */
    actions?: Array<IAction>;
    /**
     * Data associated with a notification
     */
    data?: T;
  };
}

创建时，通知将收到一个唯一的标识符。

操作可以链接到通知，但接口取决于通知的处理方式。

与通知交互有两种方式：通过 API 或通过命令。唯一的区别是，当使用 API 时，链接到通知的操作可以有任意回调。但是，当使用命令调用创建通知时，只能将命令设置为操作。

使用 API

要创建通知，您需要提供一条消息，并且可以使用以下助手自动设置类型（或使用 notify 手动设置类型）：

/**
 * Helper function to emit an error notification.
 */
Notification.error(message: string, options?: IOptions): string;

/**
 * Helper function to emit an info notification.
 */
Notification.info(message: string, options?: IOptions): string;

/**
 * Helper function to emit a success notification.
 */
Notification.success(message: string, options?: IOptions): string;

/**
 * Helper function to emit a warning notification.
 */
Notification.warning(message: string, options?: IOptions): string;

/**
 * Helper function to emit a in-progress notification. Then
 * it will update it with a error or success notification
 * depending on the promise resolution.
 */
Notification.promise(
  promise: Promise,
  {
    pending: { message: string, options?: IOptions },
    /**
     * If not set `options.data` will be set to the promise result.
     */
    success: { message: (result, data) => string, options?: IOptions },
    /**
     * If not set `options.data` will be set to the promise rejection error.
     */
    error: { message: (reason, data) => string, options?: IOptions }
  }
): string;

/**
 * Helper function to emit a notification.
 */
Notification.emit(
  message: string,
  type: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default' = 'default',
  options?: IOptions
): string;

使用 API 时，操作由以下定义：

{
  /**
   * The action label.
   *
   * This should be a short description.
   */
  label: string;
  /**
   * Callback function to trigger
   *
   * ### Notes
   * By default execution of the callback will close the toast
   * and dismiss the notification. You can prevent this by calling
   * `event.preventDefault()` in the callback.
   */
  callback: (event: MouseEvent) => void;
  /**
   * The action caption.
   *
   * This can be a longer description of the action.
   */
  caption?: string;
  /**
   * The action display type.
   *
   * This will be used to modify the action button style.
   */
  displayType?: 'default' | 'accent' | 'warn' | 'link';
}

您可以使用以下方法更新通知：

Notification.update({
  id: string;
  message: string;
  type?:  'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
  autoClose?: number | false;
  actions?: Array<IAction>;
  data?: ReadonlyJsonValue;
}): boolean;

注意

更新后，通知将移至通知堆栈的开头。

您可以使用以下方法关闭通知（如果您提供 id）或所有通知：

Notification.dismiss(id?: string): void;

注意

关闭通知会将其从通知列表中删除，而不管用户是否已看到它。因此，建议不要关闭通知。

使用命令

有三个可用命令。

'apputils:notify' 用于创建通知

commands.execute('apputils:notify', {
   message: string;
   type?: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
   options?: {
     autoClose?: number | false;
     actions?: Array<IAction>;
     data?: T;
   };
});

结果是通知的唯一标识符。

动作定义如下：

{
  /**
   * The action label.
   *
   * This should be a short description.
   */
  label: string;
  /**
   * Callback command id to trigger
   */
  commandId: string;
  /**
   * Command arguments
   */
  args?: ReadonlyJsonObject;
  /**
   * The action caption.
   *
   * This can be a longer description of the action.
   */
  caption?: string;
  /**
   * The action display type.
   *
   * This will be used to modify the action button style.
   */
  displayType?: 'default' | 'accent' | 'warn' | 'link';
}

'apputils:update-notification' 用于更新通知

commands.execute('apputils:update-notification', {
  id: string;
  message: string;
  type?: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
  autoClose?: number | false;
  actions?: Array<IAction>;
  data?: T;
});

结果是一个布尔值，指示更新是否成功。特别是，更新不存在的通知将失败。

'apputils:dismiss-notification' 用于关闭通知

commands.execute('apputils:dismiss-notification', {
  id: string;
});

注意

关闭通知会将其从通知列表中删除，而不管用户是否已看到它。因此，建议不要关闭通知。