桌面條目文件規範

原文連接

介紹

KDE和GNOME桌面環境都採用了相似的」桌面條目」格式，或描述特定程序如何啓動的配置文件，它在菜單中的顯示方式等。統一標準對更大的社區有利。 全部各方都贊成這樣作，即兩個環境之間的互操做，以及實現規範的任何其餘環境變得更加簡單。

文件命名

桌面條目文件應具備.desktop擴展名，但類型目錄的文件除外，該文件應具備.directory擴展名。基於擴展肯定文件類型使得肯定文件類型很是容易和快速。當沒有文件擴展名時，桌面系統應經過「魔術檢測」來後備識別。

對於應用程序，.desktop擴展名以前的桌面文件名稱部分應該是有效的D-Bus知名名稱。這意味着它是由點（U+002E FULL STOP）分隔的非空元素序列，其中沒有一個以數字開頭，而且每一個元素僅包含來自集合的字符[A-Za-z0-9- _]：ASCII字母，數字，短劃線（U+002D HYPHEN-MINUS）和下劃線（U+002D HYPHEN-MINUS）。

桌面條目的名稱應遵循「反向DNS」約定：它應以應用程序做者控制的反向DNS域名開頭，小寫。域名後面應該跟應用程序的名稱，一般用合併的單詞和首字母大寫字母（CamelCase）編寫。例如，若是exam​​ple.org的全部者編寫「Foo Viewer」，他們可能會選擇名稱org.example.FooViewer，結果是名爲org.example.FooViewer.desktop的文件。

容許使用包含短劃線的已知名稱，但不建議這樣作，由於在反向DNS名稱的某些相關用途中不容許使用短劃線，例如D-Bus對象路徑和接口名稱以及Flatpak應用程序ID。若是做者的域名包含短劃線，建議將其替換爲下劃線：這不會致使歧義，由於DNS域名中不容許使用下劃線。

若是做者的域名包含以數字開頭的元素（在D-Bus知名名稱中不容許），建議在桌面條目名稱的該元素前加下劃線。例如，7-zip.org可能會發布名爲org._7_zip.Archiver的應用程序。

桌面文件 ID

表示應用程序的每一個桌面條目由其桌面文件ID標識，該文件ID基於其文件名。

要肯定桌面文件的ID，請相對於安裝桌面文件的$XDG_DATA_DIRS組件建立其完整路徑，刪除「applications/」前綴，而後將「/」變爲「-」。例如/usr/share/applications/foo/bar.desktop具備桌面文件ID foo-bar.desktop。

若是多個文件具備相同的桌面文件ID，則使用$XDG_DATA_DIRS優先順序中的第一個。例如，若是$ XDG_DATA_DIRS包含默認路徑/usr/local/share:/usr/share，那麼/usr/local/share/applications/org.foo.bar.desktop和/usr/share/applications/org.foo.bar.desktop都具備相同的桌面文件ID org.foo.bar.desktop，但只會使用第一個。若是foo-bar.desktop和foo/bar.desktop都存在，則選擇未定義。

若是桌面文件未安裝在$XDG_DATA_DIRS組件之一的applications子目錄中，則它沒有ID。

文件的基本格式

桌面條目文件以UTF-8編碼。 文件被解釋爲由換行符分隔的一系列行。 文件中字母大小寫是有意義的。

兼容的實現毫不能從文件中刪除任何字段，即便它們不支持它們。 這些字段必須保存在某個列表中，若是文件被「重寫」，它們將被包含在內。 這可確保即便其餘系統訪問和更改文件，也會保留任何特定於桌面的擴展。

註釋

以#開頭的行被視爲註釋，將被忽略，可是應該在桌面條目文件的讀寫期間保留它們。

註釋行不被解析，可能包含任何字符（LF除外）。 可是，鼓勵將UTF-8用於包含非ASCII字符的註釋行。

組頭部

名稱爲groupname的組頭部是如下格式的行：

[groupname]

組名能夠包含除[和]和控制字符之外的全部ASCII字符。

多個組可能沒有相同的名稱。

在組頭部以後的全部{key，value}對，直到新的組頭部屬於該組。

桌面條目文件的基本格式要求有一個名爲Desktop Entry的組頭部。 文件中可能存在其餘組，但這是明確須要支持的最重要的組。 該組還應該用做自動MIME類型檢測的「魔術鍵」。 桌面條目文件中此組以前應該沒有任何內容，但可能有一行或多行註釋。

條目

