Plotly Dash多页面仪表盘的构建框架

原创于 2025-12-16 06:07:10 发布 · 518 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#plotly #dash #数据可视化 #Plotly Dash #仪表盘开发 #程序那些事 #AIGC

Plotly Dash — 一个适用于多页面仪表盘的结构化框架

多页面仪表盘的精确输出（暗色模式）显示了项目结构的特性 – 图片由作者提供 – 数据来自 GAPMINDER.ORG，CC-BY 许可证

Plotly Dash 是一个广受认可和使用的框架，可用于创建交互式仪表盘，便于以易于消化且美观的格式呈现各种数据和信息。
通常，关于如何创建 Dash 应用的示例和指南都将所有代码放在一个 Python 文件中。虽然这是一种简洁的入门方式，但即使是简单的仪表盘，当所有代码都在单个文件中时，管理起来也会变得异常困难。
本文介绍了一个合理且功能齐全的多文件项目结构，包含了开始所需的所有要素。即使项目规模相当庞大，管理和扩展项目也会变得容易得多。

引言

许多在线 Dash 仪表盘示例都是以单个文件呈现的，虽然这对于小型简单仪表盘没问题，但随着项目规模增大并可能扩展为多个页面，管理就变得不可能了。
因此，有必要开始拆分单个文件，创建逻辑清晰的项目结构，以使项目管理更容易。
然而，关于如何构建结构化多页面应用，特别是针对 Dash 的指导非常少。似乎也没有标准的“官方”方式来构建 Dash 应用。
此外，任何多页面应用的示例往往只提供一个极简的骨架结构，通常不包括任何图表示例（即它们不是功能齐全的）。这给实际运行应用并使其与要呈现的数据可靠地协同工作留下了一些猜测空间。
本文提供了一个功能齐全的基础框架，用户可以立即运行并进行实验。它也为开始开发项目提供了一个有用的参考点。
免责声明：我与 Plotly 没有任何关联。此外，本文共享的 GitHub 代码库以及文中的所有功能和示例都可以使用，无需任何付费功能或付费订阅。

目标

考虑到上述情况，本文主要关注与创建 Dash 仪表盘相关的四个要点：

多页面
逻辑化的项目结构（即不在单个文件中，采用多文件夹结构）
功能齐全，包括数据（API）和图表（Plotly）
支持 Git

详细功能

多页面仪表盘的精确输出（暗色模式）显示了项目结构的特性 – 图片由作者提供 – 数据来自 GAPMINDER.ORG，CC-BY 许可证

概述

除了上一节详细说明的主要目标外，还包括了以下功能，以提供一个可用、美观且功能齐全的基础：

一个侧边栏，列出可用页面，并在页面切换时高亮显示当前活动页面
带有网站名称、徽标和暗色/亮色主题切换开关的页眉
移动端就绪的响应式布局，带有可折叠侧边栏
暗色/亮色主题切换，包括 Plotly 图表的暗色/亮色主题
两种不同的 API 集成：一种是本地的（Plotly Gapminder），另一种是远程的，并包含 API 密钥处理逻辑（NinjasAPI）
Git 就绪，包含将 API 密钥排除在代码之外的逻辑，以及自动 DEBUG/生产模式切换（使用 python-dotenv）
使用 style.css 进行自定义样式设置的简单示例
利用 DASH Mantine Components 进行整体样式设置，提供一致的主题

以下小节将更详细地解释框架中包含的一些功能。
如果你在寻找代码，请跳到文章末尾，在那里你会找到 GitHub 仓库的链接以及如何开始的详细信息。

使用 DASH Mantine Components 进行样式设置

多页面仪表盘的精确输出（亮色模式）显示了项目结构的特性 – 图片由作者提供 – 数据来自 GAPMINDER.ORG，CC-BY 许可证

可以在没有前端框架帮助的情况下对 Dash 仪表盘进行样式设置。然而，一般来说，我认为优先级应该是快速有效地呈现数据，因此没有必要把事情弄得比需要的更困难。
因此，本文介绍的框架利用 Dash Mantine 组件进行样式设置，这是一个专为 Dash 仪表盘使用而设计的、广泛使用且现代化的样式 API：

以比以往更快的速度构建功能丰富、易于访问的 Dash 应用！Dash Mantine Components 包含超过 100 个可自定义的组件，基于 React Mantine 库，具有一致的样式、主题支持，并完全支持亮色和暗色模式。
– dash-mantine-components.com

