Xamarin.Forms 的 XAML 热重载

  • 项目

XAML 热重载会插入现有工作流以提高工作效率并节省时间。 如果没有 XAML 热重载，则每次想要查看 XAML 更改时，必须生成和部署应用。 通过热重载，更改将在保存 XAML 文件时实时反映在正在运行的应用中。 此外，导航状态和数据将会被保留，让你能够快速迭代 UI，而不会丢失已在应用中完成的进度。 因此，使用 XAML 热重载，你将使用更少的时间重新生成和部署应用以验证 UI 更改。

注意

如果要编写本机 UWP 或 WPF 应用，而不使用 Xamarin.Forms，请参阅 适用于 UWP 和 WPF 的 XAML 热重载。

系统要求

IDE/Framework 所需最低版本
Visual Studio 2019 对于仅限更改模式为 16.9，对于完整页面模式则为 16.4
Visual Studio 2019 for Mac 对于仅限更改模式为 8.9，对于完整页面模式则为 8.4
Xamarin.Forms 对于仅限更改模式为 5.0.0.2012，对于完整页面模式则为 4.1

启用面向 Xamarin.Forms 的 XAML 热重载

如果从模板开始，则 XAML 热重载默认处于打开状态，并且项目配置为无需其他设置即可工作。 在仿真器或物理设备上调试 Android、iOS 或 UWP 应用，并更改 XAML 以触发 XAML 热重载。

如果从现有 Xamarin.Forms 解决方案工作，则无需进行其他安装即可使用 XAML 热重载，但可能需要仔细检查配置以确保获得最佳体验。 首先，在 IDE 设置中启用它：

  • 在 Windows 上，在“工具”>“选项”>“热重载”>“调试”处选中“启用 XAML 热重载”复选框（以及所需的平台）。
    • 在 Visual Studio 2019 的早期版本中，复选框位于“工具”>“选项”>“Xamarin”>“热重载”处。
  • 在 Mac 上，选中位于“Visual Studio”“首选项”“Xamarin 工具”“XAML 热重载”的“启用 Xamarin热重载”复选框。>>>
    • 在 Visual Studio for Mac 的早期版本中，复选框位于“Visual Studio”>“首选项”>“项目”>“Xamarin 热重载”中。

然后，在 Android 和 iOS 生成设置中，检查链接器是否设置为“不要链接”或“不链接任何项”。 要将 XAML 热重载与物理 iOS 设备配合使用，还必须选中“启用 Mono 解释器”（Visual Studio 16.4 及更高版本）或向“其他 mtouch 参数”（Visual Studio 16.3 及更低版本）添加“--interpreter”。

可以使用以下流程图检查现有项目的设置，以便与 XAML 热重载配合使用：

XAML Hot Reload Setup

热重载模式

XAML 热重载可以在两种不同的模式下工作 - 较新的仅限更改模式和较旧的完整页面模式。

从 Visual Studio 16.9 和 Visual Studio for Mac 8.9 开始，默认行为是将仅限更改模式用于所有使用 Xamarin.Forms 5.0 或更高版本的应用。 对于旧版 Xamarin.Forms，使用完整页面模式。 但是，可以在热重载 IDE 设置中强制将完整页面模式用于所有应用（在 Windows 上为“工具”>“选项”>“调试”>“热重载”，在 Mac 上为“Visual Studio”>“首选项”>“Xamarin 工具”>“XAML 热重载”）。

仅限更改会分析 XAML，以确切了解进行编辑时更改的内容，并仅将这些更改发送到正在运行的应用。 这是用于 WPF 和 UWP 热重载的相同技术。 它会保留 UI 状态，因为它不会为完整页面重新创建 UI，而只是更新受编辑影响的控件的更改属性。 仅限更改模式还支持使用实时可视化树。

默认情况下，使用仅限更改模式后，无需保存文件即可查看更改 - 键入时会立即应用更新。 但可以更改此行为以仅在文件保存时进行更新。 这可以通过在热重载 IDE 设置中选中 “在文档保存时应用 XAML 热重载”复选框（当前仅在 Windows 上可用）来实现。 如果进行更大的 XAML 更新，并且不希望在完成后显示它们，则仅在文档保存时更新有时会非常有用。