文件中的條目是{key，value}對，格式以下：

Key=Value

等號以前和以後的空格應該被忽略; =符號是實際的分隔符。

在鍵名中只能使用字符A-Za-z0-9-。

因爲大小寫是有意義的，鍵 Name 和 NAME 是不一樣的。

同一組中的多個鍵可能不具備相同的名稱。不一樣組中的鍵可能具備相同的名稱。

可能的值類型

識別的值類型是string，localestring，boolean和numeric。

• string類型的值能夠包含除控制字符以外的全部ASCII字符。

• localestring類型的值是可向用戶顯示的，並以UTF-8編碼。

• boolean類型的值必須是字符串true或false。

• numeric類型的值必須是有效的浮點數，由C語言環境中scanf的%f說明符識別。

轉義序列\s，\n，\t，\r和\支持string和localestring類型的值，分別表示ASCII空格，換行符，製表符，回車符和反斜槓。

某些鍵能夠有多個值。在這種狀況下，鍵的值被指定爲複數：例如，多個字符串。多個值應該用分號分隔，鍵的值能夠選擇用分號結束。尾隨空字符串必須始終以分號結束。這些值中的分號須要使用;進行轉義。

鍵的本地化值

類型爲localestring的鍵能夠由[LOCALE]後綴，其中LOCALE是條目的語言環境類型。 LOCALE的格式必須爲lang_COUNTRY.ENCODING@MODIFIER，其中可省略_COUNTRY，.ENCODING和@MODIFIER。若是出現加後綴的鍵，則必須同時存在不加後綴的相同的鍵。

在桌面條目文件中讀取時，經過將LC_MESSAGES類別的當前POSIX語言環境與鍵的全部LOCALE後綴相匹配來選擇鍵的值。

匹配以下進行。若是LC_MESSAGES的格式爲lang_COUNTRY.ENCODING@MODIFIER，則它將匹配lang_COUNTRY@MODIFIER格式的鍵。若是這樣的鍵不存在，它將嘗試匹配lang_COUNTRY，而後是lang@MODIFIER。而後，將嘗試與lang自己進行匹配。最後，若是未找到匹配的密鑰，則使用未指定區域設置的所需鍵。匹配時忽略LC_MESSAGES值的編碼。

若是LC_MESSAGES沒有MODIFIER字段，則不會匹配帶修飾符的鍵。一樣，若是LC_MESSAGES沒有COUNTRY字段，則不會匹配指定國家/地區的鍵。若是LC_MESSAGES只有一個lang字段，那麼它將與具備類似值的鍵進行直接匹配。下表按照匹配順序列出了各類LC_MESSAGES值的可能匹配項。請注意，未顯示ENCODING字段。

表1. 區域設置匹配

LC_MESSAGES值	可能的鍵按匹配順序排列
lang_COUNTRY@MODIFIER	lang_COUNTRY@MODIFIER, lang_COUNTRY, lang@MODIFIER, lang, 默認值
lang_COUNTRY	lang_COUNTRY, lang, 默認值
lang@MODIFIER	lang@MODIFIER, lang, 默認值
lang	lang, 默認值

例如，若是LC_MESSAGES類別的當前值是sr_YU@Latn，而且桌面文件包括：

Name=Foo
Name[sr_YU]=...
Name[sr@Latn]=...
Name[sr]=...

則 Name 的值用[sr_YU]後綴的。

識別的桌面條目鍵

鍵是可選的或必需的。 若是鍵是可選的，則它可能存在也可能不存在於文件中。 可是，若是不是，標準的實現不該該崩潰，它必須提供一些理智的默認值。

某些鍵僅在上下文中另外一個特定鍵也存在並設置爲特定值纔有效。 若是特定鍵不存在或未設置爲特定值，則不該使用這些鍵。 例如，只有在Type鍵的值爲Application時才能使用Terminal鍵。

若是必需鍵僅在另外一個設置爲特定值的鍵的上下文中有效，則只有在另外一個鍵設置爲特定值時才必須存在。 例如，當且僅當Type鍵的值爲Link時，必須存在URL鍵。

一些示例鍵：Name[C]，Comment[it]。

