Ssk-wh's Blog
Desktop Entry Specification(桌面入口规范)
ssk-wh Lv4
  2023-05-18 10:16:43   2024-07-12 03:05:34    5.4k Words  20 Mins  

原文链接：https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.1.html

注：部分内容并未翻译，实则是感觉没（不）必（想）要（写），感兴趣的童鞋可以访问原文链接。

名词介绍

implementations:实现者，本文中的实现方一般指桌面环境的发行商，此规范的实现者

介绍

KDE和GNOME桌面环境都采用了类似的 desktop entries 格式或描述特定程序如何启动的配置文件。为了更好地造福社区，桌面环境各方都应达成统一标准，以便两个桌面环境之间以及任何实现规范的其他环境之间的互操作，都能变得更加简单。(鹰酱教我们的标准化)

基础格式

Desktop entry 文件应具有 .desktop 扩展名， Directory 类型的文件应具有 .directory 扩展名。根据扩展名确定文件类型使得确定文件类型非常容易和快速。当没有文件扩展名时，桌面系统应该 fallback 到通过 magic detection (指各家桌面环境独特的检测方式) 识别。

对于应用程序，桌面文件名称的一部分（*.desktop* 之前）应遵循 reverse DNS （域名反向原则，其实就是把域名反过来写）约定，例如 org.example.FooViewer.desktop。

Desktop entry 文件以 UTF-8 编码。文件被解释为一系列由换行符分隔的行。且内容是大小写敏感的。

为了保持兼容，规范的实现方不得从文件中删除任何字段，即使实现方不支持这些字段。这些字段必须提供一个维护列表，如果文件被“重写”，它们将被重新包含在内。这确保即使另一个系统访问和更改文件，任何特定于桌面的扩展也将被保留。

注释

以 # 开头的行和空行被视为注释，将被忽略，但在 Desktop entry 文件的读写过程中应保留它们。

注释行不会被规范实现方所解释，可以包含任何字符（ LF 除外）。但是，鼓励使用 UTF-8 (但不建议包含非 ASCII 字符)进行注释。

Group

名为 groupname 的组标题的格式如下：
[groupname]

组名可以包含除 [and] 和控制字符之外的所有 ASCII 字符

多个组可能不具有相同的名称(实际上我认为是一定不会相同，但是规范写的是 may not have the same name, emmm…)

Group Header 之后的所有 {key,value} 键值对都属于该组，直到遇见一个新的 Group Header

Desktop entry 文件的基本格式要求有一个名为 [Desktop Entry] 的组头。 文件中可能存在其他组，但这是明确需要支持的最重要的组。 该组还应该用作自动 MIME 类型检测的 “magic key”。 在 Desktop entry 文件中，该组之前不应有任何内容，但可能有一个或多个注释。

Entries

文件中的 entry 是 形如 {key,value} 的键值对 ，格式如下：
Key=Value
应忽略等号前后的空格, “=” 符号是实际的分隔符

Key 只能使用字符 A-Za-z0-9

由于大小写很重要， Name 和 NAME 作为 Key并不等同

同一 Group 中的多个 Key 可能具有不同的名称( emmm… , 我觉得应该去掉可能两个字)。不同 Group 中的 Key 可能具有相同的名称

支持的值类型

公认的 Value 的类型有：string, localestring, boolean, numeric.

string: 字符串类型的值可以包含除控制字符之外的所有 ASCII 字符。
localestring: localestring 类型的值是用户可显示的，并以 UTF-8 编码。
boolean: 布尔类型的值必须是字符串 true 或 false
numeric: 数字类型的值必须是 C 语言环境中 scanf 的 *%f *说明符所识别的有效浮点数。

string 和 localestring 类型的值支持转义序列 \s、\n、\t、\r 和 \，分别表示 ASCII 空格、换行符、制表符、回车符和反斜杠。

一些键可以有多个值。 在这种情况下，键的值被指定为复数：例如，*string(s)*。 多个值应该用分号分隔，键的值可以选择以分号结尾。 尾随的空字符串必须始终以分号结尾。 这些值中的分号需要使用 \; 进行转义。

公认的桌面入口Key

Key 有可选和必需两种可能。如果一个 Key 是可选的，它可能存在于文件中也可能不存在。然而，如果不是，标准的实现者不应该视为异常情况，它必须提供一些合理的默认值(即可选的 Key 不存在时，由规范实现者提供合理的默认值)。

