本文介绍如何在 Bokeh 生成的静态 HTML 中一次性初始化全局 JavaScript 对象（如 window.sharedData），供多个 UI 组件（如按钮）复用，避免重复序列化大数据导致 HTML 文件体积膨胀。
本文介绍如何在 bokeh 生成的静态 html 中一次性初始化全局 javascript 对象（如 `window.shareddata`），供多个 ui 组件（如按钮）复用，避免重复序列化大数据导致 html 文件体积膨胀。
在 Bokeh 中生成静态 HTML（即不依赖 Bokeh Server）时，Python 回调（如 curdoc().on_event(...)）完全不可用——因为页面加载后没有后台 Python 进程运行。此时所有交互逻辑必须通过纯 JavaScript 实现，而数据共享的关键在于利用浏览器全局作用域（window）进行一次初始化、多处复用。
✅ 正确做法：使用 curdoc().js_on_event('document_ready', ...) 初始化全局数据
document_ready 是 Bokeh 提供的 JS 端生命周期事件，等价于 DOM 加载完成（类似 jQuery 的 $(document).ready()），是执行一次性初始化代码的理想时机。以下为推荐实现模式：
from bokeh.models import Div, Button, CustomJS
from bokeh.layouts import column
from bokeh.plotting import show
from bokeh.io import curdoc
import json
# ✅ 假设你已构建好动态的复杂数据结构（例如按时间周期组织的 Candle 数据）
candle_data_and_sources = {
"1min": {
"candle_data": {"open": [100, 102], "high": [103, 104], "trigger_dt": ["2024-01-01", "2024-01-02"]},
"data_source": None # 占位，实际由 JS 动态赋值
},
"5min": {
"candle_data": {"open": [101, 103], "high": [104, 105], "trigger_dt": ["2024-01-01", "2024-01-02"]},
"data_source": None
}
}
# ? 关键：将 Python 数据结构 JSON 序列化为字符串，注入 JS 全局变量
init_js = CustomJS(code=f"""
console.log("Initializing shared data...");
window.sharedData = {json.dumps(candle_data_and_sources, separators=(',', ':'))};
window.sharedData.initialized = true;
console.log("Shared data ready:", Object.keys(window.sharedData));
""")
# 注册到 document_ready —— 仅在静态 HTML 中有效！
curdoc().js_on_event('document_ready', init_js)
# ✅ 复用全局数据的按钮（无需 args 传入大数据）
button1 = Button(label="Apply to All Timeframes", button_type="primary")
button1.js_on_click(CustomJS(code="""
if (!window.sharedData || !window.sharedData.initialized) {
console.warn("Shared data not ready!");
return;
}
console.log("Processing timeframes:", Object.keys(window.sharedData));
// 示例：遍历所有 timeframe 并打印第一个 open 值
for (const [tf, data] of Object.entries(window.sharedData)) {
if (data.candle_data && data.candle_data.open?.length > 0) {
console.log(`[${tf}] First open: ${data.candle_data.open[0]}`);
}
}
"""))
# 可添加任意数量同类按钮，均共享 window.sharedData
button2 = Button(label="Reset Data", button_type="warning")
button2.js_on_click(CustomJS(code="delete window.sharedData; console.log('Shared data cleared');"))
layout = column(button1, button2)
curdoc().add_root(layout)
show(layout)⚠️ 注意事项与最佳实践
-
避免
CustomJS的args传递大数据：args会将 Python 对象序列化为 JSON 并嵌入 HTML，对大型dict/DataFrame.to_dict()将显著增大文件体积；而window.sharedData仅初始化一次，后续所有 JS 回调直接访问内存对象。 -
JSON 序列化限制：确保待共享的数据可被
json.dumps()安全序列化（不支持datetime,numpy类型等）。建议提前转换为标准 Python 类型（如str,float,list,dict），或使用pandas.DataFrame.to_dict(orient="records")+json.dumps(..., default=str)。 -
安全性提示：
window.sharedData属于全局命名空间，生产环境建议封装为模块化对象（如window.MyApp = { data: ..., utils: {...} }），避免命名冲突。 -
调试技巧：在浏览器控制台中直接输入
window.sharedData查看结构，或添加console.log验证初始化时机。
✅ 总结
Bokeh 静态 HTML 的核心约束是“无服务端 Python”，因此数据共享必须转向前端机制。通过 curdoc().js_on_event('document_ready', init_code) 初始化 window.sharedData，既满足「一次生成、多处复用」的需求，又彻底规避了因重复序列化导致的 HTML 膨胀问题——尤其适用于动态生成按钮、未知数量时间周期、嵌套数据源等复杂场景。