鍵	描述	值類型	必需？
Type	此規範定義了3種類型的桌面條目：Application（應用程序，類型1），Link（連接，類型2）和Directory（目錄，類型3）。 爲了容許未來添加新類型，實現應忽略具備未知類型的桌面條目。	string	是
Version	桌面條目符合的桌面條目規範的版本。 使用此版本規範確認的條目應使用1.1。 請注意，不須要存在版本字段。	string	否
Name	應用程序的特定名稱，例如「Mozilla」。	localestring	是
GenericName	應用程序的通用名稱，例如「Web 瀏覽器」。	localestring	否
NoDisplay	表示「此應用程序存在，但不在菜單中顯示」。 這可用於例如 將此應用程序與MIME類型相關聯，以便從文件管理器（或其餘應用程序）啓動它，而無需爲其提供菜單條目（有不少很好的理由，包括例如netscape -remote或kfmclient openURL類型 的東西）。	boolean	否
Comment	該條目的工具提示，例如「查看Internet上的站點」。 該值不該該和 Name和GenericName的值重複。	localestring	否
Icon	要在文件管理器，菜單等中顯示的圖標。若是名稱是絕對路徑，則將使用給定文件。 若是名稱不是絕對路徑，則將使用圖標主題規範中描述的算法來定位圖標。	localestring	否
Hidden	隱藏應該被稱爲已刪除。 這意味着用戶刪除了（在他的級別）存在的東西（在較高級別，例如在系統目錄中）。 就用戶而言，它徹底等同於根本不存在的.desktop文件。 這也可用於「卸載」現有文件（例如，因爲重命名） - 讓make install安裝一個Hidden = true的文件。	boolean	否
OnlyShowIn, NotShowIn	標識應顯示/不顯示給定桌面條目的桌面環境的字符串列表。<br>默認狀況下，應顯示桌面文件，除非存在OnlyShowIn鍵，在這種狀況下，默認狀況下不顯示該文件。<br> 若是設置了$XDG_CURRENT_DESKTOP，則它包含以冒號分隔的字符串列表。 按順序，考慮每一個字符串。 若是在OnlyShowIn中找到匹配的條目，則顯示桌面文件。 若是在NotShowIn中找到條目，則不顯示桌面文件。 若是沒有任何字符串匹配，則採用默認操做（如上所述）。<br> $XDG_CURRENT_DESKTOP應該由登陸管理器根據會話文件中找到的DesktopNames的值設置。 會話文件中的條目有多個值時一般以分號「:」分隔。<br> 相同的桌面名稱可能不會同時出如今組的OnlyShowIn和NotShowIn中。	string(s)	否
DBusActivatable	指定此應用程序是否支持D-Bus激活。 若是缺乏此鍵，則默認值爲false。 若是值爲true，則實現應忽略Exec鍵併發送D-Bus消息以啓動應用程序。 有關其工做原理的詳細信息，請參閱D-Bus激活。 應用程序仍應在其桌面文件中包含Exec =行，以便與不理解DBusActivatable鍵的實現兼容。	boolean	否
TryExec	磁盤上可執行文件的路徑，用於肯定程序是否實際安裝。 若是路徑不是絕對路徑，則在$PATH環境變量中查找該文件。 若是文件不存在或者文件不可執行，則能夠忽略該條目（例如，不在菜單中使用）。	string	否
Exec	要執行的程序，可能帶有參數。 有關此鍵如何工做的詳細信息，請參閱Exec鍵。 若是DBusActivatable未設置爲true，則須要Exec鍵。 即便DBusActivatable爲true，爲了避免理解DBusActivatable的實現的兼容性也應指定Exec。
Path	若是條目是Application類型，則是運行該程序的工做目錄。	string	否
Terminal	程序是否在終端窗口中運行。	boolean	否
Actions	應用程序操做的標識符。 這能夠用於告訴應用程序進行特定操做，與默認行爲不一樣。 應用程序操做部分描述了操做的工做方式。	string(s)	否
MimeType	此應用程序支持的MIME類型。	string(s)	否
Categories	應在菜單中顯示條目的類別（有關可能的值，請參閱桌面菜單規範）。	string(s)	否
Implements	此應用程序實現的接口列表。 默認狀況下，桌面文件不實現任何接口。 有關其工做原理的詳細信息，請參閱接口。	string(s)	否
Keywords	除了描述此條目的其餘元數據以外可使用的字符串列表。 這多是有用的，例如便於搜索條目。 這些值不用於顯示，而且不該該與Name或GenericName的值重複。	localestring(s)	否
StartupNotify	若是爲true，則表示應用程序在使用DESKTOP_STARTUP_ID環境變量集啓動時將發送「刪除」消息。 若是爲false，則表示該應用程序根本不適用於啓動通知（未顯示任何窗口，即便在使用StartupWMClass時也會破壞等）。 若是不存在，則合理的處理取決於實現（假設爲false，使用StartupWMClass等）。 （有關更多詳細信息，請參閱「啓動通知協議規範」）。	boolean	否
StartupWMClass	若是指定，則已知應用程序將會映射至少一個具備給定字符串爲其WM類或WM名稱提示的窗口（有關更多詳細信息，請參閱啓動通知協議規範）。	string	否
URL	若是條目是連接類型，則是要訪問的URL。	string	是

