自定义图标

我们在主教程中开发的应用在打包时使用了默认的 “灰色蜜蜂” 图标。让我们通过配置使用我们自己的图标来个性化此应用程序。

备注

在 BeeWare 中，icon 一词可以指两种不同的东西：

• ** 应用程序图标** - 在桌面、Dock 或主屏幕上代表应用程序的图像。

• 运行时图标 - 应用程序界面中使用的图片（例如，按钮或表格中的图片）。

添加图标

每个平台都使用不同的应用程序图标格式 – 有些还需要\ 多个\ 不同大小和形状的。为此考虑，Briefcase 提供了一种简短的方法，可以配置一次图标，并让这种定义扩充到每个单个平台的所有所需要的图标。

编辑您的 project.toml，在 [tool.briefcase.app.helloworld] 配置部分中，在 sources 的正上方添加一个 icon 配置项:

图标 = "icons/helloworld"

图标配置时，无需指定任何扩展文件名。这里的值将会被作为前缀使用；每个平台将会在此前缀基础上添加更多项目，以构建在那个平台上所需的文件。有些平台需要\ 多个\ 图标文件；在这种情况下，前缀将与文件大小和变种结合在一起，生成使用的图标列表。

我们现在可以重新运行 briefcase update — 但这次，我们传入 --update-resources 标志，以告诉 Briefcase 我们想要安装新的应用资源（图标）：

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase update --update-resources

[helloworld] 更新应用程序代码...
正在安装 src/helloworld... 完成

[helloworld] 正在更新应用程序资源...
找不到应用程序图标的 icons/helloworld.icns；使用默认图标

[helloworld] 正在移除不需要的应用程序内容...
正在移除不需要的应用程序包内容... 完成

[helloworld] 应用程序已更新。

(beeware-venv) $ briefcase update --update-resources

[helloworld] 更新应用程序代码...
正在安装 src/helloworld... 完成

[helloworld] 更新应用程序资源...
找不到 16px 应用程序图标的 icons/helloworld-16.png；使用默认值
找不到 32px 应用程序图标的 icons/helloworld-32.png；使用默认值
找不到 64px 应用程序图标的 icons/helloworld-64.png；使用默认值
找不到 128px 应用程序图标的 icons/helloworld-128.png；使用默认值
找不到 256px 应用程序图标 icons/helloworld-256.png；使用默认图标
找不到 512px 应用程序图标 icons/helloworld-512.png；使用默认图标

[helloworld] 正在删除不需要的应用程序内容...
正在删除不需要的应用程序包内容... 完成

[helloworld] 应用程序已更新。

(beeware-venv) C:\...>briefcase update --update-resources

[helloworld] 更新应用程序代码...
正在安装 src/helloworld... 完成

[helloworld] 正在更新应用程序资源...
无法找到应用程序图标 icons/helloworld.ico；使用默认图标

[helloworld] 正在移除不需要的应用程序内容...
正在移除不需要的应用程序包内容... 完成

[helloworld] 应用程序已更新。

(beeware-venv) $ briefcase update android --update-resources

[helloworld] 正在更新应用程序代码...
正在安装 src/helloworld... 完成

[helloworld] 正在更新应用程序资源...
找不到 48px 圆形应用图标的 icons/helloworld-round-48.png；使用默认图标
找不到 72px 圆形应用图标的 icons/helloworld-round-72.png；使用默认值
找不到 96px 圆形应用图标的 icons/helloworld-round-96.png；使用默认值
找不到 144px 圆形应用图标的 icons/helloworld-round-144.png；使用默认值
找不到 192px 圆形应用图标的 icons/helloworld-round-192.png；使用默认图标
找不到 48px 方形应用图标的 icons/helloworld-square-48.png；使用默认图标
找不到 72px 方形应用图标的 icons/helloworld-square-72.png；使用默认图标
找不到 96px 方形应用图标 icons/helloworld-square-96.png；使用默认图标
找不到 144px 方形应用图标 icons/helloworld-square-144.png；使用默认图标
找不到 192px 方形应用图标 icons/helloworld-square-192.png；使用默认图标
无法找到 320px 正方形应用图标的 icons/helloworld-square-320.png；使用默认图标
无法找到 480px 正方形应用图标的 icons/helloworld-square-480.png；使用默认图标
无法找到 640px 正方形应用图标的 icons/helloworld-square-640.png；使用默认图标
找不到 960px 正方形应用图标 icons/helloworld-square-960.png；使用默认图标
找不到 1280px 正方形应用图标 icons/helloworld-square-1280.png；使用默认图标
找不到 108px 自适应应用图标 icons/helloworld-adaptive-108.png；使用默认图标
无法找到 162px 自适应应用图标的 icons/helloworld-adaptive-162.png；使用默认图标
无法找到 216px 自适应应用图标的 icons/helloworld-adaptive-216.png；使用默认图标
无法找到 324px 自适应应用图标的 icons/helloworld-adaptive-324.png；使用默认图标
无法找到 432px 自适应应用图标 icons/helloworld-adaptive-432.png；使用默认图标