有些 Key 只有在另一个特定 Key 也存在并设置为特定值时才在上下文中有意义。如果特定 Key 不存在或未设置为特定值，则不应使用这些 Key 。例如，Terminal 只有在 Type 的值为 Application 时才能使用。

如果一个必须存在的 Key 仅在另一个 Key 设置为特定值的上下文中有效，则仅当另一个 Key 设置为特定值时它才必须存在。例如，当且仅当 Type 的值为 Link 时，URL 必须存在。

一些示例的 Key ：Name[C]、Comment[it]

标准的 Keys

Key Description Value Type Required? Type
Type 本规范定义了 3 种类型的桌面条目：应用程序（类型 1）、链接（类型 2）和目录（类型 3）。为了允许在未来添加新类型，实现应该忽略具有未知类型的桌面条目。 string YES
Version 桌面条目符合的桌面条目规范的版本。确认此版本规范的条目应使用 1.0。请注意，版本字段不一定需要存在。 string NO 1-3
Name 应用程序的特定名称，例如 “Mozilla” 。 localestring YES 1-3
GenericName 应用程序的通用名称，例如 “Web Browser” 。 localestring NO 1-3
NoDisplay NoDisplay 表示“此应用程序存在，但不在菜单中显示它”。这可能对例如将此应用程序与 MIME 类型相关联，以便它可以从文件管理器（或其他应用程序）启动，而无需为其提供菜单项（有很多类似的场景，例如 netscape -remote 或 kfmclient openURL 类型的操作）。 boolean NO 1-3
Comment 条目的工具提示，例如“查看 Internet 上的站点”。该值不应与 Name 和 GenericName 的值重复。 localestring NO 1-3
Icon 在文件管理器、菜单等中显示的图标。如果名称是绝对路径，将使用给定的文件。如果名称不是绝对路径，则将使用图标主题规范中描述的算法来定位图标。 localestring NO 1-3
Hidden 隐藏应该被称为删除。 这意味着用户删除了（在他的级别）存在的东西（在上层，例如在系统目录中）。 就该用户而言，它等同于根本不存在的 .desktop 文件。 这也可以用于“卸载”现有文件（例如由于重命名） - 通过让 make install 安装一个 Hidden=true 的文件。 boolean NO 1-3
OnlyShowIn, NotShowIn 标识应显示/不显示给定桌面条目的环境的字符串列表。 这些键中只有一个，即 OnlyShowIn 或 NotShowIn，可能会出现在一个组中（有关可能的值，请参阅Desktop Menu Specification）。 string(s) NO 1-3
DBusActivatable 一个布尔值，指定此应用程序是否支持 D-Bus 激活。 如果缺少此键，则默认值为 false。 如果该值为真，则实现应忽略 Exec 键并发送 D-Bus 消息以启动应用程序。 有关其工作原理的更多信息，请参见 D-Bus Activation。 应用程序仍应在其桌面文件中包含 Exec= 行，从而与不支持 DBusActivatable 字段的桌面环境兼容。 boolean NO
TryExec 磁盘上用于确定程序是否实际安装的可执行文件的路径。 如果路径不是绝对路径，则在 $PATH 环境变量中查找该文件。 如果该文件不存在或不可执行，则可以忽略该条目（例如，在菜单中隐藏）。 string NO 1
Exec 要执行的程序，可能带有参数。 有关此键如何工作的详细信息，请参阅 Exec key。 如果 DBusActivatable 未设置为 true，则需要 Exec 的键。 即使 DBusActivatable 为真，也应该指定 Exec ，从而与不支持 DBusActivatable 字段的桌面环境兼容。。 string NO 1
Path 如果条目是应用程序类型，则为运行程序的工作目录。 string NO 1
Terminal 程序是否在终端窗口中运行。 boolean NO 1
Actions 应用程序操作的标识符。 这可用于告诉应用程序执行不同于默认行为的特定操作。 Application actions 部分描述了操作的工作原理。 string(s) NO 1
MimeType 此应用程序支持的 MIME 类型。 string(s) NO 1
Categories 条目应显示在菜单中的类别（有关可能的值，请参阅Desktop Menu Specification）。 string(s) NO 1
Keywords 除了其他元数据之外，还可以使用的字符串列表来描述此条目。这可能很有用，例如方便便于条目搜索功能。这些值不用于显示，不应与 Name 或 GenericName 的值重复。 localestring(s) NO 1
StartupNotify 如果为真，则已知应用程序在使用 DESKTOP_STARTUP_ID 环境变量集启动时将发送“删除”消息。 如果为 false，则已知该应用程序根本无法使用启动通知（不显示任何窗口，即使在使用 StartupWMClass 时也会中断等）。 如果不存在，则合理的处理取决于实现（假设为 false，使用 StartupWMClass 等）。 （有关详细信息，请参阅启动通知协议规范）。 boolean NO 1
StartupWMClass 如果指定，则已知应用程序将至少映射一个具有给定字符串的窗口作为其 WM 类或 WM 名称提示（有关更多详细信息，请参阅Startup Notification Protocol Specification）。 string NO 1
URL 如果条目是链接类型，则为要访问的 URL。 string YES 2