Exec 鍵

Exec鍵必須包含命令行。 命令行由可執行程序組成，可選地後跟一個或多個參數。 可執行程序可使用其完整路徑指定，也能夠僅使用可執行文件的名稱指定。 若是未提供完整路徑，則在桌面環境使用的$PATH環境變量中查找可執行文件。 可執行程序的名稱或路徑可能不包含等號（「=」）。 參數由空格分隔。

參數能夠所有引發來（後稱爲引用）。 若是參數包含保留字符，則必須引用該參數。 引用參數的規則也適用於提供的可執行程序的可執行文件名或路徑。

引用必須經過在雙引號之間包含參數並轉義雙引號字符(「"」)，反引號字符（「`」），美圓符號（「$」）和反斜槓字符（「\」），並在其前面添加一個反斜槓字符來完成。 實現必須在擴展字段代碼以前和將參數傳遞給可執行程序以前解開引用。 保留字符爲空格（「 」），製表符，換行符，雙引號(「"」)，單引號（「'」），反斜槓字符（「\」），大於號（「>」），小於號（「<」 ），波浪號（「~」），豎條（「|」），and符號（「&」），分號（「;」），美圓符號（「$」），星號（「*」），問號（「?「），哈希標記（」#「），括號（」(「）和（」)「）和反引號字符（」`「）。

請注意，string類型值的常規轉義規則代表反斜槓字符也能夠轉義爲（「\」），而且在引用規則以前應用此轉義規則。 所以，要明確表示桌面條目文件中帶引號的參數中的文字反斜槓字符，須要使用四個連續的反斜槓字符（「\\」）。 一樣，桌面條目文件中帶引號的參數中的文字美圓符號用（「\$」）明確表示。

已經定義了許多特殊的字段代碼，當在命令行中遇到時，它們將由文件管理器或程序啓動器擴展。 字段代碼由百分比字符（「%」）後跟字母字符組成。 必須將文字百分比字符轉義爲%%。 應從命令行中刪除不推薦使用的字段代碼並將其忽略。 字段代碼僅擴展一次，不該檢查用於替換字段代碼的字符串的字段代碼自己。

包含未在此規範中列出的字段代碼的命令行無效且不得處理，特別是實現可能不會引入對本規範中未列出的字段代碼的支持。 若是有的話，應該經過新鍵引入擴展。

除非本規範明確指示，不然實現必須注意不要將字段代碼擴展爲多個參數。 這意味着能夠包含空格的名稱字段，文件名和其餘替換項必須在擴展後做爲單個參數傳遞給可執行程序。

儘管Exec鍵被定義爲具備string類型的值（僅限於ASCII字符），但字段代碼擴展可能會在參數中引入非ASCII字符。 實現必須注意傳遞給可執行程序的參數中的全部字符都根據適用的語言環境設置進行了正確編碼。

識別的字段代碼以下：

代碼	描述
%f	單個文件名（包括路徑），即便選擇了多個文件也是如此。 讀取桌面條目的系統應該識別出有問題的程序沒法處理多個文件參數，若是程序沒法處理其餘文件參數，它應該應該爲每一個選定文件生成並執行程序的多個副本。 若是文件不在本地文件系統上（即在HTTP或FTP位置），則文件將被複制到本地文件系統，%f將擴展爲指向臨時文件。 用於不瞭解URL語法的程序。
%F	文件列表。 用於能夠一次打開多個本地文件的應用程序。 每一個文件做爲單獨的參數傳遞給可執行程序。
%u	一個URL。 本地文件能夠做爲 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環境變量中的值相同的字符串，如啓動通知協議規範所指定的。

接口

Implements鍵可用於聲明桌面文件實現的一個或多個接口。

每一個接口名稱必須遵循用於D-Bus接口名稱的規則，但除此以外，它們沒有特別的含義。 例如，在此列出接口並不必定意味着該應用程序實現了D-Bus接口，甚至不存在這樣的D-Bus接口。 徹底由定義特定接口的實體來定義實現它的意義。