特别是，为该项目结构选择的布局建立在以下官方布局示例之上：
AppShell with Theme Switch Component – GitHub
虽然官方布局的整体外观与本文使用的布局非常相似（正如你所期望的……），但官方布局没有构建任何功能，并且所有代码都在一个 Python 文件中。

暗色/亮色图表切换

上一节详细介绍的基础主题已经包含了在亮色和暗色主题之间切换的代码。
然而，一旦添加了非特定“Mantine”组件的组件（例如 plotly 图表），那么如果没有特定的集成，主题切换将无法对这些“其他”组件生效。
本文包含的框架包含了示例 plotly 图表，以及关联的代码来在暗色和亮色主题之间切换图表。
暗色/亮色切换的实现不需要重新加载图表中显示的数据，因此在切换时不会使任何数据 API 过载。

多页面

框架中包含的较复杂项目之一是它包含多个页面。
该实现使用最新的 Dash Pages 方法来实现这一点，这是在 Dash 2.5 中引入的。
虽然 Dash Pages 的实现相对简单，但当项目被构建成多个文件和文件夹时，它就变得更加复杂，因为可用的示例非常少。
希望这个框架能提供一个工作示例的参考。

Git 和开发就绪

来自 Unsplash 的 Yancy Min 的照片
由于这个框架旨在作为你自己项目的起点，因此假设会有一些开发工作，并且持续开发可能需要使用 Git。
以下小节详细介绍了此框架中一些有助于使此过程更轻松的功能。

环境变量

该框架利用 python-dotenv 来处理环境变量（有关实现细节，请参阅本文后面的“基本用法”部分）。
这本质上意味着某些变量可以保持在项目本地，但不出现在主代码库中。例如：

在生产环境和开发环境之间变化的变量
不应出现在公共仓库（例如 GitHub）中的变量

这允许将 API 密钥保密，并通过 GitHub 无缝推送到生产环境（如果你希望这样做）。

Git Ignore

包含了一个 .gitignore 文件，主要是为了防止虚拟环境以及重要的 .env 文件意外推送到 GitHub。
它还包含一些可能有所帮助的通用 Python 排除项。

生产服务器就绪

为了帮助将 Dash 应用部署到生产环境，包含了一个 wsgi.py 文件，这在将项目上线时应该会很有用。
上一节提到的 .env 文件也可用于在生产环境和开发环境之间无缝激活（或停用）DEBUG 模式。（有关实现细节，请参阅本文后面的“基本用法”部分）

API 集成

来自 Pixabay 的 zeeve platform 的图片
代码库中集成了两个数据 API。

Gapminder（默认）

第一个是 Gapminder API，它作为库包含在 Plotly 中。
这使得 API 在本地可用且快速，非常适合快速开发和测试。

API Ninjas

还包含代码作为如何集成外部 API 的示例。
在这种情况下，包含的外部 API 是 API Ninjas。如果你需要更真实的远程 API 测试（即，考虑/测试连接不良或丢失，或 API 错误），这应该基本上允许这样做。
API Ninjas 是一个商业 API，因此在超过某些使用级别后会产生订阅费用。然而，他们的免费层级是我发现的最慷慨的之一，非常适合开发测试。
要使用 API Ninjas API，你需要获取自己的 API 密钥（可以从他们的网站获取免费的有限使用 API 密钥）。然后需要将 API 密钥包含在 .env 文件中。最后，将 utils/consts.py 中的 EXTERNAL_API 标志设置为 True。
免责声明：我与 API Ninjas 没有任何关联，请随意使用你选择的外部 API（或完全不使用）！

CSS 样式设置

可以在项目中的 CSS 文件中包含特定的样式设置。该文件位于 assets/styles.css，包含以下代码：

.main-title {
    color: var(--mantine-color-gray-6);
}

[data-mantine-color-scheme="dark"] .main-title {
    color: var(--mantine-color-gray-3);
}

此示例只是将主标题颜色更改为灰色，但也考虑了在暗色和亮色主题之间切换时的颜色变化。
如果你熟悉 CSS，如果需要，可以从此文件进行广泛的样式更改。
有关如何处理 CSS 或 Javascript 等外部资源的更多详细信息，请参阅 Dash 文档。

重要编码注意事项

框架应用的第二个页面 – 图片由作者提供
Dash 在允许构建仪表盘/应用的方法上非常灵活，这使得事情简单易用。
然而，在构建这个框架的过程中，很明显当事情变得更加复杂时，需要遵循一些不成文的规则：

