自定义图标¶

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

备注

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

** 应用程序图标** - 在桌面、Dock 或主屏幕上代表应用程序的图像。
运行时图标 - 应用程序界面中使用的图片（例如，按钮或表格中的图片）。

添加图标¶

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

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

icon = "icons/helloworld"

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

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

macOSLinuxWindowsAndroidiOS

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Unable to find icons/helloworld.icns for application icon; using default

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Unable to find icons/helloworld-16.png for 16px application icon; using default
Unable to find icons/helloworld-32.png for 32px application icon; using default
Unable to find icons/helloworld-64.png for 64px application icon; using default
Unable to find icons/helloworld-128.png for 128px application icon; using default
Unable to find icons/helloworld-256.png for 256px application icon; using default
Unable to find icons/helloworld-512.png for 512px application icon; using default

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Unable to find icons/helloworld.ico for application icon; using default

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Unable to find icons/helloworld-round-48.png for 48px round application icon; using default
Unable to find icons/helloworld-round-72.png for 72px round application icon; using default
Unable to find icons/helloworld-round-96.png for 96px round application icon; using default
Unable to find icons/helloworld-round-144.png for 144px round application icon; using default
Unable to find icons/helloworld-round-192.png for 192px round application icon; using default
Unable to find icons/helloworld-square-48.png for 48px square application icon; using default
Unable to find icons/helloworld-square-72.png for 72px square application icon; using default
Unable to find icons/helloworld-square-96.png for 96px square application icon; using default
Unable to find icons/helloworld-square-144.png for 144px square application icon; using default
Unable to find icons/helloworld-square-192.png for 192px square application icon; using default
Unable to find icons/helloworld-square-320.png for 320px square application icon; using default
Unable to find icons/helloworld-square-480.png for 480px square application icon; using default
Unable to find icons/helloworld-square-640.png for 640px square application icon; using default
Unable to find icons/helloworld-square-960.png for 960px square application icon; using default
Unable to find icons/helloworld-square-1280.png for 1280px square application icon; using default
Unable to find icons/helloworld-adaptive-108.png for 108px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-162.png for 162px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-216.png for 216px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-324.png for 324px adaptive application icon; using default
Unable to find icons/helloworld-adaptive-432.png for 432px adaptive application icon; using default

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

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

  [helloworld] Updating application code...
  Installing src/helloworld... done

  [helloworld] Updating application resources...
  Unable to find icons/helloworld-20.png for 20px application icon; using default
  Unable to find icons/helloworld-29.png for 29px application icon; using default
  Unable to find icons/helloworld-40.png for 40px application icon; using default
  Unable to find icons/helloworld-58.png for 58px application icon; using default
  Unable to find icons/helloworld-60.png for 60px application icon; using default
  Unable to find icons/helloworld-76.png for 76px application icon; using default
  Unable to find icons/helloworld-80.png for 80px application icon; using default
  Unable to find icons/helloworld-87.png for 87px application icon; using default
  Unable to find icons/helloworld-120.png for 120px application icon; using default
  Unable to find icons/helloworld-152.png for 152px application icon; using default
  Unable to find icons/helloworld-167.png for 167px application icon; using default
  Unable to find icons/helloworld-180.png for 180px application icon; using default
  Unable to find icons/helloworld-640.png for 640px application icon; using default
  Unable to find icons/helloworld-1024.png for 1024px application icon; using default
  Unable to find icons/helloworld-1280.png for 1280px application icon; using default
  Unable to find icons/helloworld-1920.png for 1920px application icon; using default

  [helloworld] Removing unneeded app content...
  Removing unneeded app bundle content... done

  [helloworld] Application updated.

这将报告 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] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Installing icons/helloworld.icns as application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Ad-hoc signing app...
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 00:01

[helloworld] Built build/helloworld/macos/app/Hello World.app

[helloworld] Starting app...

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Installing icons/helloworld-16.png as 16px application icon... done
Installing icons/helloworld-32.png as 32px application icon... done
Installing icons/helloworld-64.png as 64px application icon... done
Installing icons/helloworld-128.png as 128px application icon... done
Installing icons/helloworld-256.png as 256px application icon... done
Installing icons/helloworld-512.png as 512px application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Building application...
Build bootstrap binary...
...

