PAYATHON 2026

WinUI 3 应用从商店安装后为何不显示 TitleBar 图标?

数据阿明

结论

优先检查 Images/Quadrato01.ico 的路径和打包设置,并使用完整文件路径调用 AppWindow.SetIcon。仅凭这段代码,无法确定商店安装后图标消失的唯一原因。

原代码使用了相对路径,并将图标加载放在 AppWindowTitleBar.IsCustomizationSupported() 条件内。需要确认安装后的程序能否找到文件,以及是否执行了 SetIcon。

为什么调试时正常,安装后却不显示?

Visual Studio 调试时能显示图标,只能说明文件在当时的运行环境中可以加载。发布后的安装目录、启动环境和实际包含的文件可能不同,这些差异可能影响相对路径。因此,需要检查安装包中的文件,不能只看项目目录。

Microsoft 的 AppWindow.SetIcon 文档说明,SetIcon(String) 使用 .ico 文件的完整路径,随应用分发的图标文件需要将 Build Action 设置为 Content。文档也给出了使用 AppContext.BaseDirectory 拼接路径的方法。

IconShowOptions.ShowIconAndSystemMenu 控制系统图标及菜单的显示行为,不能代替图标文件加载。相关说明见标题栏自定义文档。

解决步骤与代码示例

1. 确认图标进入发布包

在 Visual Studio 中选中 Images/Quadrato01.ico,检查其 Build Action 是否为 Content。然后检查生成的 MSIX 包,确认其中包含该文件,并核对文件所在的目录。

如果使用独立的打包项目,也要检查打包项目最终收集到的内容。文件存在于源码目录,不代表它已经进入安装包。

2. 使用完整路径加载图标

假设发布后的 Images 文件夹位于应用程序基目录下,可以在窗口创建后的初始化位置使用下面的代码。示例沿用已有的 MyAppWindow 字段、GetAppWindowForCurrentWindow() 和 OnClosing 方法。

using System;
using System.IO;
using Microsoft.UI.Windowing;

// Execute during window initialization.
if (MyAppWindow is null)
{
    MyAppWindow = GetAppWindowForCurrentWindow();
    MyAppWindow.Closing += OnClosing;
}

string iconPath = Path.Combine(
    AppContext.BaseDirectory,
    "Images",
    "Quadrato01.ico");

if (!File.Exists(iconPath))
{
    throw new FileNotFoundException("Icon file not found.", iconPath);
}

MyAppWindow.SetIcon(iconPath);

if (AppWindowTitleBar.IsCustomizationSupported())
{
    MyAppWindow.TitleBar.IconShowOptions =
        IconShowOptions.ShowIconAndSystemMenu;
}

代码将 SetIcon 移出了标题栏自定义支持检查,避免检查返回 false 时跳过图标加载。Closing 事件在取得窗口对象时订阅,以免反复初始化时重复订阅。

示例在文件缺失时抛出异常,方便查看完整路径。正式应用可以按现有的错误处理方式记录问题,并保留默认图标。

3. 在安装后的应用中验证

使用与商店发布相同配置生成的安装包进行验证,记录 iconPath、File.Exists(iconPath) 和 AppWindowTitleBar.IsCustomizationSupported() 的结果。

  • 文件不存在:检查资源是否漏打包,拼接的路径是否符合安装后的目录结构。
  • 文件存在但图标仍未显示:检查 .ico 文件是否有效、有无加载异常,以及后续代码是否再次修改图标或标题栏设置。
  • 支持检查返回 false:原代码会跳过整个代码块,需要结合目标 Windows 环境和 Windows App SDK 版本检查标题栏功能支持情况。

注意事项

使用 AppContext.BaseDirectory 的前提是图标确实位于其下的 Images 目录。如果安装包布局不同,应按实际布局构造路径。

不要直接把 ms-appx:///Images/Quadrato01.ico 当作文件路径传给 SetIcon(String)。如果使用包资源 URI,应先通过 StorageFile.GetFileFromApplicationUriAsync 获取文件,再传入它的 Path。SetIcon 文档提供了对应示例。

如果应用完全自定义了标题栏,并由 XAML 绘制可见的图标,还需要检查该图标元素的资源引用。自定义内容由应用负责绘制,相关行为见完整标题栏自定义说明。

备注:内容仅供参考。