[helloworld] 正在移除多余的应用内容...
正在移除多余的应用包内容... 完成

[helloworld] 应用已更新。

(beeware-venv) $ briefcase iOS --update-resources

  [helloworld] 正在更新应用程序代码...
  正在安装 src/helloworld... 完成

  [helloworld] 正在更新应用程序资源...
  找不到 20px 应用图标的 icons/helloworld-20.png；使用默认值
  找不到 29px 应用图标的 icons/helloworld-29.png；使用默认值
  找不到 40px 应用图标的 icons/helloworld-40.png；使用默认值
  找不到 58px 应用程序图标的 icons/helloworld-58.png；使用默认图标
  找不到 60px 应用程序图标的 icons/helloworld-60.png；使用默认图标
  找不到 76px 应用程序图标的 icons/helloworld-76.png；使用默认图标
  找不到 80px 应用程序图标的 icons/helloworld-80.png；使用默认图标
  找不到 87px 应用程序图标的 icons/helloworld-87.png；使用默认图标
  找不到 120px 应用程序图标的 icons/helloworld-120.png；使用默认图标
  找不到 152px 应用程序图标的 icons/helloworld-152.png；使用默认图标
  找不到 167px 应用程序图标的 icons/helloworld-167.png；使用默认图标
  找不到 180px 应用程序图标的 icons/helloworld-180.png；使用默认图标
  找不到 640px 应用程序图标的 icons/helloworld-640.png；使用默认图标
  找不到 1024px 应用程序图标的 icons/helloworld-1024.png；使用默认图标
  找不到 1280px 应用程序图标的 icons/helloworld-1280.png；使用默认图标
  无法找到 1920px 应用程序图标 icons/helloworld-1920.png；使用默认图标

  [helloworld] 正在删除不需要的应用程序内容...
  正在删除不需要的应用程序包内容... 完成

  [helloworld] 应用程序已更新。

这将报告 Briefcase 期望的特定图标文件（或多个文件）。但是，由于我们没有提供实际的图标文件，安装失败，Briefcase 恢复到默认值（相同的 "灰色蜜蜂 "图标）。

让我们提供一些实际的图标。下载 this icons.zip bundle，并解压到项目目录根目录。解压缩后，你的项目目录应该如下所示：

beeware-tutorial/
├── beeware-venv/
│   └── ...
└── helloworld/
    ├── ...
    ├── icons/
    │   ├── helloworld.icns
    │   ├── helloworld.ico
    │   ├── helloworld.png
    │   ├── helloworld-16.png
    │   └──...
    ├── src/
    │   └── ...
    └── pyproject.toml

这个文件夹中有很多图标，但大多数看起来都一样：浅蓝色背景上有一条绿色的蛇：

浅蓝色背景下的绿蛇图标](../../images/icon.png)。

唯一的例外是名称中带有"-adaptive-"的图标；这些图标将有透明背景。这代表了在 Briefcase 支持的每个平台上支持应用程序所需的所有不同图标尺寸和形状。

现在我们有了图标，可以再次更新应用程序了。不过，"briefcase update "只会将更新后的资源复制到构建目录中；我们还需要重建应用程序以确保包含新图标，然后启动应用程序。我们可以通过在调用 run 时传递 --update-resources来缩短这一过程，这将更新应用程序，更新应用程序的资源，然后启动应用程序：

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase run --update-resources

[helloworld] 更新应用程序代码...
安装 src/helloworld... 完成

[helloworld] 更新应用程序资源...
正在安装 icons/helloworld.icns 作为应用程序图标... 完成

[helloworld] 正在移除不需要的应用程序内容...
正在移除不需要的应用程序包内容... 完成

[helloworld] 应用程序已更新。

[helloworld] 正在对应用程序进行 Ad-hoc 签名...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 00:01

[helloworld] 已构建 build/helloworld/macos/app/Hello World.app

[helloworld] 启动应用程序...

(beeware-venv) $ briefcase run --update-resources

[helloworld] 更新应用程序代码...
正在安装 src/helloworld... 完成

[helloworld] 更新应用程序资源...
正在将 icons/helloworld-16.png 安装为 16px 应用程序图标... 完成
正在安装 icons/helloworld-32.png 作为 32 像素的应用程序图标... 完成
正在安装 icons/helloworld-64.png 作为 64 像素的应用程序图标... 完成
正在安装 icons/helloworld-128.png 作为 128 像素的应用程序图标... 完成
正在将 icons/helloworld-256.png 安装为 256px 应用程序图标... 完成
正在将 icons/helloworld-512.png 安装为 512px 应用程序图标... 完成

