文件管理上下文右键菜单规范

警告！此规范内容是不稳定版本，可能会发生破坏兼容性的更新。当无法保障向下兼容时，将会升级此文档的主版本号，如从“1.0”更新到“2.0”。反之，普通更新只会升级次版本号，如“1.0”更新到“1.1”，其对“1.0”版本向下兼容。请在使用前确认此文档的版本号，并为将来可能发生的兼容性变化做好准备。

维护者：
- ZhangYu zhangyub@uniontech.com
- LiQiang liqianga@uniontech.com
版本：1.0
修改日期：2022.3.10
议题：

引言

本文档规定了文件管理器（dde-file-manager）和桌面（dde-desktop）扩展右键菜单的配置文件的存储格式和安装路径的规范。

自定义右键菜单包含两种规范：Desktop Entry与Menu Entry

Desktop Entry

简介

Desktop Entry是对freedesktop规范中Desktop Entry Specification的兼容，编写方法与Desktop Entry Specification一致。

配置方法

文件名约束：以desktop为后缀名，如：xxx.desktop
存放路径：
- /usr/etc/deepin/menu-extensions
- /etc/deepin/menu-extensions
文件内容：参考Desktop Entry Specification

将编写完成的desktop文件放到存放路径下，重启后既可生效。

扩展字段

除freedesktop的Desktop Entry Specification中所描述的字段外，本规范还增加了扩展字段来增强右键菜单的过滤功能。

字段	描述	值类型
X-DDE-FileManager-MenuTypes	指定菜单项支持的文件组合形式。可选值：SingleFile，SingleDir，MultiFileDirs，EmptyArea。添加SingleFile表示在选中单个文件时显示菜单，SingleDir表示选中单个文件夹时显示菜单，MultiFileDirs表示选中多个文件或文件夹是显示菜单，EmptyArea表示在空白区（未选中任何文件和文件夹）显示菜单	字符串
X-DDE-FileManager-ExcludeMimeTypes	指定菜单项不支持的文件类型，即当选中的文件的类型在包含该字段指定的MimeType时不显示菜单。	字符串
X-DDE-FileManager-SupportSchemes	指定菜单项支持的Scheme，即当选中元素的URL的Scheme包含在本字段内则显示菜单。	字符串
X-DDE-FileManager-SupportSuffix	指定菜单项支持的文件后缀，即当选中的文件的后缀名包含在本字段内则显示菜单。	字符串
X-DDE-FileManager-NotShowIn	指定菜单项在应用中不显示。可选值：Desktop，Filemanager。Desktop表示在桌面不显示菜单，Filemanager表示在文件管理器中不显示菜单。	字符串

示例

仅一级菜单

[Desktop Entry]
Version=1.0
Type=Application
Name=Open foo
Name[zh_CN]=打开foo
Icon=foo
Exec=/usr/bin/foo %f

#支持的文件类型
MimeType=image/x-foo

#支持xxx.foo文件
X-DDE-FileManager-SupportSuffix=foo

#不在桌面显示
#X-DFM-NotShowIn=Desktop

#file://
X-DDE-FileManager-SupportSchemes=file

#不支持的文件类型
#X-DFM-ExcludeMimeTypes=image/x-foo2

#仅支持单选文件
X-DDE-FileManager-MenuTypes=SingleFile

含二级菜单

[Desktop Entry]
Version=1.0
Type=Application
Actions=Foo1;Foo2;
Name=Foo
Icon=Foo

#文件类型
#MimeType=image/x-foo

#支持xxx.foo文件
X-DDE-FileManager-SupportSuffix=foo

#不在桌面显示
X-DDE-FileManager-NotShowIn=Desktop

#file://
X-DDE-FileManager-SupportSchemes=file

#不支持的文件类型
#X-DDE-FileManager-ExcludeMimeTypes=image/x-foo2

#仅支持单选文件
X-DDE-FileManager-MenuTypes=SingleFile;

[Desktop Action Foo1]
Exec=/usr/bin/foo --foo1 %f
Icon=foo1
Name=Open as foo1
Name[zh_CN]=用foo1打开

[Desktop Action Foo2]
Exec=/usr/bin/foo --foo2 %f
Name=Open as foo2
Name[zh_CN]=用foo2打开
Icon=foo2

兼容

以下存放路径同等有效
- /usr/share/deepin/dde-file-manager/oem-menuextensions
字段别名

字段的别名与其功能一致。

字段	别名
X-DDE-FileManager-MenuTypes	X-DFM-MenuTypes
X-DDE-FileManager-ExcludeMimeTypes	X-DFM-ExcludeMimeTypes
X-DDE-FileManager-SupportSchemes	X-DFM-SupportSchemes
X-DDE-FileManager-NotShowIn	X-DFM-NotShowIn

Menu Entry

简介

Menu Entry是基于Desktop Entry Specification设计的，在文件格式与语法上与Desktop Entry保持一致。Menu Entry对自定义右键菜单增加了更多的可配置项。

配置方法

