指定文件处理程序 2.0 的操作

注册文件处理程序时,可以指定文件处理程序启用的一组操作。

文件处理程序可以选择支持三个内置操作:

  • newFile:文件类型显示在 OneDrive 和 SharePoint 的“新建”菜单中。
  • open:可以通过文件处理程序打开文件,文件类型显示在 OneDrive 和 SharePoint 的“打开”菜单中。 Open 操作是在新的浏览器选项卡中启动。
  • preview:可以通过文件处理程序预览文件。 preview 操作在用户左键单击 OneDrive 和 SharePoint 中的文件时启动。 preview 操作在 OneDrive 和 SharePoint 网站内的 <IFRAME> 元素中加载。
  • custom:文件可以使用文件处理程序创建应用程序定义的操作。 其他这些操作显示在 OneDrive 和 SharePoint 工具栏中,并可添加到任意扩展名的文件中。

在文件处理程序清单中定义操作

操作是在文件处理程序清单中的 actions 键值对内定义,此键值对包含文件处理程序支持的一组操作。

三个内置操作和一个自定义操作的定义示例:

[
    {
        "type": "newFile",
        "url": "https://url/for/endpoint",
        "availableOn": {
            "file": { "extensions": [".bin"] },
            "web": { }
        }
    },
    {
        "type": "open",
        "url": "https://url/for/endpoint",
        "availableOn": {
            "file": { "extensions": [".bin"] },
            "web": { }
        }
    },
    {
        "type": "preview",
        "url": "https://url/for/endpoint",
        "availableOn": {
            "file": { "extensions": [".bin"] },
            "web": { }
        }
    },
    {
        "type": "custom",
        "url": "https://url/for/endpoint",
        "displayName": "Add Signature with Contoso",
        "shortDisplayName": "Add Signature",
        "icon": {
            "png1x": "https://url/for/icon.png"
        },
        "availableOn": {
            "file": { "extensions": ["*"] },
            "folder": { },
            "allowMultiSelect": true,
            "web": { }
        }
    }
]

由于 Azure Active Directory 外接程序扩展存在限制,因此这些操作以序列化形式存储到字符串中。 建议先对数组执行 JSON 缩小操作,然后再将其转换成清单中存储的字符串值。

例如,上面定义的操作将存储在文件处理程序清单中,如下所示:

{
    "type": "FileHandler",
    "properties": [
        {
            "key": "version",
            "value": "2"
        },
        {
            "key": "actions",
            "value": "[{\"type\":\"newFile\",\"url\":\"https://url/for/endpoint\",\"availableOn\":{\"file\":{\"extensions\":[\".bin\"]},\"web\":{}}},{\"type\":\"open\",\"url\":\"https://url/for/endpoint\",\"availableOn\":{\"file\":{\"extensions\":[\".bin\"]},\"web\":{}}},{\"type\":\"preview\",\"url\":\"https://url/for/endpoint\",\"availableOn\":{\"file\":{\"extensions\":[\".bin\"]},\"web\":{}}},{\"type\":\"custom\",\"url\":\"https://url/for/endpoint\",\"displayName\":\"Add Signature with Contoso\",\"shortDisplayName\":\"Add Signature\",\"icon\":{\"png1x\":\"https://url/for/icon.png\"},\"availableOn\":{\"file\":{\"extensions\":[\"*\"]},\"folder\":{},\"allowMultiSelect\":true,\"web\":{}}}]"
        }
    ]
}

操作参数

操作参数中声明的每个操作均使用以下形状:

{
    "type": "newFile | open | preview | custom",
    "url": "url",
    "displayName": "string",
    "shortDisplayName": "string",
    "icon": { 
        "@odata.type": "microsoft.graph.displayIcon",
        "svg": "url",
        "png1x": "url",
        "png1_5x": "url",
        "png2x": "url"
    },
    "availableOn": {
        "@odata.type": "microsoft.graph.availableOn",
        "file": {
            "@odata.type": "microsoft.graph.availableOnFile",
            "extensions": [ ".pdf", ".png", ".psd" ]
        },
        "folder": {
            "@odata.type": "microsoft.graph.availableOnFolder"
        },
        "allowMultiSelect": false,
        "web": { "@odata.type": "microsoft.graph.availableOnWeb" }
    }
}

属性

并非所有属性都是必需属性,具体视指定的操作类型而定。

参数名称 类型 说明
类型 string 值 、newFilecustomopenpreview。 必填。
url URL 处理文件处理程序操作的终结点的 https:// URL。 必需。
displayName string 用于表示操作的默认区域设置字符串。 可选。 默认为 type: "open"“在浏览器中打开”。
shortDisplayName string 用于表示工具栏或折叠操作菜单中的操作的默认区域设置字符串。 可选。
availableOn object 定义此操作的可用位置的属性集合。 必需。
icon displayIcon 包含此文件类型的图标图像 URL 的对象。 可选。

AvailableOn 属性

通过在 availableOn 属性中设置属性,可以自定义操作可用的位置:

参数名称 类型 说明
file.extensions array of strings 操作适用的一组文件扩展名。 文件扩展名必须以句点 (.) 开头。 通配符 * 可用于指明自定义操作的所有文件扩展名。
folder object 不包含任何参数的对象,指明在选择文件夹或未选择任何文件时文件处理程序可用。 如果值为 null 或未定义此属性,则表明操作不适用于文件夹。
allowMultiSelect boolean 如果为 true,可以选择多个文件,并且操作仍会显示。 如果为 false 或未定义,那么操作仅在选择一个项时显示。
web object 没有参数的对象表示浏览网站时文件处理程序可用。
  • 只能为 newFile 类型操作指定一个文件扩展名。 这是新创建的文件的扩展名。 如果列出了多个文件扩展名,只会使用第一个文件扩展名。
  • folderallowMultiSelect 属性仅适用于 custom 类型操作。 对于其他任何类型操作,这些值均被忽略。