迁移到新导航

Frappe Framework 第 16 版的后续版本改变了桌面（desk）的组织方式。不再是为每个工作区附加一个自由形式的侧边栏，现在每个模块都有一个侧边栏，每个应用在最左侧都有一个模块停靠栏（dock）。本页面面向正在升级现有站点的用户。它说明了升级会对你的桌面、工作区和侧边栏做什么，哪些内容保持不变，如何让用户切换到新导航，以及升级后需要检查什么。

升级不会删除任何内容，在你选择切换之前，用户不会被迁移到新导航。要了解新导航本身，请参阅“熟悉桌面导航”。

有哪些变化

升级前 升级后
主屏幕 一个桌面图标网格 应用屏幕，每个应用一个图标。在你切换之前，你的图标网格会作为后备保留
在区域之间移动 桌面图标和工作区侧边栏 每个应用一个模块停靠栏，位于侧边栏旁边
侧边栏 任意数量的侧边栏，每个都有自己的名称 每个模块一个侧边栏，由应用提供，你可以自定义
个人侧边栏副本 用户自己的侧边栏副本 该用户对模块侧边栏的仅为我排列
工作区 可以不属于任何模块 每个工作区都属于一个模块，由模块决定其侧边栏
为所有人更改导航 编辑共享的侧边栏记录 使用工作区管理员角色进行编辑侧边栏和管理停靠栏

升级前

  1. 进行备份。运行 bench --site <your-site> backup</your-site>（参见 bench 命令）。升级不会删除任何内容，但备份是让站点完全恢复原状的唯一方法。
  2. 一起更新所有应用。Frappe Framework、ERPNext、Frappe HR 以及任何其他应用都应处于匹配的版本，因为每个应用都会为新导航提供自己的侧边栏和停靠栏。
  3. 记录你的自定义侧边栏。截图或列出你的站点添加或编辑过的每个侧边栏的条目。某些站点更改尚未被迁移（参见已知问题），有一份列表可以让你快速重建它们。
  4. 决定由谁管理导航。升级后，只有拥有工作区管理员角色的用户才能为所有人更改侧边栏或停靠栏。系统管理员不会自动获得该角色。将其授予之前负责你侧边栏的人。参见用户和权限。
  5. 与你的应用开发者确认。如果你使用了自带侧边栏的自定义应用，请询问它是否有针对新导航的版本。参见“面向应用开发者”。

运行升级

像平常一样升级，使用 bench update 或切换分支并运行 bench migrate。导航没有单独的步骤：它会在站点迁移时被转换。

注意查看输出。它会告诉你转换了什么：

  • 侧边栏：已迁移 n 个模块，保留了 n 个个人排列。你的站点有多少侧边栏变成了模块侧边栏，以及保留了多少用户的个人副本。
  • 模块“名称”：已合并……当一个模块有多个侧边栏时，它们被合并为一个。每次合并都会被命名。
  • 仍以旧格式提供侧边栏的应用列表。在应用更新之前，这些应用的模块会使用生成的侧边栏。

升级会做什么

你的桌面暂时仍使用图标网格

新导航从应用屏幕上的应用开始，到停靠栏上每个应用的模块，再到每个模块的侧边栏。图标网格在这个层级中没有位置，但它被保留为后备，这样你的用户就不会在升级后的第二天早上发现一个不同的主屏幕。

如果你的站点使用桌面图标网格，升级后它会继续使用，每个图标及其排列都保持不变。请计划迁移到应用屏幕：网格即将退役，一旦大多数站点完成迁移，它将在未来的版本中被移除。全新的站点会从应用屏幕开始，永远不会有网格。

在模块内部，你的用户会立即看到新的停靠栏和侧边栏。

工作区被归入模块

现在每个工作区都属于一个模块，因为模块决定了它出现在哪个侧边栏中。已经有模块的工作区会保留它。对于其余的，升级不会猜测：

  • 属于某个用户的工作区会被归入私有，并且仍然对该用户显示；
  • 任何其他工作区会被归入自定义工作区。

把自定义工作区当作一份待办清单。打开管理工作区，选择自定义工作区，然后将每个工作区移动到它所属的模块。参见“移动或共享工作区”。

您旧的侧边栏会被复制到新的模块侧边栏中。原始侧边栏不会被更改或删除。

  • 由应用提供的侧边栏会被该应用为每个模块提供的新侧边栏替换。
  • 您站点创建或编辑的侧边栏会成为该模块的侧边栏（前提是该应用没有为该模块提供侧边栏）。如果一个模块有多个侧边栏，它们会合并为一个，输出结果会列出每次合并。无法用于网址的侧边栏名称（例如 Buying / Selling）会被自动调整。
  • 用户的个人副本会成为该用户对该模块侧边栏的“仅供我”安排。如果一个人在一个模块中有多个副本，它们会被合并。
  • “我的工作区”侧边栏不会被复制。私有工作区现在会单独显示，且仅对其所有者可见。
  • 指向已不存在内容的链接会按原样复制，因此单个失效链接不会阻止升级。之后可在编辑侧边栏中将其移除。

用户的个人侧边栏副本，会作为其自己的安排保留下来。

旧记录会保留，且为只读

旧的侧边栏记录会作为存档保留在站点上。不再有任何内容读取它们，尝试编辑其中一个时会显示一条消息，说明它是先前导航的存档。保留它们是为了在出现问题时可以重复转换。