[helloworld] Built build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/bin/helloworld

[helloworld] Starting app...

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Installing icons/helloworld.ico as application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Building App...
Removing any digital signatures from stub app... done
Setting stub app details... done

[helloworld] Built build\helloworld\windows\app\src\Hello World.exe

[helloworld] Starting app...

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Installing icons/helloworld-round-48.png as 48px round application icon... done
Installing icons/helloworld-round-72.png as 72px round application icon... done
Installing icons/helloworld-round-96.png as 96px round application icon... done
Installing icons/helloworld-round-144.png as 144px round application icon... done
Installing icons/helloworld-round-192.png as 192px round application icon... done
Installing icons/helloworld-square-48.png as 48px square application icon... done
Installing icons/helloworld-square-72.png as 72px square application icon... done
Installing icons/helloworld-square-96.png as 96px square application icon... done
Installing icons/helloworld-square-144.png as 144px square application icon... done
Installing icons/helloworld-square-192.png as 192px square application icon... done
Installing icons/helloworld-square-320.png as 320px square application icon... done
Installing icons/helloworld-square-480.png as 480px square application icon... done
Installing icons/helloworld-square-640.png as 640px square application icon... done
Installing icons/helloworld-square-960.png as 960px square application icon... done
Installing icons/helloworld-square-1280.png as 1280px square application icon... done
Installing icons/helloworld-adaptive-108.png as 108px adaptive application icon... done
Installing icons/helloworld-adaptive-162.png as 162px adaptive application icon... done
Installing icons/helloworld-adaptive-216.png as 216px adaptive application icon... done
Installing icons/helloworld-adaptive-324.png as 324px adaptive application icon... done
Installing icons/helloworld-adaptive-432.png as 432px adaptive application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Starting app...

备注

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

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

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating application resources...
Installing icons/helloworld-20.png as 20px application icon... done
Installing icons/helloworld-29.png as 29px application icon... done
Installing icons/helloworld-40.png as 40px application icon... done
Installing icons/helloworld-58.png as 58px application icon... done
Installing icons/helloworld-60.png as 60px application icon... done
Installing icons/helloworld-76.png as 76px application icon... done
Installing icons/helloworld-80.png as 80px application icon... done
Installing icons/helloworld-87.png as 87px application icon... done
Installing icons/helloworld-120.png as 120px application icon... done
Installing icons/helloworld-152.png as 152px application icon... done
Installing icons/helloworld-167.png as 167px application icon... done
Installing icons/helloworld-180.png as 180px application icon... done
Installing icons/helloworld-640.png as 640px application icon... done
Installing icons/helloworld-1024.png as 1024px application icon... done
Installing icons/helloworld-1280.png as 1280px application icon... done
Installing icons/helloworld-1920.png as 1920px application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Starting app...

备注

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

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

splash_background_color = "#D3E6F5"

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

macOSLinuxWindowsAndroidiOS

(beeware-venv) $ briefcase create

Application 'helloworld' already exists; overwrite [y/N]? y

[helloworld] Removing old application bundle...

[helloworld] Generating application template...
...

[helloworld] Created build/helloworld/macos/app

(beeware-venv) $ briefcase create

Application 'helloworld' already exists; overwrite [y/N]? y

[helloworld] Removing old application bundle...

[helloworld] Generating application template...
...

[helloworld] Created build/helloworld/linux/ubuntu/jammy

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

Application 'helloworld' already exists; overwrite [y/N]? y

[helloworld] Removing old application bundle...

[helloworld] Generating application template...
...

[helloworld] Created build\helloworld\windows\app

(beeware-venv) $ briefcase create android

Application 'helloworld' already exists; overwrite [y/N]? y

[helloworld] Removing old application bundle...

[helloworld] Generating application template...
...
[helloworld] Created build/helloworld/android/gradle

(beeware-venv) $ briefcase create iOS

Application 'helloworld' already exists; overwrite [y/N]? y

[helloworld] Removing old application bundle...

[helloworld] Generating application template...
...
[helloworld] Created 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) 来查看添加到按钮上的图标。