桌面条目文件规范
原文鏈接
介紹
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. 區域設置匹配
| 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轉載于:https://my.oschina.net/u/1248114/blog/3065631
總結
- 上一篇： 电路中极性与非极性电容并联的作用
- 下一篇： 独享云虚拟主机、共享云虚拟主机、云服务器