JavaScript 回调#
Bokeh 的主要目标是提供一种途径，完全通过 Python 在浏览器中创建丰富的交互式可视化。然而，总会有一些用例超出预定义核心库的功能范围。
因此，Bokeh 提供了不同的方式，供用户在必要时提供自定义 JavaScript。通过这种方式，您可以响应浏览器中的属性更改和其他事件，添加自定义或主题行为。
注意
顾名思义，JavaScript 回调是在浏览器中执行的 JavaScript 代码片段。如果您正在寻找仅基于 Python 且可以使用 Bokeh 服务器运行的交互式回调，请参阅Python 回调。
主要有三种生成 JavaScript 回调的选项
使用
js_linkPython 便利方法。此方法帮助您将不同模型的属性链接在一起。使用此方法，Bokeh 会自动为您创建必要的 JavaScript 代码。有关详细信息，请参阅联动行为。使用
SetValuePython 对象，根据另一个对象的特定事件动态设置一个对象的属性。有关更多信息，请参阅SetValue 回调。使用
CustomJS对象编写自定义 JavaScript 代码。有关更多信息，请参阅CustomJS 回调。
当浏览器中发生某些事件时，会触发 JavaScript 回调。主要有两种JavaScript 回调触发器类型
大多数 Bokeh 对象都有一个
.js_on_change属性（例如，所有组件）。每当对象的状态更改时，都会调用分配给此属性的回调。有关更多信息，请参阅js_on_change 回调触发器。某些组件还具有
.js_on_event属性。每当浏览器中发生特定事件时，都会调用分配给此属性的回调。
警告
CustomJS 模型的明确目的是嵌入原始 JavaScript 代码供浏览器执行。如果代码的任何部分源自不受信任的用户输入，则您必须采取适当的措施来清理用户输入，然后再将其传递给 Bokeh。
此外，您可以通过编写自己的Bokeh 扩展来添加全新的自定义扩展模型。
SetValue 回调#
使用 SetValue 模型，在浏览器中发生事件时动态设置对象的特定属性。
SetValue 模型具有以下属性
obj：要设置值的对象。attr：要修改的对象的属性。value：要为对象属性设置的值。
基于这些参数，Bokeh 会自动创建必要的 JavaScript 代码
from bokeh.io import show
from bokeh.models import Button, SetValue
button = Button(label="Foo", button_type="primary")
callback = SetValue(obj=button, attr="label", value="Bar")
button.js_on_event("button_click", callback)
show(button)
CustomJS 回调#
使用 CustomJS 模型，在事件发生时提供自定义 JavaScript 代码片段以在浏览器中运行。
from bokeh.models.callbacks import CustomJS
callback = CustomJS(args=dict(xr=plot.x_range, yr=plot.y_range, slider=slider), code="""
// imports
import {some_function, SOME_VALUE} from "https://cdn.jsdelivr.net.cn/npm/package@version/file"
// constants, definitions and state
const MY_VALUE = 3.14
function my_function(value) {
return MY_VALUE*value
}
class MyClass {
constructor(value) {
this.value = value
}
}
let count = 0
// the callback function
export default (args, obj, data, context) => {
count += 1
console.log(`CustomJS was called ${count} times`)
const a = args.slider.value
const b = obj.value
const {xr, yr} = args
xr.start = my_function(a)
xr.end = b
}
""")
代码片段必须包含一个默认导出，该导出必须是一个函数，可以使用箭头函数语法 () => {} 或经典函数语法 function() {} 定义。根据上下文，此函数可以是异步函数、生成器函数或异步生成器函数。同样，根据上下文，此函数可能需要也可能不需要返回值。
回调函数使用四个位置参数
args这映射到
CustomJS.args属性，允许将名称映射到可序列化的值，通常提供从代码片段访问 Bokeh 模型的能力。
obj这指的是发出回调的模型（这是回调附加到的模型）。
data这是此回调的发出者提供的名称和值之间的映射。这取决于调用者、事件以及事件发生的上下文。例如，选择工具将使用
data来提供选择几何图形等。
context这是 bokehjs 提供的额外的更广泛的上下文，它类似于
data，是名称和值之间的映射。目前仅提供index，允许用户访问 bokehjs 的视图索引。
用户可以使用对象解构语法来立即访问传递的值，例如，这可能很方便
from bokeh.models.callbacks import CustomJS
callback = CustomJS(args=dict(xr=plot.x_range, yr=plot.y_range, slider=slider), code="""
export default ({xr, yr, slider}, obj, {geometry}, {index}) => {
// use xr, yr, slider, geometry and index
}
""")
代码片段编译一次，回调函数（默认导出）可以多次求值。这样，用户可以稳健高效地导入外部库、定义复杂的类和数据结构，并在回调函数的调用之间维护状态。仅当 CustomJS 实例的属性更改时，才会重新编译代码片段。
或者，用户可以使用 CustomJS 的旧版本，其中代码片段是隐式回调函数的主体
from bokeh.models.callbacks import CustomJS
callback = CustomJS(args=dict(xr=plot.x_range), code="""
// JavaScript code goes here
const a = 10
// the model that triggered the callback is cb_obj:
const b = cb_obj.value
// models passed as args are auto-magically available
xr.start = a
xr.end = b
""")
Bokeh 通过检测代码片段中是否存在 import 和 export 语法来区分这两种方法。
在这种方法中，回调函数的参数是隐式定义的。CustomJS.args 提供的名称立即作为位置参数可用，而 obj、data 和 context 都带有 cb_ 前缀可用，即 cb_obj、cb_data 和 cb_context。
最后，用户可以从文件创建 CustomJS，这在处理大型和/或复杂的代码片段时非常有用
from bokeh.models.callbacks import CustomJS
callback = CustomJS.from_file("./my_module.mjs", xr=plot.x_range)
允许的扩展名是
.mjs用于新的export default () => {}变体.js用于旧版CustomJS
js_on_change 回调触发器#
CustomJS 和 SetValue 回调可以使用 Bokeh 模型的 js_on_change 方法附加到任何 Bokeh 模型的属性更改事件
p = figure()
# execute a callback whenever p.x_range.start changes
p.x_range.js_on_change('start', callback)
以下示例将 CustomJS 回调附加到 Slider 组件。每当滑块值更新时，回调都会使用自定义公式更新绘图数据
from bokeh.layouts import column
from bokeh.models import ColumnDataSource, CustomJS, Slider
from bokeh.plotting import figure, show
x = [x*0.005 for x in range(0, 200)]
y = x
source = ColumnDataSource(data=dict(x=x, y=y))
plot = figure(width=400, height=400, x_range=(0, 1), y_range=(0, 1))
plot.line('x', 'y', source=source, line_width=3, line_alpha=0.6)
callback = CustomJS(args=dict(source=source), code="""
const f = cb_obj.value
const x = source.data.x
const y = Array.from(x, (x) => Math.pow(x, f))
source.data = { x, y }
""")
slider = Slider(start=0.1, end=4, value=1, step=.1, title="power")
slider.js_on_change('value', callback)
layout = column(slider, plot)
show(layout)
js_on_event 回调触发器#
除了使用 js_on_change 响应属性更改事件外，Bokeh 还允许 CustomJS 和 SetValue 回调由与绘图画布的特定交互事件、按钮单击事件、LOD（细节级别）事件和文档事件触发。
这些事件回调是使用 js_on_event 方法在模型上定义的，回调接收事件对象作为本地定义的 cb_obj 变量
from bokeh.models.callbacks import CustomJS
callback = CustomJS(code="""
// the event that triggered the callback is cb_obj:
// The event type determines the relevant attributes
console.log('Tap event occurred at x-position: ' + cb_obj.x)
""")
p = figure()
# execute a callback whenever the plot canvas is tapped
p.js_on_event('tap', callback)
事件可以指定为字符串，例如上面的 'tap'，或从 bokeh.events 模块导入事件类（即 from bokeh.events import Tap）。
以下代码导入 bokeh.events 并使用 display_event 函数注册所有可用的事件类，以便生成 CustomJS 对象。此函数用于使用事件名称（始终可以从 event_name 属性访问）以及所有其他适用的事件属性更新 Div。结果是一个绘图，当用户与之交互时，会在右侧显示相应的事件
from __future__ import annotations
import numpy as np
from bokeh import events
from bokeh.io import curdoc, show
from bokeh.layouts import column, row
from bokeh.models import Button, CustomJS, Div, TextInput
from bokeh.plotting import figure
def display_event(div: Div, attributes: list[str] = []) -> CustomJS:
"""
Function to build a suitable CustomJS to display the current event
in the div model.
"""
style = 'float: left; clear: left; font-size: 13px'
return CustomJS(args=dict(div=div), code=f"""
const attrs = {attributes};
const args = [];
for (let i = 0; i < attrs.length; i++) {{
const val = JSON.stringify(cb_obj[attrs[i]], function(key, val) {{
return val.toFixed ? Number(val.toFixed(2)) : val;
}})
args.push(attrs[i] + '=' + val)
}}
const line = "<span style={style!r}><b>" + cb_obj.event_name + "</b>(" + args.join(", ") + ")</span>\\n";
const text = div.text.concat(line);
const lines = text.split("\\n")
if (lines.length > 35)
lines.shift();
div.text = lines.join("\\n");
""")
N = 4000
x = np.random.random(size=N) * 100
y = np.random.random(size=N) * 100
radii = np.random.random(size=N) * 1.5
colors = np.array([(r, g, 150) for r, g in zip(50+2*x, 30+2*y)], dtype="uint8")
p = figure(tools="pan,wheel_zoom,zoom_in,zoom_out,reset,tap,lasso_select,box_select,box_zoom,undo,redo")
p.circle(x, y, radius=radii, fill_color=colors, fill_alpha=0.6, line_color=None)
# Add a div to display events and a button to trigger button click events
div = Div(width=1000)
button = Button(label="Button", button_type="success", width=300)
text_input = TextInput(placeholder="Input a value and press Enter ...", width=300)
layout = column(button, text_input, row(p, div))
# Register event callbacks
# Button events
button.js_on_event(events.ButtonClick, display_event(div))
# TextInput events
text_input.js_on_event(events.ValueSubmit, display_event(div, ["value"]))
# AxisClick events
p.xaxis[0].js_on_event(events.AxisClick, display_event(div, ["value"]))
p.yaxis[0].js_on_event(events.AxisClick, display_event(div, ["value"]))
# LOD events
p.js_on_event(events.LODStart, display_event(div))
p.js_on_event(events.LODEnd, display_event(div))
# Point events
point_attributes = ['x','y','sx','sy']
p.js_on_event(events.Tap, display_event(div, attributes=point_attributes))
p.js_on_event(events.DoubleTap, display_event(div, attributes=point_attributes))
p.js_on_event(events.Press, display_event(div, attributes=point_attributes))
p.js_on_event(events.PressUp, display_event(div, attributes=point_attributes))
# Mouse wheel event
p.js_on_event(events.MouseWheel, display_event(div,attributes=[*point_attributes, 'delta']))
# Mouse move, enter and leave
# p.js_on_event(events.MouseMove, display_event(div, attributes=point_attributes))
p.js_on_event(events.MouseEnter, display_event(div, attributes=point_attributes))
p.js_on_event(events.MouseLeave, display_event(div, attributes=point_attributes))
# Pan events
pan_attributes = [*point_attributes, 'delta_x', 'delta_y']
p.js_on_event(events.Pan, display_event(div, attributes=pan_attributes))
p.js_on_event(events.PanStart, display_event(div, attributes=point_attributes))
p.js_on_event(events.PanEnd, display_event(div, attributes=point_attributes))
# Pinch events
pinch_attributes = [*point_attributes, 'scale']
p.js_on_event(events.Pinch, display_event(div, attributes=pinch_attributes))
p.js_on_event(events.PinchStart, display_event(div, attributes=point_attributes))
p.js_on_event(events.PinchEnd, display_event(div, attributes=point_attributes))
# Ranges Update events
p.js_on_event(events.RangesUpdate, display_event(div, attributes=['x0','x1','y0','y1']))
# Selection events
p.js_on_event(events.SelectionGeometry, display_event(div, attributes=['geometry', 'final']))
curdoc().on_event(events.DocumentReady, display_event(div))
show(layout)
文档事件的 JS 回调可以使用 Document.js_on_event() 方法注册。在独立嵌入模式下，将使用当前文档通过 curdoc() 来设置此类回调。例如
from bokeh.models import Div
from bokeh.models.callbacks import CustomJS
from bokeh.io import curdoc, show
div = Div()
# execute a callback when the document is fully rendered
callback = CustomJS(args=dict(div=div, code="""div.text = "READY!"""")
curdoc().js_on_event("document_ready", callback)
show(div)
与模型级 JS 事件类似，也可以使用事件类代替事件名称来注册文档事件回调
from bokeh.events import DocumentReady
curdoc().js_on_event(DocumentReady, callback)
示例#
CustomJS 用于组件#
属性回调的常见用例是响应组件的更改。下面的代码显示了一个在滑块组件上设置 CustomJS 的示例，该组件在滑块使用时更改绘图的源。
from bokeh.layouts import column
from bokeh.models import ColumnDataSource, CustomJS, Slider
from bokeh.plotting import figure, show
x = [x*0.005 for x in range(0, 200)]
y = x
source = ColumnDataSource(data=dict(x=x, y=y))
plot = figure(width=400, height=400, x_range=(0, 1), y_range=(0, 1))
plot.line('x', 'y', source=source, line_width=3, line_alpha=0.6)
callback = CustomJS(args=dict(source=source), code="""
const f = cb_obj.value
const x = source.data.x
const y = Array.from(x, (x) => Math.pow(x, f))
source.data = { x, y }
""")
slider = Slider(start=0.1, end=4, value=1, step=.1, title="power")
slider.js_on_change('value', callback)
show(column(slider, plot))
CustomJS 用于选择#
另一种常见的情况是希望指定在选择更改时执行相同类型的回调。作为一个简单的演示，下面的示例只是将第一个绘图上的选定点复制到第二个绘图。然而，更复杂的操作和计算也很容易以类似的方式构建。
from random import random
from bokeh.layouts import row
from bokeh.models import ColumnDataSource, CustomJS
from bokeh.plotting import figure, show
x = [random() for x in range(500)]
y = [random() for y in range(500)]
s1 = ColumnDataSource(data=dict(x=x, y=y))
p1 = figure(width=400, height=400, tools="lasso_select", title="Select Here")
p1.scatter('x', 'y', source=s1, alpha=0.6)
s2 = ColumnDataSource(data=dict(x=[], y=[]))
p2 = figure(width=400, height=400, x_range=(0, 1), y_range=(0, 1),
tools="", title="Watch Here")
p2.scatter('x', 'y', source=s2, alpha=0.6)
s1.selected.js_on_change('indices', CustomJS(args=dict(s1=s1, s2=s2), code="""
const inds = cb_obj.indices
const d1 = s1.data
const x = Array.from(inds, (i) => d1.x[i])
const y = Array.from(inds, (i) => d1.y[i])
s2.data = {x, y}
"""),
)
layout = row(p1, p2)
show(layout)
下面显示了另一个更复杂的示例。它计算任何选定点（包括多个不相交的选择）的平均 y 值，并绘制一条穿过该值的线。
from random import random
from bokeh.models import ColumnDataSource, CustomJS
from bokeh.plotting import figure, show
x = [random() for x in range(500)]
y = [random() for y in range(500)]
s = ColumnDataSource(data=dict(x=x, y=y))
p = figure(width=400, height=400, tools="lasso_select", title="Select Here")
p.scatter('x', 'y', color='navy', size=8, source=s, alpha=0.4,
selection_color="firebrick")
s2 = ColumnDataSource(data=dict(x=[0, 1], ym=[0.5, 0.5]))
p.line(x='x', y='ym', color="orange", line_width=5, alpha=0.6, source=s2)
s.selected.js_on_change('indices', CustomJS(args=dict(s=s, s2=s2), code="""
const inds = s.selected.indices
if (inds.length > 0) {
const ym = inds.reduce((a, b) => a + s.data.y[b], 0) / inds.length
s2.data = { x: s2.data.x, ym: [ym, ym] }
}
"""))
show(p)
CustomJS 用于范围#
范围对象的属性也可以连接到 CustomJS 回调，以便在范围更改时执行主题工作
import numpy as np
from bokeh.layouts import row
from bokeh.models import BoxAnnotation, CustomJS
from bokeh.plotting import figure, show
N = 4000
x = np.random.random(size=N) * 100
y = np.random.random(size=N) * 100
radii = np.random.random(size=N) * 1.5
colors = np.array([(r, g, 150) for r, g in zip(50+2*x, 30+2*y)], dtype="uint8")
box = BoxAnnotation(left=0, right=0, bottom=0, top=0,
fill_alpha=0.1, line_color='black', fill_color='black')
jscode = """
box[%r] = cb_obj.start
box[%r] = cb_obj.end
"""
p1 = figure(title='Pan and Zoom Here', x_range=(0, 100), y_range=(0, 100),
tools='box_zoom,wheel_zoom,pan,reset', width=400, height=400)
p1.circle(x, y, radius=radii, fill_color=colors, fill_alpha=0.6, line_color=None)
xcb = CustomJS(args=dict(box=box), code=jscode % ('left', 'right'))
ycb = CustomJS(args=dict(box=box), code=jscode % ('bottom', 'top'))
p1.x_range.js_on_change('start', xcb)
p1.x_range.js_on_change('end', xcb)
p1.y_range.js_on_change('start', ycb)
p1.y_range.js_on_change('end', ycb)
p2 = figure(title='See Zoom Window Here', x_range=(0, 100), y_range=(0, 100),
tools='', width=400, height=400)
p2.circle(x, y, radius=radii, fill_color=colors, fill_alpha=0.6, line_color=None)
p2.add_layout(box)
layout = row(p1, p2)
show(layout)
CustomJS 用于工具#
SelectionGeometry 的回调使用 BoxSelectTool 几何图形（通过 cb_data 回调对象的 geometry 字段访问），以便更新 Rect 字形。
from bokeh.events import SelectionGeometry
from bokeh.models import ColumnDataSource, CustomJS, Quad
from bokeh.plotting import figure, show
source = ColumnDataSource(data=dict(left=[], right=[], top=[], bottom=[]))
callback = CustomJS(args=dict(source=source), code="""
const geometry = cb_obj.geometry
const data = source.data
// quad is forgiving if left/right or top/bottom are swapped
source.data = {
left: data.left.concat([geometry.x0]),
right: data.right.concat([geometry.x1]),
top: data.top.concat([geometry.y0]),
bottom: data.bottom.concat([geometry.y1])
}
""")
p = figure(width=400, height=400, title="Select below to draw rectangles",
tools="box_select", x_range=(0, 1), y_range=(0, 1))
# using Quad model directly to control (non)selection glyphs more carefully
quad = Quad(left='left', right='right', top='top', bottom='bottom',
fill_alpha=0.3, fill_color='#009933')
p.add_glyph(
source,
quad,
selection_glyph=quad.clone(fill_color='blue'),
nonselection_glyph=quad.clone(fill_color='gray'),
)
p.js_on_event(SelectionGeometry, callback)
show(p)
CustomJS 用于主题事件#
除了上面描述的用于向 Bokeh 模型添加 CustomJS 回调的通用机制外，还有一些 Bokeh 模型具有专门用于响应特定事件或情况执行 CustomJS 的 .callback 属性。
警告
下面描述的回调是在早期以临时方式添加到 Bokeh 中的。它们中的许多可以通过上面描述的通用机制来实现，因此，将来可能会弃用它们，转而使用通用机制。
CustomJS 用于悬停工具#
HoverTool 有一个回调，它带有两个内置数据：index 和 geometry。index 是悬停工具悬停在任何点上的索引。
from bokeh.models import ColumnDataSource, CustomJS, HoverTool
from bokeh.plotting import figure, show
# define some points and a little graph between them
x = [2, 3, 5, 6, 8, 7]
y = [6, 4, 3, 8, 7, 5]
links = {
0: [1, 2],
1: [0, 3, 4],
2: [0, 5],
3: [1, 4],
4: [1, 3],
5: [2, 3, 4],
}
p = figure(width=400, height=400, tools="", toolbar_location=None, title='Hover over points')
source = ColumnDataSource(dict(x0=[], y0=[], x1=[], y1=[]))
sr = p.segment(x0='x0', y0='y0', x1='x1', y1='y1', color='olive', alpha=0.6, line_width=3, source=source )
cr = p.scatter(x, y, color='olive', size=30, alpha=0.4, hover_color='olive', hover_alpha=1.0)
# add a hover tool that sets the link data for a hovered circle
code = """
const data = {x0: [], y0: [], x1: [], y1: []}
const {indices} = cb_data.index
for (const start of indices) {
for (const end of links.get(start)) {
data.x0.push(circle.data.x[start])
data.y0.push(circle.data.y[start])
data.x1.push(circle.data.x[end])
data.y1.push(circle.data.y[end])
}
}
segment.data = data
"""
callback = CustomJS(args=dict(circle=cr.data_source, segment=sr.data_source, links=links), code=code)
p.add_tools(HoverTool(tooltips=None, callback=callback, renderers=[cr]))
show(p)
OpenURL#
当用户单击字形（例如圆形标记）时打开 URL 是一项非常受欢迎的功能。Bokeh 允许用户通过公开 OpenURL 回调对象来启用此功能，该对象可以传递给 Tap 工具，以便在用户单击字形时调用该操作。
以下代码显示了如何使用 OpenURL 操作与 TapTool 结合使用，以便在用户单击圆形时打开 URL。
from bokeh.models import ColumnDataSource, OpenURL, TapTool
from bokeh.plotting import figure, show
p = figure(width=400, height=400,
tools="tap", title="Click the Dots")
source = ColumnDataSource(data=dict(
x=[1, 2, 3, 4, 5],
y=[2, 5, 8, 2, 7],
color=["navy", "orange", "olive", "firebrick", "gold"],
))
p.scatter('x', 'y', color='color', size=20, source=source)
# use the "color" column of the CDS to complete the URL
# e.g. if the glyph at index 10 is selected, then @color
# will be replaced with source.data['color'][10]
url = "https://www.html-color-names.com/@color.php"
taptool = p.select(type=TapTool)
taptool.callback = OpenURL(url=url)
show(p)
请注意，OpenURL 回调专门且仅适用于 TapTool，并且仅在点击字形时调用。也就是说，它们不会在每次点击时执行。如果您想在每次鼠标点击时执行回调，请参阅js_on_event 回调触发器。