Exec

Exec Key 的值中必须包含命令行。命令行由一个可执行程序组成，后跟一个或多个参数（可选地）。可执行程序可以用其指定完整路径，也可以只用可执行文件的名称指定。如果未提供完整路径，则在桌面环境使用的 $PATH 环境变量中查找可执行文件。可执行程序的名称或路径不能包含等号 “=”。参数由空格分隔。

参数可以完整引用。如果参数包含保留字符，则必须引用该参数。引用参数的规则也适用于提供的可执行程序名称或路径。

引用必须通过将参数括在双引号和转义双引号字符、反引号字符 (“`“)、美元符号 (“$”) 和反斜杠字符 (“\“) 之间来完成，方法是在其前面加上一个额外的反斜杠字符。规范实现者必须在扩展字段代码之前和将参数传递给可执行程序之前撤消引用。保留字符有空格（” “）、制表符、换行符、双引号、单引号（*’*）、反斜杠（”\“）、大于号（”>”）、小于号（”<” )、波浪号 (“~”)、竖线 (“|”)、和号 (“&”)、分号 (“;”)、美元符号 (“$”)、星号 (“*”)、问号 (“ ？”）、井号（“#”）、括号（“（”）和（”）”）和反引号（“`”）。

请注意，字符串类型值的一般转义规则规定反斜杠字符也可以转义为 (“\“)，并且此转义规则在引号规则之前应用。因此，要在桌面条目文件的引用参数中明确表示文字反斜杠字符，需要使用四个连续的反斜杠字符（“\\”）。同样，桌面条目文件中引用参数中的文字美元符号明确表示为 (“\$”)。

定义了许多特殊字段代码，当在命令行中遇到这些代码时，文件管理器或程序启动器将对其进行扩展。字段代码由百分比字符 (“%”) 和后跟字母字符组成。文字百分比字符必须转义为%%. 应从命令行中删除并忽略不推荐使用的字段代码。字段代码仅展开一次，用于替换字段代码的字符串不应检查字段代码本身。

包含未在本规范中列出的域代码的命令行是无效的，不得处理，特别是实现可能不会引入对本规范中未列出的域代码的支持。扩展（如果有）应通过新密钥引入。

除非本规范明确指示，否则实现必须注意不要将字段代码扩展为多个参数。这意味着名称字段、文件名和其他可以包含空格的替换必须在扩展后作为单个参数传递给可执行程序。

尽管 Exec 键被定义为具有字符串类型的值，该值仅限于 ASCII 字符，但字段代码扩展可能会在参数中引入非 ASCII 字符。实现必须注意传递给可执行程序的参数中的所有字符都根据适用的区域设置进行了正确编码。

公认的字段代码如下所示：

Code Description
%f 单个文件名，即使选择了多个文件。读取桌面条目的系统应该认识到程序可能不能处理多个文件参数，如果程序不能处理额外的文件参数，它应该可能为每个选定的文件生成并执行程序的多个副本。对于不理解 URL 语法的程序，如果文件不在本地文件系统上（即在 HTTP 或 FTP 位置上），文件将被规范实现方复制到本地文件系统并将%f扩展为指向临时文件。
%F 文件列表。用于可以一次打开多个本地文件的应用程序。每个文件都作为单独的参数传递给可执行程序。
%u 单个网址。本地文件可以作为 file: URL 或文件路径传递。
%U URL 列表。每个 URL 都作为单独的参数传递给可执行程序。本地文件可以作为 file: URL 或文件路径传递。
%d 已弃用。
%D 已弃用。
%n 已弃用。
%N 已弃用。
%i Icon桌面条目的键扩展为两个参数，第一个是 键--icon的值，然后是键的值 Icon。Icon如果键为空或缺失， 则不应扩展为任何参数。
%c Name桌面条目中 相应键中列出的应用程序的翻译名称。
%k 桌面文件的位置作为 URI（例如，如果从 vfolder 系统获取）或本地文件名，如果不知道位置则为空。
%v 已弃用。
%m 已弃用。

命令行最多可以包含一个 %f、*%u、%F* 或 %U 字段代码。如果应用程序不应打开任何文件，则必须从命令行中删除并忽略 %f、*%u、%F* 和 %U 字段代码。

字段代码不得在引用参数中使用，引用参数中字段代码扩展的结果是未定义的。 %F 和 %U 字段代码只能用作它们自己的参数。

通过 D-Bus 启动

支持由 D-Bus 启动的应用程序必须实现以下接口（以 D-Bus 自省 XML 格式给出）：
<interface name='org.freedesktop.Application'> <method name='Activate'> <arg type='a{sv}' name='platform_data' direction='in'/> </method> <method name='Open'> <arg type='as' name='uris' direction='in'/> <arg type='a{sv}' name='platform_data' direction='in'/> </method> <method name='ActivateAction'> <arg type='s' name='action_name' direction='in'/> <arg type='av' name='parameter' direction='in'/> <arg type='a{sv}' name='platform_data' direction='in'/> </method> </interface>

应用程序必须按照介绍部分中的命名建议命名其桌面文件（例如，文件名必须类似于org.example.FooViewer.desktop）。应用程序必须具有可激活的 D-Bus 服务，其众所周知的名称等于桌面文件名删除.desktop部分（对于我们的示例， org.example.FooViewer）。上述接口必须在如下确定的对象路径中实现：以应用程序众所周知的 D-Bus 名称开头，将所有点更改为斜杠并在斜杠前添加前缀。对于我们的示例，这是/org/example/FooViewer.

Activate当应用程序启动时没有要打开的文件时调用 该方法。

Open当使用文件启动应用程序时调用该方法。字符串数组是一个 URI 数组，采用 UTF-8 格式。

当桌面操作ActivateAction被激活时调用 该方法。参数是动作的名称。 action-name

所有方法都采用一个platform-data参数，该参数的使用方式与环境变量的使用方式类似。目前，规范只定义了一个字段： desktop-startup-id. 这应该是一个字符串，其值与存储在环境变量中的值相同DESKTOP_STARTUP_ID，如启动通知协议规范所指定。

注册 MIME 类型

MimeType Key 用于告知用户应用程序可以处理哪些 MIME 类型.一些应用的 MimeType 内容可能会非常长。应用程序应该能够使用 Exec 键中列出的命令合理地打开这些类型的文件。

此字段中的 MIME 类型不应有优先级，桌面文件中不应有任何形式的优先级。应用程序的优先级在 .desktop 文件之外处理。

应用的其他动作

应用程序类型的桌面条目可以包括一个或多个操作。动作表示调用应用程序的另一种方式。应用程序启动器应该在应用程序的上下文中向用户公开它们（例如，作为子菜单）。这用于构建所谓的 “Quicklists” 或 “Jumplists” 。

动作标识符

每个动作都由一个字符串标识，遵循与键名相同的格式（see the section called “Entries”）。每个标识符都与一个必须存在于 .desktop 文件中的操作组相关联。操作组是一个名为 Desktop Action %s 的组，其中 %s 是操作标识符。

为 Actions 键中未提及的操作标识符设置操作组是无效的。规范实现者必须忽略这样的 Action 组。

Action 的 Key

每个操作组都支持以下键。如果 一个 REQUIRED 的键不存在于 Action Group 中，则规范实现者应忽略此操作。

Action 的特定 Key

Key Description Value Type REQUIRED
Name 用于显示给用户查看的一个标签。由于该操作始终显示在特定应用程序的上下文中（即，作为启动器的子菜单），因此这只需要在一个应用程序中是明确的即可，不应包含应用程序名称。 localestring YES
Icon 与 Action 一起显示的图标。如果名称是绝对路径，将使用给定的文件。如果名称不是绝对路径，则将使用图标主题规范中描述的算法来定位图标。实现可能会选择忽略它。 localestring NO
Exec 此操作要执行的程序命令，可能带有参数。有关此键如何工作的详细信息，请参阅 Exec 章节。如果 desktop entry group 组中的 DBusActivatable 未设置为 true，则需要 Exec 键。即使 DBusActivatable 为真，也应该指定 Exec 的内容，从而与未对 DBusActivatable 字段进行实现的桌面环境兼容。 string NO

实现提示

应用程序操作应得到规范实现者的支持。但是，如果不支持它们，实施者可以简单地忽略操作键和相关的 Desktop Action 操作组，并继续使用 Desktop Entry 组：描述和调用应用程序的主要方式是通过名称、图标和执行键来自 Desktop Entry 组。

格式扩展

如果要增加新的字段，修改现有标准，需要进行小组讨论。 这是引入更改的首选方法。 如果某一方希望添加一个字段供个人使用，他们应该在键前加上字符串 X-PRODUCT (对应 UOS 操作系统系统，应该是 X-DDE )，例如 X-NewDesktop-Foo，遵循其他 IETF 和 RFC 标准设定的先例。

或者，字段可以放在它们自己的组中，然后它们可以有任意的键名。如果是这种情况，该组应该遵循上面概述的方案，即 [X-PRODUCT GROUPNAME]或类似的东西。这些步骤将避免不同但相似的环境之间的命名空间冲突。

Example

A.Desktop Entry File

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[Desktop Entry]
Version=1.0
Type=Application
Name=Foo Viewer
Comment=The best viewer for Foo objects available!
TryExec=fooview
Exec=fooview %F
Icon=fooview
MimeType=image/x-foo;
Actions=Gallery;Create;

[Desktop Action Gallery]
Exec=fooview --gallery
Name=Browse Gallery

[Desktop Action Create]
Exec=fooview --create-new
Name=Create a new Foo!
Icon=fooview-new

B.目前保留在 KDE 中使用的字段

由于历史原因，KDE 使用了一些 KDE 特定的扩展，这些扩展目前没有 X-KDE- 前缀。

  • KDE specific keys: ServiceTypes, DocPath, InitialPreference
  • KDE specific types: ServiceType, Service and FSDevice

KDE 在标准化之前也使用 Keywords 键，使用逗号而不是分号作为分隔符。在标准化时，该字段已经以 X-KDE 前缀为前缀，但 Trinity 分支仍然使用无前缀的变体。

KDE 将以下附加键用于 FSDevice 类型的 desktop entries

FSDevice 特定的 Keys

Key Description Value Type
Dev 要挂载的设备。 string
FSType 尝试挂载的文件系统类型。 string
MountPoint 相关设备的挂载点。 string
ReadOnly 指定设备是否只读。 boolean
UnmountIcon 未安装设备时显示的图标。已安装的设备显示来自 Icon 键的图标。 localestring
 Comments
Comment plugin failed to load
Loading comment plugin
  1. 名词介绍
  2. 介绍
  3. 基础格式
  4. 注释
  5. Group
  6. Entries
  7. 支持的值类型
  8. 公认的桌面入口Key
    1. 标准的 Keys
  9. Exec
  10. 通过 D-Bus 启动
  11. 注册 MIME 类型
  12. 应用的其他动作
    1. 动作标识符
    2. Action 的 Key
  13. 实现提示
  14. 格式扩展
  15. Example
    1. A.Desktop Entry File
    2. B.目前保留在 KDE 中使用的字段
      1. FSDevice 特定的 Keys
  1. 名词介绍
  2. 介绍
  3. 基础格式
  4. 注释
  5. Group
  6. Entries
  7. 支持的值类型
  8. 公认的桌面入口Key
    1. 标准的 Keys
  9. Exec
  10. 通过 D-Bus 启动
  11. 注册 MIME 类型
  12. 应用的其他动作
    1. 动作标识符
    2. Action 的 Key
  13. 实现提示
  14. 格式扩展
  15. Example
    1. A.Desktop Entry File
    2. B.目前保留在 KDE 中使用的字段
      1. FSDevice 特定的 Keys