Plotly Dash 是一个强大的框架，能够帮助用户创建交互式仪表盘，以易于理解且美观的形式呈现各种数据和信息。
通常，关于如何创建 Dash 应用的示例和指南会将所有代码集中在一个 Python 文件中。虽然这对于入门来说是一种简洁明了的方式，但即使是简单的仪表盘，当所有代码都挤在一个文件中时，管理起来也会变得令人望而生畏。
本文将介绍一种合理且功能齐全的多文件项目结构，其中包含了开始构建 Dash 应用所需的所有核心要素。
通过采用这种结构，即使项目规模相当庞大，其管理和扩展也将变得更加轻松。
引言
许多在线的 Dash 仪表盘示例都以单文件形式呈现。尽管对于小型、简单的仪表盘来说这并无不妥，但随着项目规模的增长，尤其当需要支持多个页面时，这种方式将变得难以管理。
因此，将单一文件拆分成逻辑化的项目结构，以简化项目管理，便成为一项必要任务。
然而，针对如何构建一个结构化的多页 Dash 应用，特别是提供详细指导的资源却寥寥无几。目前似乎也没有一个“官方”或标准化的 Dash 应用结构。
此外，现有的多页应用示例往往只提供了一个骨架式的结构，通常不包含任何实际的图表功能（即它们并非完全可用）。这导致用户在实际运行应用并使其可靠地展示所需数据时，不得不进行大量的猜测和尝试。
本文旨在提供一个功能完整的基线项目，用户可以立即运行并进行实验。它也将成为一个有用的参考点，帮助用户从此开始开发自己的项目。
免责声明：本文与 Plotly 公司无任何关联。此外，文中分享的 GitHub 代码库以及本文所涵盖的所有功能和示例，均无需任何付费功能或订阅即可使用。
目标
基于上述背景，本文主要关注创建 Dash 仪表盘的四个关键方面：
- 支持多页面
- 拥有逻辑清晰的项目结构（即非单文件，采用多文件夹结构）
- 功能完整，包含数据（API）和图表（Plotly）
- 支持 Git 版本控制
详细功能
项目结构的功能展示（深色模式）—— 图片由作者提供 —— 数据源自 GAPMINDER.ORG，遵循 CC-BY 许可
功能概览
除了上一节中详述的主要目标之外，本框架还包含了以下功能，旨在提供一个可用、美观且功能丰富的基线项目：
- 一个侧边栏，列出所有可用页面，并在页面切换时高亮显示当前活动页面。
- 一个包含网站名称、Logo 和深浅主题切换功能的页眉。
- 支持移动设备的响应式布局，并带有可折叠的侧边栏。
- 深浅主题切换功能，包括 Plotly 图表的深浅主题适配。
- 两种不同的 API 集成：一个本地 API（Plotly Gapminder）和一个支持 API 密钥逻辑的远程 API（NinjasAPI）。
- 支持 Git 版本控制，包含将 API 密钥与代码分离的逻辑，以及自动切换 DEBUG/生产模式的功能（使用 python-dotenv）。
- 一个使用 style.css 进行定制化样式的简单示例。
- 利用 DASH Mantine Components 进行通用样式设计，提供一致的视觉主题。
以下子章节将更详细地解释框架中包含的一些功能。
使用 DASH Mantine Components 进行样式设计
项目结构的功能展示（浅色模式）—— 图片由作者提供 —— 数据源自 GAPMINDER.ORG，遵循 CC-BY 许可
虽然可以在不借助前端框架的情况下对 Dash 仪表盘进行样式设计，但通常情况下，项目的首要任务是快速有效地呈现数据。因此，没有必要让开发工作变得过于复杂。
有鉴于此，本文提出的框架采用了 Dash Mantine Components 进行样式设计。这是一个广泛使用且现代化的样式 API，专为 Dash 仪表盘而设计：
以前所未有的速度构建功能丰富、易于访问的 Dash 应用！Dash Mantine Components 包含了 100 多个基于 React Mantine 库的可定制组件，具有一致的样式、主题，并全面支持深色和浅色模式。
具体而言，本项目结构所选择的布局是基于以下官方布局示例进行构建的：
尽管官方布局的整体外观与本文使用的布局非常相似（这也在预期之中），但官方布局并未内置任何功能，并且所有代码都集中在一个 Python 文件中。本框架则在此基础上进行了功能性的扩展和结构上的优化。
深浅色图表切换
上一节中详细介绍的基础主题已经包含了在深浅主题之间切换的代码。
然而，一旦添加了不属于“Mantine”组件的元素（例如 Plotly 图表），那么如果没有进行特定的集成，主题切换功能将无法对这些“其他”组件生效。
本文框架包含了示例 Plotly 图表，以及将这些图表在深色和浅色主题之间切换的相关代码。
深浅色切换功能的实现无需重新加载图表中显示的数据，因此在切换时不会对任何数据 API 造成额外负担。
多页面支持
框架中包含的较为复杂的功能之一是其对多页面的支持。
该实现使用了 Dash 2.5 中引入的最新方法，即通过 Dash Pages 来实现多页面功能。
尽管 Dash Pages 的实现相对直接，但当项目被组织成多个文件和文件夹时，由于可用的示例非常少，其复杂性会显著增加。
希望本框架能为用户提供一个可行的多页应用示例，作为开发指导。
支持 Git 与开发就绪
由于本框架旨在作为用户项目开发的起点，因此假定将进行一些开发工作，并且持续的开发可能需要使用 Git。
以下小节详细介绍了本框架中一些有助于简化此过程的功能。
环境变量
本框架利用 python-dotenv 来处理环境变量（有关实现细节，请参阅本文后面“基本用法”一节）。
这本质上意味着某些变量可以保留在项目本地，但不会出现在主代码库中。例如：
- 在生产和开发环境之间变化的变量
- 不应出现在公共仓库（即 GitHub）中的变量
这使得 API 密钥得以保密，并支持通过 GitHub 无缝推送到生产环境（如果用户希望这样做）。
Git Ignore
项目中包含一个 .gitignore 文件，其主要目的是防止虚拟环境以及至关重要的 .env 文件被意外推送到 GitHub。
它还包含了一些通用的基于 Python 的排除规则，这些规则可能会有所帮助。
支持生产服务器部署
为了便于将 Dash 应用部署到生产环境，项目中包含了一个 wsgi.py 文件，当需要将项目上线时，该文件将非常有用。
上一节中提到的 .env 文件也可用于在生产和开发环境之间无缝激活（或停用）DEBUG 模式。（有关实现细节，请参阅本文后面“基本用法”一节）
API 集成
图片由 zeeve platform 在 Pixabay 上发布
代码库中集成了两个数据 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（或不使用任何外部 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):
这是完全可行的。
代码仓库
此 GitHub 页面提供了本文讨论的 DASH 项目结构代码库—— 图片由作者提供
一个使用本文所介绍结构、功能完善的 Dash 应用示例，可在 GitHub 仓库中找到：
用户可以克隆该仓库并直接运行，以了解其工作原理，或将其作为自己项目的起点。
基本用法
图片由 Eder Pozo Pérez 在 Unsplash 上发布
要运行仓库中的代码，请遵循以下步骤。
创建虚拟环境并安装依赖包
创建并激活虚拟环境。用户可以选择适合自己的方式进行操作。例如：
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"
注意：如果用户希望使用 NinjasAPI，需要从其官方渠道获取合法的 API 密钥。但由于 Gapminder 本地 API 是默认设置，因此运行应用并非必须使用 NinjasAPI。除了包含一个可用的 API 密钥以使用 NinjasAPI 外，用户还需要将 utils/consts.py 中的 EXTERNAL_API 标志设置为 True。
在生产/部署环境中，应将 DEBUG 值更改为 False。
这种方法的好处在于，可以在开发和生产环境之间使用 Git 更新代码，而无需每次都手动更改 .env 文件中的 DEBUG 值。
这是因为 .env 文件不包含在 Git 仓库中，因此它仅存在于创建它的机器/服务器上。
运行项目
要在项目目录中运行项目，只需执行以下命令：
python main.py
随后，系统将提示本地 IP 地址，用户可以在浏览器中打开该地址以访问项目前端界面。
总结
希望本文及其配套的 GitHub 仓库能为读者提供一个良好的起点，帮助其开启使用 Plotly Dash 创建仪表盘的旅程，或者至少为如何进入下一阶段提供一些思路。
