自定义扩展#

Bokeh 配备了丰富多样的内置功能，使您能够在浏览器中生成复杂的交互式可视化和数据应用程序。然而，一些有用的功能和特性可能无法进入核心库，要么是因为它们过于主题化，要么是由于资源不足。幸运的是，您可以使用自定义扩展来扩展 Bokeh 的功能，这些扩展允许您

修改现有 Bokeh 模型的行为
添加新模型以将第三方 JavaScript 库连接到 Python
为特定领域用例创建高度主题化的模型

您可以使用标准版本制作和使用自定义扩展，并且无需设置开发环境或从源代码构建任何内容。这是参与 Bokeh 开发的最简单方法。您可以尝试新功能和改进的功能，而无需等待核心团队将它们实现到 Bokeh 本身中。

注意

扩展 Bokeh 是一项高级功能。创建和使用扩展的某些方面仍在积极开发中，应被视为实验性的。

Bokeh 模型的结构#

Python 模型#

在大多数情况下，Python Bokeh 模型是完全声明式的类。您可以通过从 Model 创建子类并包含特殊的类属性来声明要在 JavaScript 端镜像的属性，从而创建自定义扩展。有关所有可用的属性类型，请参阅 bokeh.core.properties 部分的参考指南。

这是一个简单的示例，用于为滑块创建自定义读数

from bokeh.core.properties import String, Instance
from bokeh.models import UIElement, Slider

class Custom(UIElement):

    text = String(default="Custom text")

    slider = Instance(Slider)

此示例从 UIElement 创建子类，以允许扩展集成到 DOM 布局中。它还添加了两个属性

一个 String，用于配置读数的文本消息，以及
一个 Instance，可以容纳 Slider。

这将创建一个 JavaScript Slider 对象，该对象对应于 Python 中的 Slider。

JavaScript 模型和视图#

虽然 Python 端几乎没有代码，但 JavaScript 端需要代码来实现模型。您还需要为必要的相应视图提供代码。

这是一个用于 Custom 及其 CustomView 的带注释的 TypeScript 实现。对于内置模型，此类代码直接包含在最终的 BokehJS 脚本中。

import {UIElement, UIElementView} from "models/ui/ui_element"
import {Slider} from "models/widgets/sliders/slider"
import {div} from "core/dom"
import * as p from "core/properties"

export class CustomView extends UIElementView {
  declare model: Custom

  private content_el: HTMLElement

  override connect_signals(): void {
    super.connect_signals()
    this.connect(this.model.slider.change, () => this._update_text())
  }

  override render(): void {
    // BokehJS views create <div> elements by default. These are accessible
    // as ``this.el``. Many Bokeh views ignore the default <div> and
    // instead do things like draw to the HTML canvas. In this case though,
    // the program changes the contents of the <div> based on the current
    // slider value.
    super.render()

    this.content_el = div({style: {
      textAlign: "center",
      fontSize: "1.2em",
      padding: "2px",
      color: "#b88d8e",
      backgroundColor: "#2a3153",
    }})
    this.shadow_el.append(this.content_el)

    this._update_text()
  }

  private _update_text(): void {
    this.content_el.textContent = `${this.model.text}: ${this.model.slider.value}`
  }
}

export namespace Custom {
  export type Attrs = p.AttrsOf<Props>

  export type Props = UIElement.Props & {
    text: p.Property<string>
    slider: p.Property<Slider>
  }
}

export interface Custom extends Custom.Attrs {}

export class Custom extends UIElement {
  declare properties: Custom.Props
  declare __view_type__: CustomView

  constructor(attrs?: Partial<Custom.Attrs>) {
    super(attrs)
  }

  static {
    // If there is an associated view, this is typically boilerplate.
    this.prototype.default_view = CustomView

    // The this.define() block adds corresponding "properties" to the JS
    // model. These should normally line up 1-1 with the Python model
    // class. Most property types have counterparts. For example,
    // bokeh.core.properties.String will correspond to ``String`` in the
    // JS implementation. Where JS lacks a given type, you can use
    // ``p.Any`` as a "wildcard" property type.
    this.define<Custom.Props>(({Str, Ref}) => ({
      text:   [ Str, "Custom text" ],
      slider: [ Ref(Slider) ],
    }))
  }
}

将它们放在一起#

对于内置 Bokeh 模型，构建过程会自动将 BokehJS 中的实现与相应的 Python 模型匹配。Python 类还应该有一个名为 __implementation__ 的类属性，其值为定义客户端模型以及任何可选视图的 JavaScript（或 TypeScript）代码。