文件名约束：以conf为后缀名，如：xxx.conf
存放路径：
- /usr/etc/deepin/context-menus
- /etc/deepin/context-menus

将编写完成的conf文件放到存放路径下既可生效。

文件格式

分组

配置文件中必须包含主组**[Menu Entry]，作为整个配置文件的入口。且在[Menu Entry]分组下的Actions对应为一级菜单。其他分组则为由Menu Action加上上级菜单中Actions字段的值组合成新的分组[Menu Action XXX]**，该组描述一个具体的菜单项。每个分组中都可以再包含Actions字段作为子级菜单入口。
Menu Entry组字段

字段	描述	值类型	是否必需	示例
Version	该配置文件使用的规范版本	字符串	必需	Version=1.0
Comment	该配置文件的描述信息	字符串	非必需	Comment=This is a test file!!!
Comment[xxx]	该配置文件的描述本地化的描述信息。	字符串	非必需	Comment[zh_CN]=这是一个测试文件!!!
Actions	一级菜单项分组入口	字符串	必需	Actions=ActionOne:ActionTwo

Menu Action组字段

字段	描述	值类型	是否必需	示例
Name	菜单项的显示名称，支持名称动态参数。	字符串	必需	1. Name=Open 2.动态参数：Name=Open %b
Name[xxx]	菜单项的本地化显示名称，支持名称动态参数。	字符串	非必需	1. Name[zh_CN]=打开 2. 动态参数：Name=[zh_CN]打开 %b
X-DDE-FileManager-PosNum	菜单项期望添加到菜单中的位置，未配置时以配置文件书写顺序排序，依次追加到菜单尾部。	数值	非必需	X-DDE-FileManager-PosNum=1
X-DDE-FileManager-PosNum-XXX	菜单项根据选中的文件组合方式添加到菜单中不同的位置，XXX的值为X-DDE-FileManager-MenuTypes字段的值。	数值	非必需	X-DDE-FileManager-PosNum-SingleFile=1
X-DDE-FileManager-Separator	为菜单项添加分割线，取值为：None，Top，Bottom，Both。依次表示为无分割线，在上方添加分割线，在下方添加分割线，在上下方都添加分割线。	字符串	非必需	X-DDE-FileManager-Separator=Both
Actions	子菜单项分组入口，若配置该字段这表示该菜单包含子菜单项，同时Exec字段为无效。	字符串	非必需	Actions=ActionThree:ActionFour
Exec	菜单项执行动作，支持动态参数。若该分组下同时配置Actions字段，则该字段不生效。	字符串	非必需	1. Exec=/usr/bin/foo 2. 动态参数 Exec=/usr/bin/foo %U

菜单控制字段

该类字段仅在一级Menu Action组中生效，即写在Menu Entry中的Actions。在Menu Action组下的子菜单项Actions不生效，子菜单项跟随一级菜单。

字段	描述	值类型	是否必需	示例
MimeType	指定菜单项支持的文件类型，仅当选中的文件的类型在该字段中时显示菜单项。未配置时或者值为*都作为支持所有文件类型。	字符串	非必需	MimeType=text/plain:text/markdown
X-DDE-FileManager-ExcludeMimeTypes	指定菜单项不支持的文件类型，即当选中的文件的类型在包含该字段指定的MimeType时不显示菜单项。	字符串	非必需	X-DDE-FileManager-ExcludeMimeTypes=text/plain
X-DDE-FileManager-SupportSchemes	指定菜单项支持的Scheme，即当选中元素的URL的Scheme包含在本字段内则显示菜单。	字符串	非必需	X-DDE-FileManager-SupportSchemes=file:ftp
X-DDE-FileManager-NotShowIn	指定菜单项在应用中不显示。可选值：Desktop，Filemanager。Desktop表示在桌面不显示菜单，Filemanager表示在文件管理器中不显示菜单。	字符串	非必需	X-DDE-FileManager-NotShowIn=Desktop
X-DDE-FileManager-SupportSuffix	指定菜单项支持的文件后缀，即当选中的文件的后缀名包含在本字段内则显示菜单。	字符串	非必需	X-DDE-FileManager-SupportSuffix=txt:md
X-DDE-FileManager-MenuTypes	指定菜单项支持的文件组合形式。单个文件(SingleFile)、单个文件夹(SingleDir)、多个文件(MultiFiles)、多个文件(MultiDirs)、文件以及文件夹(FileAndDir)、空白区域（BlankSpace）	字符串	必需	X-DDE-FileManager-MenuTypes=SingleFile:MultiFiles

名称动态参数

名称动态参数用于Name字段中根据指定的参数替换名称内容，以达到菜单项名称中显示文件名称的效果。

参数	描述	示例
%d	右键时所出的文件夹名称。如在/home目录下呼出右键菜单，则该值为home	Name[zh_CN]=在%d打开
%b	右键时焦点文件名称，不包含扩展名和路径。如在/home目录下的text.txt文件呼出右键菜单，则该值为text	Name[zh_CN]=打开%b
%a	右键时焦点文件的完整名称，不包含路径。如在/home目录下的text.txt文件呼出右键菜单，则该值为text.txt	Name[zh_CN]=打开%a