雖然徹底取決於接口的設計者來決定給定的接口名稱的含義，但這裏有一些推薦的「最佳實踐」：

• 接口應該要求應用程序是能夠DBusActivatable的，包括使用D-Bus「反向DNS」約定命名應用程序的桌面文件的要求
• 接口名稱應對應於應用程序在導出org.freedesktop.Application接口時在同一對象路徑上導出的D-Bus接口
• 若是接口但願容許有關實現的詳細信息，則應經過指定實現者在其桌面文件中添加與接口同名的組來實現（例如：[org.freedesktop.ImageAcquire]）

儘管建議，接口能夠指定幾乎任何能夠想象的要求，包括這樣（荒謬）的事情，「當經過Exec行啓動時，應用程序應該呈現一個設置了_FOO_IDENTIFIER屬性的窗口，此時將發送一個X客戶端消息到那個窗口「。 另外一個例子是「此接口的全部實現都應該標記爲NoDisplay，而且在啓動時，不會顯示任何窗口，而且將在不確認的狀況下刪除全部用戶的文件」。

接口定義者在設計接口時應注意保持向後和向前兼容性問題。

註冊MIME類型

MimeType鍵用於指示應用程序知道如何處理的MIME類型。 對於某些應用程序，預計此列表可能會變長。 指望應用程序可以使用Exec鍵中列出的命令合理地打開這些類型的文件。

此字段中的MIME類型或桌面文件中的任何形式的優先級都不該該具備優先級。 應用程序的優先級在.desktop文件以外處理。

附加應用程序操做

Application類型的桌面條目能夠包括一個或多個操做。 操做表示調用應用程序的其餘方法。 應用程序啓動器應該在應用程序的上下文中將它們公開給用戶（例如，做爲子菜單）。 這用於構建所謂的「快速列表」或「跳轉列表」。

操做標識符

每一個操做都由一個字符串標識，其格式與鍵名相同（請參閱「條目」一節）。 每一個標識符都與必須存在於.desktop文件中的操做組相關聯。操做組是名爲Desktop Action %s的組，其中%s是操做標識符。

Actions鍵中未說起的操做標識符的操做組無效。實現者必須忽略這樣的操做組。

操做的鍵

每一個操做組中都支持如下鍵。 若是操做組中不存在必需鍵，則實現者應忽略此操做。

表3.特定於操做的鍵

鍵	描述	值類型	必需？
Name	將顯示給用戶的標籤。 因爲操做始終顯示在特定應用程序的上下文中（即，做爲啓動程序的子菜單），所以這隻須要在應用程序中明確，而且不該包含應用程序名稱。	localestring	是
Icon	與操做一塊兒顯示的圖標。 若是值是絕對路徑，則將使用給定文件。 若是值不是絕對路徑，則將使用圖標主題規範中描述的算法來定位圖標。 實現可能會選擇忽略它。	localestring	否
Exec	執行此操做的程序，可能帶參數。有關此鍵如何工做的詳細信息，請參閱Exec鍵。 若是主桌面條目組中的DBusActivatable未設置爲true，則須要Exec鍵。 即便DBusActivatable爲true，爲了避免理解DBusActivatable的實現的兼容性也應該指定Exec。	string	否

實施說明

應用程序操做應該由實現者支持。 可是，若是不支持它們，實現者能夠簡單地忽略Actions鍵和關聯的Desktop Action操做組，並繼續使用Desktop Entry組：描述和調用應用程序的主要方法是經過Desktop Entry組的Name，Icon和Exec鍵。

預計顯示應用程序列表的其餘桌面組件（例如軟件安裝程序）不會爲這些操做提供任何用戶界面。 所以，應用程序必須僅包含做爲通用發·射器有意義的操做。

擴展格式

若是要使用適用於全部支持方的新{key，value}對修改標準，則將進行小組討論。 這是引入更改的首選方法。 若是一個特定的一方但願添加一個供我的使用的字段，他們應該在密鑰前面添加字符串X-PRODUCT，例如： X-NewDesktop-Foo，遵循其餘IETF和RFC標準設定的先例。

或者，能夠將字段放在它們本身的組中，而後它們能夠具備任意鍵名。 若是是這種狀況，該組應遵循上述方案，即[X-PRODUCT GROUPNAME]或相似的東西。 這些步驟將避免不一樣但類似的環境之間的命名空間衝突。

示例桌面條目文件

[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