假设您将前面示例中的 TypeScript 代码保存在名为 custom.ts 的文件中，则完整的 Python 类可能如下所示

from bokeh.core.properties import String, Instance
from bokeh.models import UIElement, Slider

class Custom(UIElement):

    __implementation__ = "custom.ts"

    text = String(default="Custom text")

    slider = Instance(Slider)

假设 Python 模块 custom.py 定义了这个类，您现在可以像使用任何内置 Bokeh 模型一样使用自定义扩展。

from bokeh.io import show, output_file
from bokeh.layouts import column
from bokeh.models import Slider

slider = Slider(start=0, end=10, step=0.1, value=0, title="value")

custom = Custom(text="Special Slider Display", slider=slider)

layout = column(slider, custom)

show(layout)

这将产生以下输出

渲染的文档自动包含实现的 JavaScript 代码。移动滑块以查看特殊标题随着滑块的移动而更新。

指定实现语言#

如果 __implementation__ 的值是以 .js 或 .ts 结尾的单行，则 Bokeh 会将其解释为文件名，打开该文件，并根据文件的扩展名编译其内容。

如果需要内联实现，请使用类 JavaScript 或 TypeScript 指定源代码的语言。这是一个例子

class Custom(Model):

    __implementation__ = JavaScript(" <JS code here> ")

指定默认值#

如果您的属性具有默认值，则必须在 Python 端和 JavaScript 端都提供默认值。您提供的值在两端应相同。出于效率原因，Bokeh 仅传输用户已从其默认值显式更改的属性值。

作为一个具体的例子，默认值为 True 的布尔属性 flag 在 Python 端应如下所示

flag = Bool(default=True)

它在 Bokeh 端应如下所示

flag: [ Boolean, true ]

提供外部资源#

您可能需要第三方 JavaScript 库或 CSS 资源才能在 Bokeh 中实现自定义模型。您可以通过自定义模型的 __javascript__ 和 __css__ Python 类属性提供外部资源。

包含外部资源的 URL 路径会将它们添加到 HTML 文档头部，使 JavaScript 库在全局命名空间中可用，并应用自定义 CSS 样式。

这是一个示例，其中包含 KaTeX（一个具有 LaTeX 支持的 JS 库）的 JS 和 CSS 文件，以便创建 LatexLabel 自定义模型。

class LatexLabel(Label):
    """A subclass of the built-in Bokeh model `Label` that supports
    rendering LaTeX with the KaTeX typesetting library.
    """
    __javascript__ = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.js"
    __css__ = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.css"
    __implementation__ = """
    # do something here
    """

有关完整的实现及其输出，请参阅下面扩展库中的 LaTeX 示例。

与 Bokeh 服务器集成#

您无需执行任何额外工作即可将自定义扩展与 Bokeh 服务器集成。对于独立文档，渲染的应用程序会自动包含 JavaScript 实现。此外，Bokeh 模型属性的标准同步对于自定义用户扩展是透明的，与内置模型相同。

示例#

本节旨在为您提供基本示例，以帮助您开始创建自定义扩展。然而，这是一个有些高级的主题，您通常需要研究 bokehjs/src/lib/models 中基类的源代码才能取得进展。

专门的坐标轴刻度: 子类化内置的 Bokeh 坐标轴模型，以自定义坐标轴刻度行为。
新的自定义工具: 创建一个全新的工具，可以在绘图画布上绘制。
包装 JavaScript 库: 通过将第三方 JavaScript 库包装在 Bokeh 自定义扩展中，将 Python 连接到该库。
添加自定义小部件: 在扩展小部件中包含第三方 JavaScript 库。

预构建扩展#

到目前为止，本章介绍了简单的，通常是内联的扩展。这些对于 Bokeh 的临时添加非常有用，但对于认真的开发而言，这种方法并不是特别方便。

例如，某些配置文件（如 package.json 或 tsconfig.json）的隐式性质不允许您在为扩展编写 TypeScript 或 JavaScript 时充分利用 IDE 的功能。

进入预构建扩展。

要创建预构建扩展，请使用 bokeh init 命令。这将创建所有必要的文件，包括 bokeh.ext.json、package.json 和 tsconfig.json。

要逐步创建和自定义扩展，请运行 bokeh init --interactive。

要构建您的扩展，请使用 bokeh build 命令。如有必要，这将运行 npm install，编译 TypeScript 文件，转换 JavaScript 文件，解析模块，并将它们链接到可分发的捆绑包中。

Bokeh 缓存编译产品以提高性能。如果这导致问题，请使用 bokeh build --rebuild 命令从头开始重建您的扩展。