与 GNOME 集成¶

GNOME 是一个构建完整桌面和开发平台的项目，完全基于自由软件。许多公司、政府、学校、机构和个人已经在他们的系统上部署了 GNOME 桌面。如果您是第三方软件的开发者（“独立软件供应商”或 ISV，或者如果您不是商业用途，则是“独立软件开发者” (ISD)），您可能希望确保您的现有软件在 GNOME 下能够正常运行。本指南解释了如何将现有软件与 GNOME 集成，而无需实际重写该软件以显式使用 GNOME 平台库和开发工具。

本指南在以下情况下将很有用

您是一位软件开发者或分发者，您有一个并非专门设计用于与 GNOME 配合使用的应用程序，但您希望确保它能在 GNOME 桌面上舒适地运行。
您是为一个部署了 GNOME 桌面的机构的系统管理员。您还有遗留或内部应用程序，并且希望您的 GNOME 用户能够舒适地访问这些应用程序。
您正在编写一个真正的 GNOME 应用程序，并且需要一个基本检查清单，以确保您的应用程序与 GNOME 桌面的其余部分良好集成。

通常，本指南是关于将现有软件集成到 GNOME 桌面中。另一方面，如果您正在考虑编写新软件，我们鼓励您完全以 GNOME 作为目标平台进行开发；请参阅 GNOME 开发者网站以获取更多信息。

GNOME 的主要关注点之一是用户体验。用户应该拥有一个舒适的计算环境：这意味着拥有一个完整的桌面和一组以一致的方式协同工作的应用程序。通过相对较少的努力，并非显式为 GNOME 设计的应用程序也可以在 GNOME 桌面中舒适地运行。

基本集成¶

桌面文件¶

要从 GNOME 运行应用程序，用户单击桌面上的图标，或从应用程序网格中选择他们想要运行的应用程序。因此，将现有程序与 GNOME 集成的第一步是将其注册到用户可以运行的应用程序集中。

应用程序网格是根据注册的应用程序列表自动构建的。

在 GNOME 和其他 freedesktop.org 兼容的桌面上，应用程序通过桌面条目注册到桌面的菜单中，这是一个带有 .desktop 扩展名的文本文件。此桌面文件包含应用程序配置的列表。桌面从该文件中获取信息并用于

关联应用程序的名称、描述和图标
将应用程序创建的每个窗口与相同的名称和图标关联
识别它支持的文件打开的 MIME 类型

要注册您的应用程序，请使用您为应用程序选择的相同应用程序标识符和 .desktop 文件扩展名创建一个桌面文件。

注意

有关应用程序标识符的更多信息，请参阅应用程序 ID 教程。

典型的桌面文件将具有以下结构

[Desktop Entry]
Name=Your Application
Comment=An amazing application
Exec=your-application
Icon=com.example.YourApplication
Keywords=various;keywords;describing;your;application;
StartupNotify=true
Terminal=false

桌面文件中的一些键可以在不同的语言中本地化，例如 Name、Comment、GenericName 和 Keywords 键。通过本地化您的桌面文件，您可以让世界各地的用户更容易找到您的应用程序。

注意

有关桌面文件格式的更多信息，请访问 Freedesktop.org 桌面条目规范。

重要提示

您应该确保您的桌面文件作为您项目测试套件的一部分有效。您可以使用 desktop-file-validate 工具，该工具由 desktop-file-utils 项目提供

您的桌面文件应安装在 XDG_DATA_DIRS 或 XDG_DATA_HOME 环境变量的其中一个 applications 目录中，具体取决于安装前缀。对于系统安装，前者通常意味着 /usr/share/applications；对于用户安装，后者通常是 $HOME/.local/share/applications。

注意

有关 XDG 目录的更多信息，请访问 Freedesktop.org 基本目录规范

图标¶

应用程序图标应按照 Freedesktop.org 图标主题规范安装。对于 GNOME 应用程序，您应该提供

使用 SVG 格式的全彩可缩放图标

或者

使用 PNG 格式的全彩 256×256 像素栅格图标

您还应选择性地提供使用 SVG 格式的符号图标。

您应该将图标安装在 hicolor 图标主题命名空间下，使用应用程序标识符作为图标的基本名称；例如