指向 /desk/... 和 /app/... 页面的书签和链接仍然可以打开。地址现在还会包含您所在的模块，例如 /desk/selling/customer，并且旧地址在打开时会被更正为新形式。

切换到新导航

准备好后，将站点的主屏幕从后备图标网格移动到应用屏幕。不会丢失任何内容，并且在后备方案存在期间，如果您需要更多时间，可以返回它。

接受邀请

升级后，拥有系统管理员或工作区管理员角色的用户会在下次打开桌面时收到一次邀请，以试用新导航。

  • 试用会将整个站点切换到应用屏幕并重新加载页面。
  • 保留图标网格会让一切保持原样。

任一回答都会停止向站点上的所有人显示该邀请。两者都不会删除任何内容：图标和每个用户的安排都会保留，随时可供您切换回来。

移动到应用屏幕

无论您是否回答了邀请，您也可以随时自行切换：

  1. 在搜索栏中搜索桌面设置并打开它。
  2. 将桌面页面设置为应用。（桌面图标是后备网格。）
  3. 保存。

这会更改站点上所有人的主屏幕。

升级之后

迁移完成后，请逐项处理以下列表：

  1. 阅读迁移输出，并记录任何被合并的模块或被指出仍使用旧格式的应用。
  2. 以普通用户身份登录，而不是管理员，并检查他们的停靠栏是否列出了他们需要的模块，以及他们的侧边栏是否包含他们使用的内容。
  3. 清空自定义工作区。在管理工作区中，将其中的每个工作区移动到其真实模块。
  4. 重建未保留的内容。将您的侧边栏与升级前制作的列表进行比较。打开编辑侧边栏，选择面向所有人，然后添加回缺失的内容。请参阅自定义侧边栏。
  5. 为所有人安排停靠栏，如果您的用户需要不同的顺序。
  6. 授予工作区管理员角色给今后将负责导航的人员。

已知问题

这些是在升级一个完全自定义的测试站点时发现的，并且截至 2026 年 10 月仍未解决。请查看您版本的发行说明以了解修复情况。

  • 在应用提供侧边栏的模块中，站点更改不会被保留。如果您的站点在诸如销售、库存、制造或会计等模块中创建了自己的侧边栏，或编辑了其侧边栏，那么这些更改在升级后不会出现，因为该应用为该模块提供的新侧边栏会取代它们。个人副本不受影响，在没有应用提供侧边栏的模块中，站点侧边栏也不受影响。旧条目仍在存档中，因此修复后可以恢复它们。在此之前，请在面向所有人上使用编辑侧边栏重建它们。
  • 某些桌面图标被隐藏。在图标网格上，如果某个图标打开的侧边栏没有自己的工作区，它可能不再显示，因为它找不到要打开的模块侧边栏。切换到应用屏幕可以避免此问题。否则，请重新创建指向该模块工作区的图标。

撤销切换或升级

  • 若要暂时返回图标网格，请在桌面设置中将桌面页面设置为桌面图标。您的图标会与您离开时完全一致。请将其视为临时措施：该网格将在未来版本中移除。

  • 若要撤销整个升级，请恢复升级前所做的备份，以及应用的早期版本。这是唯一完整的回滚方式。

  • 若要重复侧边栏转换，例如在修复发布后，请让您的系统管理员运行：

    bench --site <your-site> execute frappe.patches.v16_0.convert_sidebars.execute
</your-site>

它会跳过任何已有侧边栏的模块，所以请先移除你想替换的模块侧边栏。

面向应用开发者

应用过去将侧边栏放在单个 workspace_sidebar 文件夹中。这些文件不再被读取。在应用更新之前，其模块会使用根据其内容生成的侧边栏，这虽然可行，但会丢失应用精心编排的顺序。migrate 输出会列出所有处于此状态的应用。

要转换应用的侧边栏，请在开发站点上运行以下命令并提交新文件：

bench --site <your-site> convert-sidebar-fixtures --app <your-app> --dry-run
bench --site <your-site> convert-sidebar-fixtures --app <your-app>
</your-app></your-site></your-app></your-site>

该命令只写入新文件，并保留旧文件夹，因此你可以再次运行它。关于应用可以附带的其他所有内容，请参阅侧边栏和 Dock。

故障排除

某个模块的侧边栏看起来是生成的，而不是精心编排的。 其应用尚未针对新导航进行更新，或者该模块从未有过侧边栏。请向应用开发者请求更新，或通过编辑侧边栏为所有人统一安排一次。

某个用户丢失了个人侧边栏。 只有当其副本至少包含一个条目，并且属于仍然存在的模块时，才会被保留。请与用户一起使用仅为我重新构建它。

在任何侧边栏中都找不到某个工作区。 它没有模块。请打开它，并在提示时选择一个模块，或在管理工作区中设置一个。

常见问题

升级后，我的用户会看到不同的主屏幕吗？
在你切换之前不会。使用图标网格的站点会继续保留它作为回退方案，但请计划迁移：该网格将在未来版本中移除。

我们可以试用新导航后再返回吗？
目前可以。在桌面设置中切换桌面页面。只有在回退方案仍然存在时，才能返回图标网格。

  • 桌面导航
  • 桌面
  • 侧边栏
  • Dock
  • 工作区