网页#
本章探讨了将独立的 Bokeh 文档和 Bokeh 应用程序嵌入到网页中的各种方法。首先，以下是独立文档与应用程序的不同之处
- 独立文档
这些文档不需要 Bokeh 服务器即可工作。它们可能具有许多工具和交互，例如自定义 JavaScript 回调，但在其他方面只是 HTML、CSS 和 JavaScript。这些文档可以作为大型文档或作为一组具有单独模板的子组件嵌入到其他 HTML 页面中。
- Bokeh 应用程序
这些应用程序需要 Bokeh 服务器才能工作。拥有 Bokeh 服务器可以让您将事件和工具连接到在服务器上执行的实时 Python 回调。有关创建和运行 Bokeh 应用程序的更多信息，请参阅 Bokeh 服务器。
独立文档#
本节介绍发布和嵌入独立 Bokeh 文档的不同方法。
HTML 文件#
Bokeh 可以使用 file_html() 函数为 Bokeh 文档生成完整的 HTML 页面。此函数可以使用其自己的通用模板或您提供的模板创建 HTML 文档。这些 HTML 文件包含绘图数据，并且完全可移植，同时仍为您的绘图提供交互式工具（平移、缩放等）。这是一个示例
from bokeh.plotting import figure
from bokeh.resources import CDN
from bokeh.embed import file_html
plot = figure()
plot.scatter([1,2], [3,4])
html = file_html(plot, CDN, "my plot")
您可以使用标准 Python 文件操作将返回的 HTML 文本保存到文件。您还可以为您自己的 HTML 输出提供模板，并传入自定义或额外的模板变量。有关更多详细信息，请参阅 file_html() 文档。
这是一种生成 HTML 文件的低级、显式方法，对于 Flask 应用程序等 Web 应用程序非常有用。
在脚本和使用 bokeh.plotting 接口的 Jupyter 笔记本中，您可以结合 show() 或 save() 调用 output_file() 函数。show() 函数创建一个 HTML 文档并在 Web 浏览器中显示它，而 save() 创建一个 HTML 文档并将其本地保存。
JSON 项目#
Bokeh 还可以提供 JSON 数据，BokehJS 可以使用这些数据在指定的 <div> 中渲染独立的 Bokeh 文档。json_item() 函数接受 Bokeh 模型（例如，绘图）和目标 <div> 的可选 ID。
p = figure()
p.scatter(x, y)
item_text = json.dumps(json_item(p, "myplot"))
embed_item() 函数随后可以在网页上使用此输出
item = JSON.parse(item_text);
Bokeh.embed.embed_item(item);
这将在 ID 为 “myplot” 的 <div> 中渲染绘图。
您也可以在调用 json_item() 时省略目标 ID
p = figure()
p.scatter(x, y)
item_text = json.dumps(json_item(p)) # no target ID given
然后您可以在 JavaScript 中指定 ID
item = JSON.parse(item_text);
Bokeh.embed.embed_item(item, "myplot");
这是一个更完整的 Flask 应用程序示例，它从 /plot 端点提供 Bokeh JSON 项目
@app.route('/plot')
def plot():
p = make_plot('petal_width', 'petal_length')
return json.dumps(json_item(p, "myplot"))
这将生成如下所示的 JavaScript 代码
<script>
fetch('/plot')
.then(function(response) { return response.json() })
.then(function(item) { return Bokeh.embed.embed_item(item) })
</script>
或者，使用现代语法，如下所示
<script>
const response = await fetch('/plot')
const item = await response.json()
Bokeh.embed.embed_item(item)
</script>
有关完整示例，请参阅 examples/output/apis/json_item.py。
组件#
您还可以让 Bokeh 返回独立文档的各个组件，以便使用 components() 函数逐个嵌入它们。此函数返回一个 <script>，其中包含绘图的数据并提供一个目标 <div> 以显示绘图视图。您可以根据需要在 HTML 文档中使用这些元素。
from bokeh.plotting import figure
from bokeh.embed import components
plot = figure()
plot.scatter([1,2], [3,4])
script, div = components(plot)
返回的 <script> 将如下所示
<script type="text/javascript">
(function() {
const fn = function() {
Bokeh.safely(function() {
const docs_json = { DOCUMENT DATA HERE };
const render_items = [{
"docid":"6833819f-9b5b-4904-821e-3f5eec77de9b",
"elementid":"9574d123-9332-4b5f-96cc-6323bef37f40",
"modelid":"7b328b27-9b14-4f7b-a5d8-0138bc7b0f59"
}];
Bokeh.embed.embed_items(docs_json, render_items);
});
};
if (document.readyState != "loading") fn();
else document.addEventListener("DOMContentLoaded", fn);
})();
</script>
请注意，Jupyter 笔记本不允许在同一个笔记本单元中使用 components() 和 show() 函数。
docs_json 包含所有数据以及绘图或小部件对象（为简洁起见此处省略）。生成的 <div> 如下所示
<div id="9574d123-9332-4b5f-96cc-6323bef37f40"></div>
您可以将此脚本及其配套的 <div> 插入或模板化到 HTML 文档中，当脚本执行时，您的绘图将替换 <div>。
为了使其工作，您首先需要加载 BokehJS，可以本地加载或从内容分发网络 (CDN) 加载。要从 CDN 加载 BokehJS，请将以下行添加到您的 HTML 文档或模板中，并用适当的版本替换 x.y.z
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-x.y.z.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-x.y.z.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-tables-x.y.z.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-gl-x.y.z.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-x.y.z.min.js"
crossorigin="anonymous"></script>
仅 Bokeh 核心库 bokeh-x.y.z.min.js 是始终必需的。其他脚本是可选的，只有当您想使用相应的功能时才需要包含它们
如果您正在使用任何 Bokeh 小部件，则只需要
"bokeh-widgets"文件。如果您正在使用 Bokeh 的 数据表，则只需要
"bokeh-tables"文件。要启用 WebGL 支持，则需要
"bokeh-gl"文件。要启用 MathJax 支持，则需要
"bokeh-mathjax"文件。
例如，要使用版本 3.0.0 并支持小部件、表格和数学文本，请在您的 HTML 中包含以下内容
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-3.0.0.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.0.0.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.0.0.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.0.0.min.js"
crossorigin="anonymous"></script>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-3.0.0.min.js"
crossorigin="anonymous"></script>
注意
始终提供结束标记 </script>。这是所有浏览器都要求的，并且没有它页面通常不会呈现。您还应始终在 script 标记上包含 crossorigin="anonymous" 属性。
如果您想通过设置 integrity 属性在显式脚本标记中包含 子资源完整性 (SRI) 哈希，则可以通过调用 get_sri_hashes_for_version() 获取必要的哈希。这是一个示例
In [1]: import bokeh.resources
In [2]: bokeh.resources.get_sri_hashes_for_version("2.2.0")
Out[2]:
{'bokeh-2.2.0.js': 'TQAjsk2/lDn1NHjYoe8HIascd3/Cw4EWdk6GNtYXVVyAiUkbEZiuP7fEgbSwM37Y',
...
'bokeh-widgets-2.2.0.min.js': '2ltAd1cQhavmLeBEZXGgnna8fjbw+FjvDq9m2dig4+8KVS8JcYFUQaALvLT//qHE'}
这些是裸哈希，您必须用 sha384- 作为前缀才能使用。例如
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-2.2.0.min.js"
integrity="sha384-5Y+xuMRAbgBj/2WKUiL8yzV4fBFic1HJPo2hT3pq2IsEzbsJjj8kT2i0b1lZ7C2N"
crossorigin="anonymous"></script>
您只能为完整发布版本生成 SRI 哈希，而不能为开发构建或候选版本生成。
除了单个 Bokeh 模型（例如，绘图）之外，components() 函数还可以接受模型列表或元组，或者键和模型的字典。每个都返回一个元组，其中包含一个脚本和一个用于目标 <div> 元素的数据结构。
以下说明了不同的输入类型如何与输出相关联
components(plot)
#=> (script, plot_div)
components((plot_1, plot_2))
#=> (script, (plot_1_div, plot_2_div))
components({"Plot 1": plot_1, "Plot 2": plot_2})
#=> (script, {"Plot 1": plot_1_div, "Plot 2": plot_2_div})
这是一个示例，说明如何使用多绘图生成器
# scatter.py
from bokeh.plotting import figure
from bokeh.models import Range1d
from bokeh.embed import components
# create some data
x1 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
y1 = [0, 8, 2, 4, 6, 9, 5, 6, 25, 28, 4, 7]
x2 = [2, 5, 7, 15, 18, 19, 25, 28, 9, 10, 4]
y2 = [2, 4, 6, 9, 15, 18, 0, 8, 2, 25, 28]
x3 = [0, 1, 0, 8, 2, 4, 6, 9, 7, 8, 9]
y3 = [0, 8, 4, 6, 9, 15, 18, 19, 19, 25, 28]
# select the tools you want
TOOLS="pan,wheel_zoom,box_zoom,reset,save"
# the red and blue graphs share this data range
xr1 = Range1d(start=0, end=30)
yr1 = Range1d(start=0, end=30)
# only the green graph uses this data range
xr2 = Range1d(start=0, end=30)
yr2 = Range1d(start=0, end=30)
# build the figures
p1 = figure(x_range=xr1, y_range=yr1, tools=TOOLS, width=300, height=300)
p1.scatter(x1, y1, size=12, color="red", alpha=0.5)
p2 = figure(x_range=xr1, y_range=yr1, tools=TOOLS, width=300, height=300)
p2.scatter(x2, y2, size=12, color="blue", alpha=0.5)
p3 = figure(x_range=xr2, y_range=yr2, tools=TOOLS, width=300, height=300)
p3.scatter(x3, y3, size=12, color="green", alpha=0.5)
# plots can be a single Bokeh model, a list/tuple, or even a dictionary
plots = {'Red': p1, 'Blue': p2, 'Green': p3}
script, div = components(plots)
print(script)
print(div)
运行 python scatter.py 打印出以下内容
<script type="text/javascript">
const docs_json = { DOCUMENT DATA HERE }
const render_items = [{
"docid":"33961aa6-fd96-4055-886f-b2afec7ff193",
"elementid":"e89297cf-a2dc-4edd-8993-e16f0ca6af04",
"modelid":"4eff3fdb-80f4-4b4c-a592-f99911e14398"
},{
"docid":"33961aa6-fd96-4055-886f-b2afec7ff193",
"elementid":"eeb9a417-02a1-47e3-ab82-221abe8a1644",
"modelid":"0e5ccbaf-62af-42cc-98de-7c597d83747a"
},{
"docid":"33961aa6-fd96-4055-886f-b2afec7ff193",
"elementid":"c311f123-368f-43ba-88b6-4e3ecd9aed94",
"modelid":"57f18497-9598-4c70-a251-6072baf223ff"
}];
Bokeh.embed.embed_items(docs_json, render_items);
</script>
{
'Green': '\n<div id="e89297cf-a2dc-4edd-8993-e16f0ca6af04"></div>',
'Blue': '\n<div id="eeb9a417-02a1-47e3-ab82-221abe8a1644"></div>',
'Red': '\n<div id="c311f123-368f-43ba-88b6-4e3ecd9aed94"></div>'
}
然后，您可以将生成的脚本和 <div> 元素插入到如下所示的样板文件中
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Bokeh Scatter Plots</title>
<script src="https://cdn.bokeh.org/bokeh/release/bokeh-2.2.0.min.js"></script>
<!-- COPY/PASTE SCRIPT HERE -->
</head>
<body>
<!-- INSERT DIVS HERE -->
</body>
</html>
请注意，这不包括 "-widgets" 的 JavaScript 和 CSS 文件，因为文档未使用任何 Bokeh 小部件。
您可以通过执行以下操作查看多绘图生成的示例
python /bokeh/examples/embed/embed_multiple.py
自动加载脚本#
您还可以使用 autoload_static() 函数嵌入独立文档。此函数提供一个 <script> 标记，该标记会用 Bokeh 绘图替换自身。此脚本还会检查 BokehJS 并在必要时加载它。此函数允许您仅使用此 <script> 标记嵌入绘图。
此函数接受您要显示的 Bokeh 模型（例如，绘图）、Resources 对象和要从中加载脚本的路径。然后 autoload_static() 返回一个自包含的 <script> 标记和一个 JavaScript 代码块。JavaScript 代码保存到您提供的路径，并且 <script> 加载并运行它以在网页上显示您的绘图。
以下是如何将 autoload_static() 与简单绘图一起使用
from bokeh.resources import CDN
from bokeh.plotting import figure
from bokeh.embed import autoload_static
plot = figure()
plot.scatter([1,2], [3,4])
js, tag = autoload_static(plot, CDN, "some/path")
生成的 <script> 标记如下所示
<script
src="some/path"
id="c5339dfd-a354-4e09-bba4-466f58a574f1"
async="true"
data-bokeh-modelid="7b226555-8e16-4c29-ba2a-df2d308588dc"
data-bokeh-loglevel="info"
></script>
将此标记包含在您希望绘图显示在 HTML 页面上的任何位置。
将 JavaScript 代码保存到文档包含绘图的服务器上的 “some/path” 文件中。
注意
<script> 标记会用 <div> 替换自身，因此必须将其放置在文档的 <body> 中。
Bokeh 应用程序#
本节介绍如何嵌入整个 Bokeh 服务器应用程序。您可以嵌入 Bokeh 应用程序，以便每次页面加载都会创建并显示新会话和文档，或输出特定的现有会话。
应用程序文档#
如果应用程序在 Bokeh 服务器上运行，使其在某个 URL 上可用，您通常希望将整个应用程序嵌入到网页中。这样，每次页面加载时，页面都会创建一个新会话并将其显示给用户。
您可以使用 server_document() 函数实现此目的。此函数接受 Bokeh 服务器应用程序的 URL，并返回一个脚本，该脚本在每次脚本执行时从该服务器嵌入一个新会话。
以下是 server_document() 函数的使用示例
from bokeh.embed import server_document
script = server_document("https://demo.bokeh.org/sliders")
这将返回一个 <script> 标记，如下所示
<script
src="https://demo.bokeh.org/sliders/autoload.js?bokeh-autoload-element=1000&bokeh-app-path=/sliders&bokeh-absolute-url=https://demo.bokeh.org/sliders"
id="1000">
</script>
您可以将此标记添加到 HTML 页面，以在该点包含 Bokeh 应用程序。
应用程序会话#
有时，您可能希望加载特定会话，而不是加载新会话。
以 Flask 应用程序为例，它为经过身份验证的用户呈现页面。您可能希望它拉取一个新会话，为该特定用户进行一些自定义，并提供此自定义的 Bokeh 服务器会话。
您可以使用 server_session() 函数完成此操作。此函数接受要嵌入的特定模型（或 None 用于整个会话文档）、会话 ID 和 Bokeh 应用程序的 URL。
以下是如何将 server_session() 与 Flask 一起使用的示例
from flask import Flask, render_template
from bokeh.client import pull_session
from bokeh.embed import server_session
app = Flask(__name__)
@app.route('/', methods=['GET'])
def bkapp_page():
# pull a new session from a running Bokeh server
with pull_session(url="https://127.0.0.1:5006/sliders") as session:
# update or customize that session
session.document.roots[0].children[1].title.text = "Special sliders for a specific user!"
# generate a script to load the customized session
script = server_session(session_id=session.id, url='https://127.0.0.1:5006/sliders')
# use the script in the rendered page
return render_template("embed.html", script=script, template="Flask")
if __name__ == '__main__':
app.run(port=8080)
标准模板#
Bokeh 还提供了一个标准的 Jinja 模板，通过扩展“base”模板，可以帮助您快速灵活地嵌入不同的文档根目录。当您需要在非 Bokeh 布局（例如 Bootstrap）中嵌入 Bokeh 应用程序的各个组件时，这尤其有用。
这是一个最小的应用程序示例，该应用程序创建了两个设置了名称属性的根目录
p1 = figure(..., name="scatter")
p2 = figure(..., name="line")
curdoc().add_root(p1)
curdoc().add_root(p2)
然后，您可以使用名称引用这些根目录，并将它们传递给 embed 宏以将它们放置在模板的任何部分
{% extends base %}
<!-- goes in head -->
{% block preamble %}
<link href="app/static/css/custom.min.css" rel="stylesheet">
{% endblock %}
<!-- goes in body -->
{% block contents %}
<div> {{ embed(roots.scatter) }} </div>
<div> {{ embed(roots.line) }} </div>
{% endblock %}
这是一个包含您可以覆盖的所有部分的完整模板
<!DOCTYPE html>
<html lang="en">
{% block head %}
<head>
{% block inner_head %}
<meta charset="utf-8">
<title>{% block title %}{{ title | e if title else "Bokeh Plot" }}{% endblock %}</title>
{% block preamble -%}{%- endblock %}
{% block resources -%}
{% block css_resources -%}
{{- bokeh_css if bokeh_css }}
{%- endblock css_resources %}
{% block js_resources -%}
{{ bokeh_js if bokeh_js }}
{%- endblock js_resources %}
{% endblock resources %}
{% block postamble %}{% endblock %}
{% endblock inner_head %}
</head>
{% endblock head%}
{% block body %}
<body>
{% block inner_body %}
{% block contents %}
{% for doc in docs %}
{{ embed(doc) if doc.elementid }}
{%- for root in doc.roots %}
{% block root scoped %}
{{ embed(root) }}
{% endblock %}
{% endfor %}
{% endfor %}
{% endblock contents %}
{{ plot_script | indent(4) }}
{% endblock inner_body %}
</body>
{% endblock body%}
</html>