Plotly.py 在线 Dashboard API 使用指南：用 Python 程序化创建、定制与发布云端仪表盘（Legacy）

Plotly.py 在线 Dashboard API 使用指南用 Python 程序化创建、定制与发布云端仪表盘Legacy【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py本指南基于当前仓库 doc/unconverted/python/create-online-dashboard-legacy.md 整理系统讲解 Plotly.py 早期版本2.0.5中通过plotly.dashboard_objs与plotly.plotly.dashboard_ops程序化创建、布局、定制并上传在线 Dashboard 的完整流程。读者将掌握 Dashboard 对象初始化、三类 boxplot/text/webpage的定义与插入、insert/get_box/swap/remove布局操作、布局尺寸控制、样式与标题设置以及上传和检索云端仪表盘的完整实战方法。同时结合当前仓库 CHANGELOG.md 与 doc/python/v4-migration.md 说明该 API 的版本演进与迁移现状帮助读者正确判断其适用环境。重要提示本指南对应的是 Plotly.py 的 Legacy遗留功能。Dashboard API 于 2.0.5 引入见 CHANGELOG.md随后在 4.0.0 版本中在线相关的plotly.plotly、plotly.dashboard_objs等模块被移出核心包迁移至独立的chart-studio发行包见 CHANGELOG.md 与 v4-migration.md。当前仓库的plotly包为离线优先架构见 plotly/init.py不再包含dashboard_objs。因此本文所有代码示例适用于安装了plotly 2.0.5~3.x并配合 Chart Studio 云服务或私有化 Plotly 服务器的历史环境若使用 v4需安装chart-studio并将plotly.dashboard_objs替换为chart_studio.dashboard_objs。一、背景什么是 Plotly 在线 DashboardDashboard仪表盘是按特定布局组织起来的一组图表plots与图片images的集合。在 Plotly 生态中创建 Dashboard 有两条路径在线创建器Online Creator在 Plotly 网页端手动拖拽布局Python API 程序化创建完全通过代码构建 Dashboard 对象上传到 Plotly 服务器后与已有仪表盘并列存放也可以从服务器检索已有仪表盘。在 Plotly 的 Dashboard 中可以包含三类内容图表plots、文本text与网页webpages。Dashboard 存储在 Plotly 账户空间中可通过账户的 organize 页面管理。Dashboard 的 API 自版本2.0.5起可用。按 CHANGELOG.md 的记录2.0.2/2.0.3 中曾因dashboard_objs未包含进setup.py的packages列表导致import plotly失败2.0.5 之后该模块才正式纳入顶层导入并可正常使用。使用前请升级pip install plotly --upgrade然后确认版本号import plotly plotly.__version__Dashboard 的隐私级别与单个plot可以设置为public、private或secret一样Dashboard 也可以独立设置这三种隐私级别并且与其内部图表plots的隐私设置相互独立。这意味着如果你将某个 Dashboard 分享给他人但其中一张或多张图表被设置为private那么对接收方而言这些图表将不会显示。因此在设计分享型 Dashboard 时需要同时检查 Dashboard 整体与内部每张图表的隐私设置。二、初始化 Dashboard 对象使用plotly.dashboard_objs模块创建 Dashboard 对象并在 Jupyter Notebook 中通过.get_preview()预览其 HTML 布局。import plotly.dashboard_objs as dashboard import IPython.display from IPython.display import Image my_dboard dashboard.Dashboard() my_dboard.get_preview().get_preview()会返回 Dashboard 组织的 HTML 表示——即仪表盘中各个元素box彼此之间的相对位置关系。每次修改 Dashboard 后都应运行该方法检查布局效果。重要提示由于.get_preview()的工作方式在一个 Jupyter Notebook 中只有运行该方法的那个单元格能够显示 Dashboard 预览。推荐的实践是固定预留一个单元格专用于执行my_dboard.get_preview()每次改动布局后运行它来刷新 HTML 表示。本文为清晰起见会在每次修改后展示对应的预览结果。三、选择并上传图表Choose Plots要把图表放进 Dashboard需要先在 Plotly 服务器上发布图表。可以在 Jupyter 中即时创建图表也可以直接复用已发布图表的 URL。3.1 创建一个普通图表并获取 URLimport plotly.graph_objs as go import plotly.plotly as py import numpy as np colorscale [[0, #FAEE1C], [0.33, #F3558E], [0.66, #9C1DE7], [1, #581B98]] trace1 go.Scatter( y np.random.randn(500), modemarkers, markerdict( size16, color np.random.randn(500), colorscalecolorscale, showscaleTrue ) ) data [trace1] url_1 py.plot(data, filenamescatter-for-dashboard, auto_openFalse) py.iplot(data, filenamescatter-for-dashboard)这里的关键是py.plot(data, filename..., auto_openFalse)会返回图表的 URL默认公开后续 Dashboard 的 box 就通过这个 URL 关联图表。3.2 创建带 secret key 的图表import plotly.plotly as py import plotly.graph_objs as go import numpy as np x0 np.random.randn(50) x1 np.random.randn(50) 2 x2 np.random.randn(50) 4 x3 np.random.randn(50) 6 colors [#FAEE1C, #F3558E, #9C1DE7, #581B98] trace0 go.Box(xx0, marker{color: colors[0]}) trace1 go.Box(xx1, marker{color: colors[1]}) trace2 go.Box(xx2, marker{color: colors[2]}) trace3 go.Box(xx3, marker{color: colors[3]}) data [trace0, trace1, trace2, trace3] url_2 py.plot(data, filenamebox-plots-for-dashboard, sharingsecret, auto_openFalse) py.iplot(data, filenamebox-plots-for-dashboard)sharingsecret会生成带share_key的私密链接url_2中会携带该密钥供后续在 Dashboard 中引用。url_2注意py.plot()返回的 URL 可直接赋给变量供 Dashboard 后续使用如 3.2 所示secret图表的 URL 中会包含share_key参数需要特殊处理才能放进 Dashboard。四、Box 概念把内容放进 Dashboard 的基本单元要把图表、文本框或网页放进 Dashboard必须先将它放入一个box本质上是一个字典再通过insert插入 Dashboard。本文示例会插入一个图表、一个文本框和一个 secret 图表。4.1 三种 box 字典结构图表 boxplot box{ type: box, boxType: plot, fileId: , shareKey: None, title: }fileId必填格式为username:number例如PlotBot:1300可以从图表上传到 Plotly 服务器后的 URL 中解析得到shareKey可选当图表是 secret 时提供其 sharekeytitle可选设置该 box 的标题。文本 boxtext box{ type: box, boxType: text, text: , title: }text要在 box 中显示的文本内容title可选设置该 box 的标题。网页 boxwebpage box{ type: box, boxType: webpage, url: , title: }url要嵌入网页的 URL例如https://en.wikipedia.org/wiki/Main_Pagetitle可选设置该 box 的标题。4.2 从 URL 提取 fileId 与 sharekey为了把已上传图表放进 Dashboard需要先从图表 URL 中解析出fileId形如username:number。若图表为 secret还需解析出 sharekey。可以复用下面的两个辅助函数import re def fileId_from_url(url): Return fileId from a url. raw_fileId re.findall(~[A-z]/[0-9], url)[0][1: ] return raw_fileId.replace(/, :) def sharekey_from_url(url): Return the sharekey from a url. if share_key not in url: return This url is not sercret. It does not have a secret key. return url[url.find(share_key) len(share_key):]fileId_from_url用正则匹配 URL 中~username/number形态的片段去掉~并把/替换为:得到username:number格式的 fileIdsharekey_from_url若 URL 含share_key则返回其后的密钥值否则返回提示信息注意原文档中的提示字符串存在拼写笔误 sercret此处保留原样以便与历史行为一致。4.3 组装三个 box 并插入 DashboardfileId_1 fileId_from_url(url_1) fileId_2 fileId_from_url(url_2) box_a { type: box, boxType: plot, fileId: fileId_1, title: scatter-for-dashboard } text_for_box ## Distributions: #### Scatter Plot 1. Ranging 0 - 500 2. Even distribution #### Box Plot 1. Similar Range 2. Outliers present in trace 1 and trace 3 You can view more markdown tips [here](https://daringfireball.net/projects/markdown/syntax). box_b { type: box, boxType: text, text: text_for_box, title: Markdown Options for Text Box } box_c { type: box, boxType: plot, fileId: fileId_2, title: box-for-dashboard, shareKey: sharekey_from_url(url_2) } my_dboard.insert(box_c)文本 box 的内容支持 Markdown 语法示例中使用了标题、有序列表等标记可以直接在 Dashboard 中渲染为富文本。my_dboard.get_preview()将 secret 图表插入后运行my_dboard.insert(box_a, above, 1)把普通散点图插入到 1 号区域的上方my_dboard.insert(box_a, above, 1)五、布局操作insert 的位置、方向与自定义尺寸5.1 insert 的定位方式Dashboard.insert(box, side, box_id)的定位逻辑是以box_id指定的现有区域为参照向side方向如above、left、below插入新 box。每次插入都会把被引用的容器区域按插入方向均分为两部分。my_dboard.insert(box_b, left, 1)上述代码将文本 box 插入到 1 号区域左侧。5.2 用 fill_percent 控制占比默认情况下新 box 插入后会把被引用的 box等分为两半。通过fill_percent参数可以手动控制新 box 占原容器 box 的比例取值表示新 box 从指定方向占据容器百分比my_dboard.insert(box_b, left, 1, fill_percent30)即文本 box 插入到 1 号区域左侧且只占该容器 30% 的宽度其余 70% 留给原区域。该参数由 Dashboard API 引入见 CHANGELOG.md 中 “New parameterfill_percentto the.insertmethod for the dashboards API” 的记录更完整的参数说明可运行help(dashboard.Dashboard.insert)查看。5.3 连续堆叠插入可以用循环连续向同一位置堆叠插入多个 boxstacked_dboard dashboard.Dashboard() text_box { type: box, boxType: text, text: empty space } for _ in range(5): stacked_dboard.insert(text_box, below, 1) # stacked_dboard.get_preview()这段代码会在 1 号区域下方连续堆叠 5 个文本 box。若堆叠后出现大量小尺寸 box可能会难以在在线创建器中用鼠标调整大小解决办法是先通过 API 放大整个布局见第八节。六、查询与修改 boxget_box每次运行my_dboard.get_preview()都会返回一个布局图其中每个矩形区域中央标注一个数字。这些数字即box ids本质上是每次运行.get_preview()时临时分配的查找键可能随布局变化而改变——因此修改前务必重新运行预览获取最新 id。box 本身只是描述其内容的字典。例如想查看布局中区域1将显示什么图表运行my_dboard.get_box(1)返回该区域的 box 字典后可以直接修改字典中的值来更新该 box例如修改图表标题my_dboard.get_box(1)[title] a new title my_dboard.get_box(1)七、交换与移除 boxswap / remove7.1 swap 交换两个 box若想交换 Dashboard 中两个已放置 box 的位置先运行my_dboard.get_preview()查看当前布局然后挑选两个互不相同的 box ids 进行交换my_dboard.get_box(3)[title]my_dboard.swap(2, 3) my_dboard.get_box(3)[title]swap(2, 3)会交换 2 号与 3 号区域存储的内容交换后再次通过get_box(3)[title]即可验证内容是否互换。7.2 remove 移除 box先通过my_dboard.get_preview()确定目标 box id再用remove删除。以下示例先在 2 号区域下方插入box_a然后移除 3 号区域my_dboard.insert(box_a, below, 2)my_dboard.remove(3)移除后布局即恢复为插入前的状态。八、Dashboard 设置settings与布局尺寸定制Dashboard 对象支持以字典式键访问的方式设置标题、Logo、链接、配色、字体等外观属性并可通过[layout][size]控制整体布局尺寸。8.1 设置标题my_dboard[settings][title] My First Dashboard with Python8.2 添加 Logo在 Dashboard 左上角添加 Logomy_dboard[settings][logoUrl] https://images.plot.ly/language-icons/api-home/python-logo.png8.3 添加页头链接向 Dashboard 页头添加若干链接每个链接为包含title与url的字典my_dboard[settings][links] [] my_dboard[settings][links].append({title: Link to Plotly, url: https://plot.ly/}) my_dboard[settings][links].append({title: Link to Python Website, url: https://www.python.org/})8.4 配色设置以下设置项控制 Dashboard 的前景、背景、页头与 box 配色my_dboard[settings][foregroundColor] #000000 my_dboard[settings][backgroundColor] #adcaea my_dboard[settings][headerForegroundColor] #ffffff my_dboard[settings][headerBackgroundColor] #D232C8 my_dboard[settings][boxBackgroundColor] #ffffff my_dboard[settings][boxBorderColor] #000000 my_dboard[settings][boxHeaderBackgroundColor] #ffffff各键含义设置键作用foregroundColor前景文字颜色backgroundColorDashboard 整体背景色headerForegroundColor页头前景文字颜色headerBackgroundColor页头背景色boxBackgroundColorbox 背景色boxBorderColorbox 边框颜色boxHeaderBackgroundColorbox 页头背景色8.5 字体设置my_dboard[settings][fontFamily] Raleway my_dboard[settings][headerFontSize] 1.6em my_dboard[settings][headerFontWeight] 200在线 Dashboard 创建器Online Creator中可用的其他设置项在 Dashboard API 中同样可用均通过my_dboard[settings][...]访问。8.6 更新 Dashboard 尺寸当布局因多次堆叠而出现大量小 box、难以在在线创建器中缩放时先通过 API 整体放大布局stacked_dboard[layout][size] 3000[layout][size]是 Dashboard 布局的尺寸属性增大该值可让每个 box 获得更大的像素空间从而便于后续在网页端微调。九、上传与检索 Dashboard9.1 上传到 Plotly 云端使用py.dashboard_ops.upload()将 Dashboard 上传到 Plotly 云账户import plotly.plotly as py py.dashboard_ops.upload(my_dboard, My First Dashboard with Python)上传成功后Dashboard 会出现在账户的 organize 页面中可像其他内容一样被分享或嵌入。9.2 检索已有 Dashboard可以从 Plotly 云端检索自己的任意 Dashboardpy.dashboard_ops.get_dashboard_names()列出当前账户在云端文件中的所有 Dashboard 名称py.dashboard_ops.get_dashboard(name)按名称取回 Dashboard构造出一个Dashboard()对象。py.dashboard_ops.get_dashboard_names()recent_dboard py.dashboard_ops.get_dashboard(My First Dashboard with Python)取回后即可对recent_dboard执行与本地对象相同的所有操作get_preview()、insert、swap、remove、修改 settings 等修改后再次upload即可更新云端版本。十、API 参考与版本现状10.1 查看完整 API在 Notebook 中运行help(py.dashboard_ops)可查看上传、检索 Dashboard 相关函数的完整签名与参数说明help(dashboard.Dashboard.insert)可查看insert与fill_percent的详细用法。10.2 版本演进与迁移现状以仓库证据为准根据当前仓库记录该 API 的演进路径如下2.0.3/2.0.4dashboard_objs曾因未包含在setup.py的packages中导致import plotly损坏CHANGELOG.md2.0.5dashboard_objs纳入顶层导入Dashboard 可创建并上传CHANGELOG.md后续版本为.insert方法新增fill_percent参数CHANGELOG.md4.0.02019-07-16在线功能整体移出核心包——plotly.plotly、plotly.api、plotly.dashboard_objs、plotly.grid_objs、plotly.presentation_objs全部迁移到独立的chart-studio发行包顶层模块改为chart_studioCHANGELOG.mdv4 迁移指南明确要求安装pip install chart-studio后将plotly.dashboard_objs替换为chart_studio.dashboard_objsdoc/python/v4-migration.md。也就是说在当前仓库所代表的现代 plotly.pyv4/v5/v6离线优先架构见 plotly/init.py中plotly.dashboard_objs与plotly.plotly均不再存在若需要在现代环境中复现本文示例请安装chart-studio并把所有plotly.plotly改为chart_studio.plotly、plotly.dashboard_objs改为chart_studio.dashboard_objs同时将plotly.graph_objs相应替换为plotly.graph_objects。此外v4 起chart_studio.plotly.plot的fileopt参数已被移除同名图表会被直接覆盖无法再就地追加修改CHANGELOG.md。十一、实战建议与注意事项先上传图表、再引用 URL所有放进 Dashboard 的图表都必须先通过py.plot()发布并拿到 URL再用fileId_from_url解析 fileIdsecret 图表还需用sharekey_from_url提取 sharekey。预览是布局调试的唯一手段box ids 是每次.get_preview()临时分配的所有insert/swap/remove操作前都应先运行预览确认当前 id。隐私独立Dashboard 的隐私级别与内部图表的隐私级别相互独立分享前务必确认两者都满足要求否则private图表对接收方不可见。Markdown 文本文本 box 支持 Markdown 语法可用来组织说明、列表、标题等富文本内容。尺寸问题频繁堆叠插入会导致 box 过小难以在网页端调整优先通过[layout][size]放大布局。环境匹配本 API 为 Legacy 在线功能示例代码仅在安装plotly 2.0.5~3.x或chart-studio且具备 Plotly 云服务凭据的环境中可运行现代离线开发应使用plotly.graph_objects与plotly.io渲染框架。通过本文的完整流程你可以完全用 Python 代码构建一个包含图表、文本与网页的多区域 Dashboard定制其标题、Logo、链接、配色与字体上传到 Plotly 云端共享并在需要时按名称检索回本地继续编辑——这是 Plotly.py 早期版本中“程序化构建在线仪表盘”的完整实践路径。【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考