[helloworld] 正在移除不需要的应用程序内容...
正在移除不需要的应用程序包内容... 完成

[helloworld] 应用程序已更新。

[helloworld] 构建应用程序……
构建引导二进制文件……
……

[helloworld] 已构建 build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/bin/helloworld

[helloworld] 启动应用程序……

(beeware-venv) C:\...>briefcase build --update-resources

[helloworld] 更新应用程序代码...
安装 src/helloworld... 完成

[helloworld] 更新应用程序资源...
正在将 icons/helloworld.ico 安装为应用程序图标... 完成

[helloworld] 正在移除不需要的应用程序内容...
正在移除不需要的应用包内容... 完成

[helloworld] 应用程序已更新。

[helloworld] 正在构建应用...
正在从占位应用中移除所有数字签名... 完成
正在设置占位应用详细信息... 完成

[helloworld] 已构建 build\helloworld\windows\app\src\Hello World.exe

[helloworld] 正在启动应用...

(beeware-venv) $ briefcase build android --update-resources

[helloworld] 更新应用程序代码...
正在安装 src/helloworld... 完成

[helloworld] 更新应用程序资源...
正在将 icons/helloworld-round-48.png 安装为 48px 圆形应用程序图标... 完成
正在安装 icons/helloworld-round-72.png 作为 72px 圆形应用图标... 完成
正在安装 icons/helloworld-round-96.png 作为 96px 圆形应用图标... 完成
正在安装 icons/helloworld-round-144.png 作为 144px 圆形应用图标... 完成
正在安装 icons/helloworld-round-192.png 作为 192 像素圆形应用图标... 完成
正在安装 icons/helloworld-square-48.png 作为 48 像素方形应用图标... 完成
正在安装 icons/helloworld-square-72.png 作为 72 像素方形应用图标... 完成
正在安装 icons/helloworld-square-96.png 作为 96 像素的方形应用程序图标... 完成
正在安装 icons/helloworld-square-144.png 作为 144 像素的方形应用程序图标... 完成
正在安装 icons/helloworld-square-192.png 作为 192 像素的方形应用程序图标... 完成
正在安装 icons/helloworld-square-320.png 作为 320 像素的正方形应用程序图标... 完成
正在安装 icons/helloworld-square-480.png 作为 480 像素的正方形应用程序图标... 完成
正在安装 icons/helloworld-square-640.png 作为 640 像素的正方形应用程序图标... 完成
正在安装 icons/helloworld-square-960.png 作为 960 像素的正方形应用程序图标... 完成
正在安装 icons/helloworld-square-1280.png 作为 1280 像素的正方形应用程序图标... 完成
正在安装 icons/helloworld-adaptive-108.png 作为 108 像素的自适应应用程序图标... 完成
正在安装 icons/helloworld-adaptive-162.png 作为 162 像素自适应应用图标... 完成
正在安装 icons/helloworld-adaptive-216.png 作为 216 像素自适应应用图标... 完成
正在安装 icons/helloworld-adaptive-324.png 作为 324 像素自适应应用图标... 完成
正在安装 icons/helloworld-adaptive-432.png 作为 432 像素自适应应用图标……完成

[helloworld] 正在删除不需要的应用内容……
正在删除不需要的应用包内容……完成

[helloworld] 应用已更新。

[helloworld] 正在启动应用……

备注

如果您使用的是最新版本的安卓系统，您可能会注意到应用程序图标已更改为绿色的蛇形，但图标的背景却是白色，而不是浅蓝色。我们将在下一步中解决这个问题。

(beeware-venv) $ briefcase build iOS --update-resources

[helloworld] 更新应用程序代码...
安装 src/helloworld... 完成

[helloworld] 更新应用程序资源...
正在安装 icons/helloworld-20.png 作为 20px 应用程序图标... 完成
正在安装 icons/helloworld-29.png 作为 29px 应用程序图标... 完成
正在安装 icons/helloworld-40.png 作为 40px 应用程序图标... 完成
正在安装 icons/helloworld-58.png 作为 58px 应用程序图标... 完成
正在安装 icons/helloworld-60.png 作为 60px 应用程序图标... 完成
正在安装 icons/helloworld-76.png 作为 76px 应用程序图标... 完成
正在将 icons/helloworld-80.png 安装为 80px 应用程序图标... 完成
正在将 icons/helloworld-87.png 安装为 87px 应用程序图标... 完成
正在将 icons/helloworld-120.png 安装为 120px 应用程序图标... 完成
正在将 icons/helloworld-152.png 设置为 152px 应用程序图标... 完成
正在将 icons/helloworld-167.png 设置为 167px 应用程序图标... 完成
正在将 icons/helloworld-180.png 设置为 180px 应用程序图标... 完成
正在将 icons/helloworld-640.png 设置为 640 像素的应用程序图标... 完成
正在将 icons/helloworld-1024.png 设置为 1024 像素的应用程序图标... 完成
正在将 icons/helloworld-1280.png 设置为 1280 像素的应用程序图标... 完成
正在将 icons/helloworld-1920.png 设置为 1920 像素的应用程序图标……完成