进行编辑并保存后，完整页面模式会将完整的 XAML 文件发送到正在运行的应用。 然后，正在运行的应用重新加载页面，并重新创建其控件 - 你会看到 UI 刷新。

仅限更改模式是热重载的未来，我们建议尽可能使用它。 它速度更快、可以保留 UI 状态并支持实时可视化树。 对于尚未更新到 Xamarin.Forms 5.0 的应用，仍提供完整页面模式。

注意

切换模式时，需要重启调试会话。

XAML 错误

仅限更改模式：如果进行更改，热重载 XAML 分析程序将被视为无效，它将在编辑器中显示带下划线的错误，并将其包含在错误窗口中。 这些热重载错误具有一个错误代码，其开头为“XHR”（适用于 XAML 热重载）。 如果页面上存在任何此类错误，即使对页面的其他部件进行了更改，热重载也不会应用更改。 修复所有错误，以便热重载再次开始处理页面。

完整页面模式：如果 XAML 热重载无法热心加载所做的更改，它将在编辑器中显示带下划线的错误，并将其包含在错误窗口中。 这些更改（称为粗鲁编辑）包括错误键入 XAML 或将控件连接到不存在的事件处理程序。 即使进行了粗鲁编辑，也可以在不重启应用的情况下继续重新加载 - 在 XAML 文件中的其他位置进行另一项更改并点击“保存”。 粗鲁编辑将不会被重新加载，但将继续应用其他更改。

一次性在多个平台上重新加载

XAML 热重载支持在 Visual Studio 和 Visual Studio for Mac 中同时进行调试。 可以同时部署 Android 和 iOS 目标，以一次性查看两个平台上反映的更改。 要在多个平台上进行调试，请参阅：

已知限制

  • 目前不支持 Android、iOS 和 UWP 以外的 Xamarin.Forms 目标（例如 macOS）。
  • 使用 [XamlCompilation(XamlCompilationOptions.Skip)]，从而禁用 XAML 编译是不受支持的，并且可能导致实时可视化树出现问题。
  • 在 XAML 热重载会话期间，无法添加、删除或重命名文件或 NuGet 包。 如果添加或删除了文件或 NuGet 包，需重新生成并重新部署应用才能继续使用 XAML 热重载。
  • 将链接器设置为“不要链接”或“不链接任何项”以获得最佳体验。 “仅限链接 SDK”设置大部分的时间都会有效，但在某些情况下可能会失败。 可以在 Android 和 iOS 生成选项中找到链接器设置。
  • 在物理 iPhone 上进行调试需要解释器使用 XAML 热重载。 为此，请打开项目设置，选择 iOS 生成”选项卡，并确保启用了“启用 Mono 解释器”设置。 可能需要将属性页顶部的“平台”选项更改为“iPhone”。
  • XAML 热重载无法重新加载 C# 代码，包括事件处理程序、自定义控件、页面后端代码和其他类。

疑难解答

  • 显示 XAML 热重载输出以查看状态消息，这会有助于排除故障：
    • Windows：使用“视图”>“输出”显示输出，然后选择位于顶部的“Xamarin 热重载”下面的“显示输出来源：”
    • Mac：将鼠标悬停在状态栏中的“XAML 热重载” 以显示该填充
  • 如果 XAML 热重载无法初始化：
    • 请更新 Xamarin.Forms 版本。
    • 确保使用的是最新版本的 IDE。
    • 在项目的生成设置中，将 Android 或 iOS 链接器设置设为“不要链接”。
  • 如果在保存 XAML 文件时没有发生任何情况，请确保在 IDE 中启用 XAML 热重载。
  • 如果要在物理 iPhone 上进行调试，并且你的应用变得无响应，请检查是否已启用解释器。 如果要启用它，请在 iOS 生成设置中选中“启用 Mono 解释器”（Visual Studio 16.4/8.4 及更新），或向 “其他 mtouch 参数”字段（Visual Studio 16.3/8.3 及更早版本）添加“--interpreter”。

要报告 bug，请在 Windows 上使用“帮助”>“发送反馈”>“报告问题”，或在 Mac 上使用“帮助”>“报告问题”。