必须使用函数生成应用元素，而不是将其赋值给变量。

特别是，在处理具有文件和文件夹结构的多页面 Dash 应用时，必须使用函数生成应用元素，而不是将其赋值给变量。
例如，以本项目结构中使用的存档页面定义为例。
这是使用函数定义的存档页面：

import dash
from dash import html

dash.register_page(__name__)

def layout(**kwargs) -> html.Div:
    return html.Div(
        [
            html.H1("This is our Archive page"),
            html.Div("This is our Archive page content."),
        ]
    )

……这是使用变量定义的相同页面：

import dash
from dash import html

dash.register_page(__name__)

layout = html.Div(
        [
            html.H1("This is our Archive page"),
            html.Div("This is our Archive page content."),
        ]
    )

理论上它们都是有效的，并且都应该可以工作，正如官方文档所示。
通常，赋值给变量有时会起作用。然而，在某些情况下，在单独的文件/文件夹之间传递变量会失败。而使用函数则总是有效。
不幸的是，我记不起一个例子，但我亲身经历过这种情况，这就是为什么如果代码中的元素需要在文件/文件夹之间传递，本框架严格遵守使用函数的原因。
无论如何，使用函数可以说是一种更透明和可追溯的编码方式，从长远来看更有意义。

变量类型

你可能会注意到所有函数都包含了变量类型。
由于代码库是用 Python 编写的，这并非严格必要。希望这能帮助人们在阅读代码库并试图理解不同部分如何组合在一起时提高透明度。
如果你觉得它令人困惑或没有帮助，那么可以随时将其删除，而不会产生任何不良影响。
例如，将：

def get_graph(index: str) -> dmc.Skeleton:

改为：

def get_graph(index):

是完全没问题的。

代码仓库

你可以在本文讨论的 DASH 项目结构的 GitHub 页面上访问它 – 图片由作者提供
一个完整的工作示例 Dash 应用，使用本文介绍的结构，可在此处我的 GitHub 仓库中找到：
Plotly Dash Mulit-Page App
可以克隆该仓库并直接运行以了解其工作原理，或将其用作你自己项目的起点。

基本用法

来自 Unsplash 的 Eder Pozo Pérez 的照片
要运行仓库中的代码，请执行以下步骤。

创建虚拟环境并安装包

创建你的虚拟环境并激活它。你可以选择你喜欢的方式。例如：

cd project-folder 
python -m venv venv 
source venv/bin/activate

然后安装所需的包：

pip install --upgrade pip
pip install -r requirements.txt

创建“.env”文件

项目使用 python-dotenv 通过本地文件存储敏感数据，从而将 API 密钥等排除在项目代码之外。因此，你不会在仓库中找到此文件。你需要创建自己的文件。
在项目文件夹的根目录中创建一个名为：.env 的文件。作为文件中应包含内容的示例，以下是可在本地开发环境中使用的内容：

DEBUG = True 
NINJAS_API_KEY = "s0L889BwIkT2ThjHDROVGH==fkluRlLyGgfUUPgh"

注意：如果你想使用该特定 API，你必须从 NinjasAPI 获取一个合法的 API 密钥，但由于 Gapminder 本地 API 是默认的，因此运行应用不需要这样做。除了包含一个有效的 API 密钥以使用 NinjasAPI 外，你还必须在 utils/consts.py 中将 EXTERNAL_API 标志设置为 True。
在实时/生产环境中，你应该将 DEBUG 值更改为 False。
使用这种方法的好处是，能够使用 Git 在开发和生产环境之间更新代码，而无需每次更改 .env 文件中的 DEBUG 值。
这是因为 .env 文件不包含在 Git 仓库中，因此专门针对创建它的机器/服务器。

运行项目

要运行项目，只需在项目目录中执行以下行：

python main.py

然后你将被告知可以在浏览器中打开的本地 IP 地址以访问项目前端。

结论

希望本文以及相关的 GitHub 仓库能提供一个良好的起点，帮助你开始使用 Plotly Dash 创建自己的仪表盘，或者仅仅是了解如何进入下一个阶段。
如果你对代码有任何意见或改进建议，请随时评论本文，或在相关的 GitHub 仓库上提出问题 / 拉取请求。

参考文献

Plotly DASH
DASH Mantine Components
GAPMINDER.ORG, CC-BY LICENSE
更多精彩内容请关注我的个人公众号公众号（办公AI智能小助手）或者我的个人博客 https://blog.qife122.com/
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）