{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "(dash-pages)=\n", "# Dash Pages\n", "\n", "Dash Pages 从 Dash 版本 2.5.0 开始提供。它实现了简化创建多页面应用的功能，处理 URL 路由，并提供了一种简单的方法来组织和定义应用中的页面。\n", "\n", "使用 Dash Pages 创建多页面应用有三个基本步骤：\n", "\n", "1. 为您应用中的每个页面创建单独的 `.py` 文件，并将它们放在 `/pages` 目录中。\n", "2. 在这些页面文件中需要：\n", " - 添加 `dash.register_page(__name__)`，告诉 Dash 这是应用中的页面。\n", " - 在名为 `layout` 的变量中或名为 `layout` 的函数中定义页面的内容，该函数返回内容。\n", "3. 在您的主应用文件，`app.py` 中：\n", " - 在声明您的应用时，将 `use_pages` 设置为 `True`：`app = Dash(__name__, use_pages=True)`\n", " - 在您想要在用户访问应用的某个页面路径时显示页面内容的地方，添加 `dash.page_container` 到您的应用布局中。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 示例：使用 Pages 的简单多页面应用\n", "\n", "下面是使用 Dash Pages 的三页面应用结构的样子：\n", "\n", "```\n", "- app.py\n", "- pages\n", " |-- analytics.py\n", " |-- home.py\n", " |-- archive.py\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "它有主 `app.py` 文件，这是我们多页面应用的入口点（我们在其中包含 `dash.page_container`），并且在 `pages` 目录中有三页。\n", "\n", ":::::{tab-set}\n", "::::{tab-item} pages/analytics.py\n", "```{include} pages/analytics.py\n", ":code: python\n", "```\n", "::::\n", "::::{tab-item} pages/home.py\n", "```{include} pages/home.py\n", ":code: python\n", "```\n", "::::\n", "::::{tab-item} pages/archive.py\n", "```{include} pages/archive.py\n", ":code: python\n", "```\n", "::::\n", "::::{tab-item} app.py\n", "```{include} app.py\n", ":code: python\n", "```\n", "::::\n", ":::::" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "![](images/sample_pages_app_1.gif)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```{note}\n", "- `path` — 我们在应用的三个页面中的每一个上调用 `dash.register_page`。对于其中两个页面，我们没有设置 `path` 属性。如果您不设置 `path` 属性，它将根据模块名称自动生成。因此，当用户访问 `/archives` 时，会提供 `archives.py` 的布局。同样，当用户访问 `/analytics` 时，会提供 `analytics.py` 的布局。当我们为 `home.py` 调用 `dash.register_page` 时，我们确实设置了 `path` 属性。对于 `home.py`，我们设置 `path` 属性是因为我们不希望在用户访问 `/home` 时显示内容，而是在用户访问主页：`/` 时显示。\n", "- `page_registry` — 包含对 `dash.register_page` 的调用的页面会被添加到我们应用的页面注册表中。这是一个我们可以从中提取有关应用页面信息的 `OrderedDict`。在我们的 `app.py` 中，我们遍历应用的所有页面（在 `dash.page_registry.values()` 中）并为每一个添加链接。我们也可以从 `dash.page_registry` 中单独选择这些链接。路径为 `/` 的页面总是在字典中的索引 `0`。其他页面按字母顺序排列。\n", "- `page_container` — `app.py` 中有 `dash.page_container`。当用户导航到该页面的路径时，此处会显示页面内容。\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## layout" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "在上面的示例中，我们在每个页面中使用名为 `layout` 的变量定义布局。例如，在上面的 `home.py` 中：\n", "\n", "```python\n", "layout = html.Div([\n", " html.H1('This is our Home page'),\n", " html.Div('This is our Home page content.'),\n", "])\n", "```\n", "\n", "您也可以使用名为 `layout` 的函数来返回页面内容：\n", "\n", "```python\n", "def layout():\n", " return html.Div([\n", " html.H1('This is our Home page'),\n", " html.Div('This is our Home page content.'),\n", " ])\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```{note}\n", "页面布局必须使用名为 `layout` 的变量或函数来定义。在创建带有 Pages 的应用时，只在主 `app.py` 文件中使用 `app.layout`。\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## `dash.register_page`\n", "\n", "在文件中调用 [`dash.register_page`](https://dash.plotly.com/urls#reference-for-dash.register_page) 是 Dash 知道将该文件作为多页面应用中的页面包含的方式。\n", "\n", "正如我们所见，它可以仅使用模块名称进行调用：\n", "\n", "```python\n", "dash.register_page(__name__)\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "在这种情况下，Dash 会根据模块名称生成页面的路径、标题和链接名称。\n", "\n", "```{note}\n", "标题是 HTML 的 ``。名称是 Dash 注册表中该页面的键，创建页面链接时可以使用。路径是页面的 URL 路径名。\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "所以，如果我们有名为 `analytics.py` 的文件，页面的路径是 `/analytics`，标题是 `Analytics`，链接名称是 `Analytics`。\n", "\n", "如果我们不希望这些根据模块名称自动生成，我们也可以指定它们，就像我们在上面的示例中对 `home.py` 所做的那样。\n", "\n", "设置路径、标题和链接名称：\n", "\n", "`pages/analytics.py`：\n", "\n", "```python\n", "dash.register_page(\n", " __name__,\n", " path='/analytics-dashboard',\n", " title='Our Analytics Dashboard',\n", " name='Our Analytics Dashboard'\n", ")\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "任何调用 `dash.register_page` 的页面都会被添加到应用的页面注册表中。\n", "\n", "页面注册表是一个名为 `dash.page_registry` 的 `OrderedDict`。每个注册表条目都有页面的信息，包括在调用 `dash.register_page` 时设置的属性值，以及由 Dash 推断的值。与任何字典一样，您可以在代码中访问和使用其数据。\n", "\n", "在这里，我们访问我们的 `analytics` 的路径，并在 `app.py` 中的 `dcc.Link` 中使用它：\n", "\n", "```python\n", "html.Div(dcc.Link('Dashboard', href=dash.page_registry['pages.analytics']['path']))\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "要从 `pages/` 目录中的文件内访问 `dash.page_registry`，您需要在函数内部使用它。\n", "\n", "在这里，我们在 `pages` 目录中有两个文件：`side_bar.py` 和 `topic_1.py`。`topic_1` 页面从 `side_bar.py` 导入了一个侧边栏。注意 `side_bar.py` 内的函数是如何访问 `dash.page_registry` 的。如果不在函数内，应用将无法工作，因为在页面加载时 `dash.page_registry` 还没有准备好。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ":::::{tab-set}\n", "::::{tab-item} side_bar.py\n", "```{include} side_bar.py\n", ":code: python\n", "```\n", "::::\n", "::::{tab-item} topic_1.py\n", "```{include} topic_1.py\n", ":code: python\n", "```\n", "::::\n", ":::::" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Dash 页面注册表顺序\n", "默认情况下，路径定义为 `/` 的页面会以索引 `0` 添加到注册表中。然后根据文件名按字母顺序添加其他页面。\n", "\n", "您也可以通过在每个页面上设置 `order` 属性来指定 `dash.page_registry` 中页面的顺序：" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "`pages/analytics.py`\n", "\n", "```python\n", "dash.register_page(__name__, order=3)\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "如果您在一个或多个页面上设置了 `order` 属性，页面会按照以下顺序添加到注册表：\n", "\n", "1. 根据 `order` 属性指定的顺序。\n", "2. 在那之后，按照字母顺序（对于未设置 `order` 属性的页面）。\n", "\n", "设置 `order` 属性在您想要在动态创建侧边栏或页眉时能够循环遍历链接时很有用。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 默认和自定义 404\n", "\n", "如果用户访问的路径没有在应用的页面中声明，Pages 会向用户显示默认的 '404 - 页面未找到' 消息。\n", "\n", "这个页面可以被自定义。在您的应用的 `pages` 目录中放置一个名为 `not_found_404.py` 的文件，将 `dash.register_page(__name__)` 添加到文件中，并在 `layout` 变量或函数内定义自定义 404 的内容：" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```python\n", "import dash\n", "from dash import html\n", "\n", "dash.register_page(__name__)\n", "\n", "layout = html.H1(\"This is our custom 404 content\")\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 可变路径\n", "您可以通过使用 `path_template` 参数来捕获路径中的动态变量。通过将其放置在 `<variable_name>` 内来指定 URL 的动态部分。`variable_name` 将是传递给您的 `layout` 函数的命名关键字参数。`layout` 函数从 URL 接收的值始终是 `str` 类型。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### 单变量路径\n", "\n", "```python\n", "import dash\n", "from dash import html\n", "\n", "dash.register_page(__name__, path_template=\"/report/<report_id>\")\n", "\n", "\n", "def layout(report_id=None):\n", " return html.Div(\n", " f\"The user requested report ID: {report_id}.\"\n", " )\n", "```\n", "\n", "![](images/path_var_example.gif)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### 示例 - 两个路径变量以及更新标题和描述\n", "\n", "路径变量也可以用来更新页面的标题（您在浏览器标签中看到的）和页面的元描述（搜索引擎在索引和显示搜索结果时使用的信息，分享链接时也会在社交媒体上显示；否则不可见）。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```python\n", "import dash\n", "from dash import html\n", "\n", "\n", "def title(asset_id=None, dept_id=None):\n", " return f\"Asset Analysis: {asset_id} {dept_id}\"\n", "\n", "\n", "def description(asset_id=None, dept_id=None):\n", " return f\"This is the AVN Industries Asset Analysis: {asset_id} in {dept_id}\"\n", "\n", "\n", "dash.register_page(\n", " __name__,\n", " path_template=\"/asset/<asset_id>/department/hello-<dept_id>\",\n", " title=title,\n", " description=description,\n", ")\n", "\n", "\n", "def layout(asset_id=None, dept_id=None, **other_unknown_query_strings):\n", " return html.Div(\n", " f\"variables from pathname: asset_id: {asset_id} dept_id: {dept_id}\"\n", " )\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 查询字符串\n", "\n", "URL 中的查询字符串参数可以被 Pages 捕获。\n", "\n", "### 示例 - 单个查询字符串参数\n", "\n", "在这个示例中，当用户访问 `/archive?report_id=9` 时，值 `9` 被 `layout` 函数捕获并在页面上显示。`layout` 函数从 URL 接收的值始终是 `str` 类型。\n", "\n", "`pages/archive.py`:\n", "\n", "```python\n", "import dash\n", "from dash import html\n", "\n", "dash.register_page(__name__)\n", "\n", "\n", "def layout(report_id=None, **other_unknown_query_strings):\n", " return html.Div([\n", " html.H1('This is our Archive page'),\n", " html.Div(f'This is report: {report_id}.'),\n", " ])\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### 示例 - 两个查询字符串参数\n", "\n", "在这个示例中，当用户访问 `/archive?report_id=9&department_id=55` 时，值 `9` 和 `55` 被 `layout` 函数捕获并在页面上显示。\n", "\n", "`pages/archive.py`\n", "\n", "```python\n", "import dash\n", "from dash import html\n", "\n", "dash.register_page(__name__)\n", "\n", "\n", "def layout(report_id=None, department_id=None, **other_unknown_query_strings):\n", " return html.Div([\n", " html.H1('This is our Archive page'),\n", " html.Div(f'''\n", "\t This is report: {report_id}.\\n\n", "\t This is department: {department_id}.\n", "\t '''),\n", " ])\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 重定向\n", "如果您更改了页面的路径，最好定义一个重定向，以便访问旧链接的用户不会得到 '404 - 页面未找到'。您可以使用 `redirects` 参数设置其他路径直接指向一个页面。这需要一个包含所有重定向到该页面的路径的列表。\n", "\n", "在这里，我们有一个名为 `archive` 的页面。当用户访问 `/archive`、`/archive-2021` 或 `/archive-2020` 时会显示它。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```python\n", "import dash\n", "from dash import html\n", "\n", "dash.register_page(\n", " __name__,\n", " path=\"/archive\",\n", " redirect_from=[\"/archive-2021\", \"/archive-2020\"]\n", ")\n", "\n", "layout = html.Div([\n", " html.H1('This is our Archive page'),\n", " html.Div('This is our Archive page content.'),\n", "])\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 单个文件中的多页应用\n", "\n", "到目前为止，我们已经构建了多页面应用，其中我们在 `pages` 目录中为每个页面声明了单独的 `.py` 文件。也可以在 `app.py` 中声明多个页面。\n", "\n", "为此，我们在 `app.py` 中注册页面，并将布局直接传递给 `dash.register_page`。在这个示例中，我们在 `app.py` 文件中定义了两个页面：`home` 和 `analytics` 页面。对于 `module`，第一个参数，我们为每个页面分配一个唯一的名称（因为这些名称将作为 Dash 页面注册表中的键）。我们还在创建 Dash 应用实例时添加了 `pages_folder=\"\"`，以指定我们没有为应用的页面使用文件夹。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```python\n", "from dash import Dash, html, dcc\n", "import dash\n", "\n", "app = Dash(__name__, use_pages=True, pages_folder=\"\")\n", "\n", "dash.register_page(\"home\", path='/', layout=html.Div('Home Page'))\n", "dash.register_page(\"analytics\", layout=html.Div('Analytics'))\n", "\n", "app.layout = html.Div([\n", " html.Div([\n", " html.Div(\n", " dcc.Link(f\"{page['name']} - {page['path']}\", href=page[\"relative_path\"])\n", " ) for page in dash.page_registry.values()\n", " ]),\n", " dash.page_container,\n", "])\n", "\n", "if __name__ == '__main__':\n", " app.run(debug=True)\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 页面路由的额外输入\n", "\n", "这个特性在 Dash 2.14 中是新加的\n", "\n", "默认情况下，路由到不同页面是通过两个输入触发的：1. URL 路径名 2. URL 查询参数\n", "\n", "在某些情况下，您可能希望向页面布局函数传递更多信息，或者从其他输入触发布局渲染。例如，您可能想要：\n", "\n", "- 当用户更改语言下拉菜单时重新渲染整个页面内容\n", "- 在页面渲染时访问额外信息，而无需在每次值更新时重新渲染页面（例如，在 URL 哈希中序列化应用状态）\n", "\n", "您可以通过这种机制传递任何您想要的输入/状态，但这里有几件事情需要记住：\n", "- 这将在服务器端回调中使用，因此传递非常大量的数据可能会增加页面加载时间\n", "- 传递给页面的新输入/状态将被传递给每个页面。确保每个页面上都有输入组件可用，或者使用 ALL id 模式" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### 示例 1：更新页面的语言内容" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "![](images/routing_inputs_internationalized_app.gif)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ":::::{tab-set}\n", "::::{tab-item} app2.py\n", "```{include} app2.py\n", ":code: python\n", "```\n", "::::\n", "::::{tab-item} pages2/home.py\n", "```{include} pages2/home.py\n", ":code: python\n", "```\n", "::::\n", ":::::" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### 示例 2：在 URL 哈希中序列化应用状态" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "![](images/routing_inputs_serialized_state.gif)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ":::::{tab-set}\n", "::::{tab-item} app3.py\n", "```{include} app3.py\n", ":code: python\n", "```\n", "::::\n", "::::{tab-item} pages3/home.py\n", "```{include} pages3/home.py\n", ":code: python\n", "```\n", "::::\n", ":::::" ] } ], "metadata": { "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 2 }