Exec动态参数

Exec动态参数用于Exec字段中根据指定的参数替换命令参数内容，以达到菜单执行命令时获取选中的文件信息。

参数	描述	示例
%p	当前文件夹路径。如在/home目录下呼出右键菜单，则该值为/home	Exec=/usr/bin/foo %p
%f	右键时焦点文件路径。如在/home目录下的text.txt文件呼出右键菜单，则该值为/home/text.txt	Exec=/usr/bin/foo --open-file %f
%F	右键时所有选中文件的路径。如在/home目录下选中text1.txt和text2.txt呼出右键菜单，则该值为/home/text1.txt /home/text2.txt	Exec=/usr/bin/foo --open-files %F
%u	右键时焦点文件URL。如在/home目录下的text.txt文件呼出右键菜单，则该值为file:///home/text.txt	Exec=/usr/bin/foo --open-file %u
%U	右键时所有选中文件的路径。如在/home目录下选中text1.txt和text2.txt呼出右键菜单，则该值为file:///home/text1.txt file:///home/text2.txt	Exec=/usr/bin/foo --open-files %U

约束

Version必须配置，否则该配置文件作为无效文件。
Actions字段与Exec字段为互拆字段，配置了Actions的组不可再增加Exec字段，同时每个Menu Action组必须含有这两个字段中的一个。
一级菜单组Menu Action必须给出X-DDE-FileManager-MenuTypes项，以此来指明支持的选中项类型。
Exec最多可包含一个动态参数。从左至右第一个有效，多余的无效处理。
Menu Action仅支持到三级菜单，即：一级、二级、三级菜单，超过默认不支持，不显示。

示例

#右键菜单入口
[Menu Entry]
#该配置文件采用的规范协议版本
Version=1.0
#描述
Comment=This is a test file!!!
#本地化描述
Comment[zh_CN]=这是一个测试文件
#在[Menu Entry]下包含另外有2个分组,入口名对应为ActionOne和ActionTwo,作为一级菜单
Actions=ActionOne:ActionTwo

[Menu Action ActionOne] 											  						
#菜单名
Name=Menu one %b
Name[zh_CN]=菜单1 %b
#选中单个文件和多个文件时生效
X-DDE-FileManager-MenuTypes=SingleFile:MultiFiles
#支持文件类型
MimeType=image/x-foo:image/x-foo1;
#不支持的文件类型
#X-DDE-FileManager-ExcludeMimeTypes=image/x-foo2:image/x-foo3

#支持file://
X-DDE-FileManager-SupportSchemes=file
#不支持桌面
X-DDE-FileManager-NotShowIn=Desktop

#支持xxx.foo文件
X-DDE-FileManager-SupportSuffix=foo

#默认在右键菜单的一级菜单的第二个位置插入该项
X-DDE-FileManager-PosNum=1
#选中多个文件时在右键菜单的输入第三个位置
X-DDE-FileManager-PosNum-MultiFiles=3
#在该项的上方插入分割线
X-DDE-FileManager-Separator=Top
#菜单执行命令，该一级菜单为执行动作的菜单，无子菜单
Exec=/usr/bin/foo %F

[Menu Action ActionTwo] 											  						
#菜单名
Name=Menu two %d
Name[zh_CN]=菜单2 %d
#在空白区时生效
X-DDE-FileManager-MenuTypes=BlankSpace
#不支持文件管理器
X-DDE-FileManager-NotShowIn=Filemanager
#默认在右键菜单的一级菜单的第三个位置插入该项
X-DDE-FileManager-PosNum=3
#在该项的上下方插入分割线
X-DDE-FileManager-Separator=Both
#菜单包含两个子菜单
Actions=ActionThree:ActionFour

[Menu Action ActionThree] 
Name=Menu three
Name[zh_CN]=菜单3
X-DDE-FileManager-PosNum=1
#菜单执行命令
Exec=/usr/bin/foo --xxx %p

[Menu Action ActionFour] 
Name=Menu four
Name[zh_CN]=菜单4
X-DDE-FileManager-PosNum=2
#菜单执行命令
Exec=/usr/bin/foo --yyy %p

兼容

以下存放路径同等有效
- /usr/share/applications/context-menus
字段别名

字段的别名与其功能一致。

字段	别名
X-DDE-FileManager-PosNum	PosNum
X-DDE-FileManager-PosNum-XXX	PosNum-XXX
X-DDE-FileManager-Separator	Separator
X-DDE-FileManager-MenuTypes	X-DFM-MenuTypes
X-DDE-FileManager-ExcludeMimeTypes	X-DFM-ExcludeMimeTypes
X-DDE-FileManager-SupportSchemes	X-DFM-SupportSchemes
X-DDE-FileManager-NotShowIn	X-DFM-NotShowIn

参考

Desktop Entry Specification