/usr/share/icons/hicolor/256x256/apps/com.example.YourApplication.png
/usr/share/icons/hicolor/scalable/apps/com.example.YourApplication.svg
/usr/share/icons/hicolor/symbolic/apps/com.example.YourApplication-symbolic.svg

高级集成¶

D-Bus 激活¶

与典型的 UNIX 风格 fork()/exec() 进程创建方法不同，在 GNOME 中启动应用程序最好是通过向该应用程序的知名名称发送 D-Bus 消息来完成 D-Bus 激活。如果应用程序已经运行，它可以响应该消息，通过打开新窗口或提升其现有窗口，而不是启动新实例。

使用 D-Bus 激活启动进程可确保每个应用程序在其自身的原始环境中启动，作为会话的直接后代，而不是在其父进程的环境中。这对于确保应用程序最终进入正确的 cgroup 非常重要，例如。

另一个原因是，可进行 D-Bus 激活是使用持久通知的先决条件。

为了让 D-Bus 知道如何激活您的服务，您需要在 /usr/share/dbus-1/services 下安装一个 D-Bus 服务文件

[D-BUS Service]
Name=com.example.YourApplication
Exec=/usr/bin/your-app --gapplication-service

注意

在 Exec 行上的 --gapplication-service 命令行参数由 GApplication 用于将应用程序实例作为服务启动。

您还需要将以下键添加到应用程序的桌面文件中

DBusActivatable=true

如果 DBusActivatable 为 true 并且桌面文件名看起来像一个有效的应用程序 ID，那么 Exec 行将被忽略，您的应用程序将通过 D-Bus 激活方式启动（使用桌面文件名减去 .desktop 扩展名作为应用程序 ID）。

MIME 类型¶

如果您的应用程序可以打开特定的 MIME 类型，您需要在桌面文件中告知桌面。例如，如果您的应用程序可以接受 PNG 文件，请将以下行添加到您的桌面文件中

MimeType=image/png;

注意

可以通过用分号分隔不同的类型来添加其他 MIME 类型。

如果您希望应用程序一次打开多个文件，则需要在 Exec 行中添加 %F 作为参数，或者如果它只支持一次打开一个文件，则添加 %f，这将会在打开应用程序支持的多个文件选择时打开应用程序的多个实例。

系统已经知道大量的 MIME 类型。但是，如果您正在创建一个自定义的 MIME 类型，您需要将其注册到 MIME 数据库中，通过在 /usr/share/mime/packages 目录中创建一个 XML 文件

<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
   <mime-type type="application/x-example">
     <comment>Example file type </comment>
     <magic priority="50">
       <match value="search-string" type="string" offset="10:140"/>
     </magic>
     <glob pattern="*.newextension"/>
   </mime-type>
</mime-info>

重要提示

为了避免与其他应用程序添加的文件发生冲突，您应该使用应用程序的 ID 作为文件的基本名称，例如 com.example.YourApplication.xml

在此示例中，将示例 MIME 类型替换为您的 MIME 类型名称。magic 规则搜索文件的内容以查找给定的字符串进行标识。glob 规则使用文件名的后缀进行标识。

注意

由于 magic 规则强制计算机打开文件以搜索字符串，因此 glob 规则是首选。

一旦您的新 MIME 类型在文件中得到充分描述，请在 shell 中运行以下命令

update-mime-database /usr/share/mime

提示

有关选择好的 MIME 扩展名和注册您的 MIME 类型，请访问 IANA 网站。

URI 方案处理¶

如果您的应用程序可以打开特定的 URI 方案，您需要在桌面文件中告知桌面。例如，如果您的应用程序可以接受 mailto: URI，您需要将相应的 x-scheme-handler/mailto 添加到桌面文件中的 MIME 类型中，如前一节中所述。您可以使用任何您想要的 URI 方案，而不仅仅是常见的方案，例如 mailto/http/https/ftp，例如 gemini:// URI 方案。

您还需要使用 %u 或 %U 分别表示一个或多个 URI，就像在上一节中使用 %f 和 %F 一样。如果您的应用程序同时处理 MIME 类型和 URI，则只需要使用 %u 或 %U 版本，无需使用 %f 和 %F。