[helloworld] 正在删除不需要的应用程序内容……
正在删除不需要的应用程序包内容……完成

[helloworld] 应用程序已更新。

[helloworld] 正在启动应用程序……

备注

如果在运行应用程序时出现引用 faker 或 httpx 的堆栈跟踪，则有可能是在教程的第 7 或第 8 步中没有运行应用程序。重新运行应用程序，添加 -r 参数以更新应用程序需求。

在 iOS 或 Android 上运行应用程序时，除了图标的变化外，您还会发现闪屏也加入了新图标。不过，图标的淡蓝色背景与闪屏的白色背景显得有些格格不入。我们可以通过自定义闪屏的背景颜色来解决这个问题。将以下定义添加到 pyproject.toml 中，就在 icon` 定义之后：

splash_background_color = "#D3E6F5"

不幸的是，Briefcase 无法将此更改应用于已生成的项目，因为这需要修改在最初调用 briefcase create 时生成的文件之一。要应用这一更改，我们必须通过重新运行 briefcase create 来重新创建应用程序。当我们这样做时，系统会提示我们确认是否要覆盖现有项目：

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase create

应用程序“helloworld”已存在；是否覆盖 [y/N]？ y

[helloworld] 正在删除旧的应用程序包...

[helloworld] 正在生成应用程序模板...
...

[helloworld] 已创建 build/helloworld/macos/app

(beeware-venv) $ briefcase create

应用程序“helloworld”已存在；是否覆盖 [y/N]？ y

[helloworld] 正在删除旧的应用程序包...

[helloworld] 正在生成应用程序模板...
...

[helloworld] 已创建 build/helloworld/linux/ubuntu/jammy

(beeware-venv) C:\...>briefcase create

应用程序“helloworld”已存在；是否覆盖 [y/N]？ y

[helloworld] 正在删除旧的应用程序包...

[helloworld] 正在生成应用程序模板...
...

[helloworld] 已创建 build\helloworld\windows\app

(beeware-venv) $ briefcase create android

应用程序“helloworld”已存在；是否覆盖 [y/N]？ y

[helloworld] 正在删除旧的应用程序包...

[helloworld] 正在生成应用程序模板...
...
[helloworld] 已创建 build/helloworld/android/gradle

(beeware-venv) $ briefcase create iOS

应用程序“helloworld”已存在；是否覆盖 [y/N]？ y

[helloworld] 正在删除旧的应用程序包...

[helloworld] 正在生成应用程序模板...
...
[helloworld] 已创建 build/helloworld/ios/xcode

然后，您可以使用 "briefcase run "重新构建和运行应用程序。您不会注意到桌面应用程序有任何变化；但安卓或 iOS 应用程序现在应该有一个淡蓝色的闪屏背景。

每当您对 pyproject.toml进行与源代码或依赖关系无关的更改时，都需要像这样重新创建应用程序。对描述、版本号、颜色或权限的任何更改都需要重新创建步骤。因此，在开发项目时，不应手动更改 build 文件夹的内容，也不应将 build 文件夹添加到版本控制系统中。build "文件夹应被视为完全短暂的，它是构建系统的输出，可根据需要重新创建，以反映项目的当前配置。

添加运行时图标

在应用程序界面上添加图标时，这类图标必须与应用程序图标分开存放。右键单击牦牛提比略，将图片保存为.png文件并命名为helloworld。然后将该文件保存到应用程序源码包中的 icons/ 文件夹中。

牦牛提比略的圣像](../../images/runtime-icon.png)。

您的目录将如下所示：

beeware-tutorial/
├── beeware-venv/
│   └── ...
└── helloworld/
    ├── ...
    ├── icons/
    │   ├── helloworld.icns
    │   ├── helloworld.ico
    │   ├── helloworld.png
    │   ├── helloworld-16.png
    │   └──...
    ├── src/
    │   ├── helloworld
    │   │   └── icons/
    │   │ └── helloworld.png
    │   └──...
    └── pyproject.toml

现在运行时图标已经就位，让我们为按钮添加一个图标。Toga 按钮 widget 只能容纳图标或文本（不能同时容纳），因此让我们更新按钮的代码，加入运行时图标。

helloworld_icon = toga.Icon("icons/helloworld")

button = toga.Button(
    icon=helloworld_icon,
    on_press=self.say_hello,
    margin=5,
)

由于运行时图标是捆绑在 Python 包内的应用程序资源，因此不需要重建或更新资源。此时，您可以运行 briefcase dev (或 briefcase run) 来查看添加到按钮上的图标。