Definieren von Aktionen für Dateihandler der Version 2.0

Bei der Registrierung eines Dateihandlers definieren Sie einen Satz von Aktionen, deren Ausführung der Dateihandler ermöglicht.

Es gibt drei integrierte Aktionen, die ein Dateihandler unterstützen kann:

• newFile: Der Dateityp wird im Menü Neu in OneDrive und SharePoint angezeigt.
• open: Der Dateihandler kann Dateien öffnen. Er wird im Menü Öffnen in OneDrive und SharePoint angezeigt. Aktionen des Typs „Öffnen“werden in einer neuen Browserregisterkarte gestartet.
• preview: Der Dateihandler kann eine Dateivorschau anzeigen. Die Vorschau wird angezeigt, wenn der Benutzer mit der linken Maustaste auf eine Datei in OneDrive oder SharePoint klickt. Vorschauaktionen werden in einem Element des Typs <IFRAME> innerhalb der OneDrive- bzw. SharePoint-Website geladen.
• custom: Dateien können einen Dateihandler verwenden, um von der Anwendung definierte Aktionen zu erstellen. Diese zusätzlichen Aktionen werden in der Symbolleiste in OneDrive und SharePoint angezeigt und lassen sich jeder beliebigen Dateierweiterung hinzufügen.

Definieren von Aktionen im Dateihandlermanifest

Aktionen werden im Dateihandlermanifest im Schlüssel-Wert-Paar actions definiert. Es enthält ein Array mit den Aktionen, die der Dateihandler unterstützt.

Hier ein Beispiel für die Definition der drei integrierten Aktionen sowie einer benutzerdefinierten Aktion:

[
    {
        "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": { }
        }
    }
]

Aufgrund von Einschränkungen bei den Azure Active Directory-Add-In-Erweiterungen werden diese Aktionen serialisiert in einer Zeichenfolge gespeichert. Es empfiehlt sich, den JSON-Code des Arrays zu minimieren, bevor Sie es für die Speicherung im Manifest in einen Zeichenfolgenwert konvertieren.

Die oben definierten Aktionen beispielsweise würden in folgender Form im Dateihandlermanifest gespeichert werden:

{
    "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\":{}}}]"
        }
    ]
}

Aktionsparameter

Jede im Aktionsparameter deklarierte Aktion hat folgendes Format:

{
    "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" }
    }
}

Eigenschaften

Je nach dem Typ der definierten Aktion sind nicht alle Eigenschaften erforderlich.

Parametername	Typ	Beschreibung
type	string	Ein Wert von newFile, custom, openoder preview. Erforderlich.
url	URL	Eine URL des Typs https:// zu dem Endpunkt, der die Dateihandleraktion behandelt. Erforderlich.
displayName	string	Eine Standardgebietsschemazeichenfolge, die verwendet wird, um die Aktion darzustellen. Optional. Der Standardwert ist "Im Browser öffnen" für type: "open".
shortDisplayName	string	Eine Standardgebietsschemazeichenfolge, die verwendet wird, um die Aktion in der Symbolleiste oder im reduzierten Aktionsmenü darzustellen. Optional.
availableOn	object	Eine Sammlung von Eigenschaften, die definieren, worauf die Aktion angewendet werden kann. Erforderlich.
Symbol	displayIcon	Ein Objekt mit URLs zu Symbolbilder für diesen Dateityp. Optional.

AvailableOn-Eigenschaften

Durch Festlegen von Eigenschaften innerhalb der availableOn-Eigenschaft können Sie anpassen, wo die Aktion verfügbar ist:

Parametername	Typ	Beschreibung
file.extensions	array of strings	Ein Array mit den Dateierweiterungen, auf die die Aktion angewendet werden kann. Die Dateierweiterungen müssen mit einem Punkt (.) beginnen. Bei benutzerdefinierten Aktionen können Sie mit einem Platzhalterzeichen (*) festlegen, dass alle Dateierweiterungen unterstützt werden.
folder	object	Ein Objekt ohne Parameter gibt an, dass der Dateihandler verfügbar ist, wenn ein Ordner ausgewählt wird oder wenn keine Dateien ausgewählt werden. Ist ein Nullwert gesetzt oder ist die Eigenschaft nicht definiert, ist die Aktion für Ordner nicht verfügbar.
allowMultiSelect	boolean	Wenn diese Eigenschaft auf true gesetzt ist, wird die Aktion auch bei Auswahl mehrerer Dateien angezeigt. Wenn die Eigenschaft auf false gesetzt ist oder fehlt, wird die Aktion nur bei Auswahl eines einzelnen Elements angezeigt.
web	object	Ein Objekt ohne Parameter gibt an, dass der Dateihandler verfügbar ist, wenn die Website durchsucht wird.

• Für Aktionen des Typs newFile kann nur eine einzige Dateierweiterung definiert werden. Dies ist die Erweiterung, die die neu erstellte Datei haben wird. Sollten mehrere Dateierweiterungen aufgeführt sein, wird nur die erste Dateierweiterung verwendet.
• Die Eigenschaften folder und allowMultiSelect sind nur für Aktionen des Typs custom verfügbar. Für Aktionen anderen Typs werden diese Werte ignoriert.