文件管理上下文右键菜单规范
2022-08-10 18:52:32

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

引言

本文档规定了文件管理器(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

参考