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

项目
04/08/2023

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

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

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	`newFile`、`open` 或 `preview` 的值。必需。
url	URL	处理文件处理程序操作的终结点的 `https://` URL。必需。
displayName	string	用于 `type: "custom"` 的默认区域设置字符串，以表示操作。可选。
shortDisplayName	string	供 `type: "custom"` 用于表示工具栏或折叠操作菜单中的操作的默认区域设置字符串。可选。
availableOn	object	定义此操作的可用位置的属性集合。必需。
icon	displayIcon	包含此文件类型的图标图像 URL 的对象。可选。

displayName 属性仅适用于 custom 类型的操作。任何其他类型的操作均忽略此属性。

AvailableOn 属性

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

参数名称	类型	说明
file.extensions	array of strings	操作适用的一组文件扩展名。文件扩展名必须以句点 (.) 开头。通配符 `*` 可用于指明自定义操作的所有文件扩展名。
folder	object	不包含任何参数的对象，指明在选择文件夹或未选择任何文件时文件处理程序可用。如果值为 null 或未定义此属性，则表明操作不适用于文件夹。
allowMultiSelect	boolean	如果为 `true`，可以选择多个文件，并且操作仍会显示。如果为 `false` 或未定义，那么操作仅在选择一个项时显示。
web	object	没有参数的对象表示浏览网站时文件处理程序可用。

只能为 newFile 类型操作指定一个文件扩展名。这是新创建的文件的扩展名。如果列出了多个文件扩展名，只会使用第一个文件扩展名。
folder 和 allowMultiSelect 属性仅适用于 custom 类型操作。对于其他任何类型操作，这些值均被忽略。

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

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

操作参数

属性

AvailableOn 属性

其他资源