Especificar acciones para los controladores de archivos 2.0Specifying actions for file handlers 2.0

Al registrar un controlador de archivos, especifica un conjunto de acciones permitidas mediante el controlador de archivos.When registering a file handler, you specify a set of actions enabled by the file handler.

Existen tres acciones integradas que un controlador de archivos puede admitir:There are three built-in actions that a file handler can choose to support:

  • newFile: El tipo de archivo aparece en el menú Nuevo de OneDrive y SharePoint.newFile: File type appears in the New menu in OneDrive and SharePoint.
  • open: Los archivos pueden abrirse con el controlador de archivos, que aparece en el menú Abrir de OneDrive y SharePoint. Las acciones de apertura se inician en una nueva pestaña del explorador.open: Files can be opened by the file handler, which appears in the Open menu in OneDrive and SharePoint. Open actions are launched in a new browser tab.
  • preview: Los archivos pueden previsualizarse con el controlador de archivos. La vista previa se produce cuando el usuario hace clic con el botón izquierdo en un archivo de OneDrive y SharePoint. Las acciones de vista previa se cargan en un elemento <IFRAME> dentro de los sitios web de OneDrive y SharePoint.preview: Files can be previewed by the file handler. Preview occurs when the user left-clicks on a file in OneDrive and SharePoint. Preview actions are loaded in an <IFRAME> element inside the OneDrive and SharePoint websites.

Los controladores de archivos adicionales admiten un tipo de acción custom que permite que un controlador de archivos cree acciones definidas por la aplicación. Estas acciones adicionales aparecen en la barra de herramientas de OneDrive y SharePoint, y pueden agregarse en cualquier extensión de archivo.Additional file handlers support a custom action type which allows a file handler to create application defined actions. These additional actions appear in the toolbar in OneDrive and SharePoint, and can be added to any file extension.

Definir acciones en el manifiesto del controlador de archivosDefining actions in the file handler manifest

Las acciones se definen en el manifiesto del controlador de archivos dentro del par clave-valor actions, que contiene una matriz de acciones que admite el controlador de archivos.Actions are defined in the file handler manifest within the actions key-value pair, which contains an array of actions supported by the file handler.

Un ejemplo de la definición de las tres acciones integradas y una única acción personalizada:An example of the definition for the three built-in actions and a single custom action:

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

Debido a las limitaciones en las extensiones de complemento de Azure Active Directory, estas acciones se almacenan serializadas en una cadena. Se recomienda que JSON minimice la matriz antes de convertirla en un valor de cadena para el almacenamiento en el manifiesto.Due to limitations in the Azure Active Directory addIn extensions, these actions are stored serialized into a string. It is recommended that you JSON minify the array before converting it to a string value to store in the manifest.

Por ejemplo, las acciones definidas anteriormente se almacenarían en el manifiesto del controlador de archivos de la siguiente manera:For example, the actions defined above would be stored in the file handler manifest like this:

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

Parámetros de acciónAction parameters

Cada acción que se ha declarado en el parámetro de acción tiene la forma siguiente:Each action declared in the action parameter takes the following shape:

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

PropiedadesProperties

No todas las propiedades son necesarias, varían en función del tipo de acción que se especifica.Not all properties are required, depending on the type of action specified.

Nombre del parámetroParameter name TipoType DescripciónDescription
tipotype cadenastring Un valor de newFile, open o preview. Necesario.A value of newFile, open, or preview. Required.
urlurl URLURL Una dirección URL https:// para el punto de conexión que controla la acción del controlador de archivos. Necesario.An https:// URL for the endpoint that handles the file handler action. Required.
displayNamedisplayName stringstring Una cadena de configuración regional predeterminada que se ha usado en type: "custom" para representar la acción. Opcional.A default locale string used for type: "custom" to represent the action. Optional.
shortDisplayNameshortDisplayName stringstring Una cadena de configuración regional predeterminada usada por type: "custom" para representar la acción en la barra de herramientas o el menú de acción contraído.A default locale string used for type: "custom" to represent the action in the toolbar or collapsed action menu. Opcional.Optional.
availableOnavailableOn objectobject Una colección de propiedades que definen dónde está disponible esta acción. Necesario.A collection of properties the define where this action is available. Required.
iconoicon displayIcondisplayIcon Objeto que contiene las direcciones URL a las imágenes de icono de este tipo de archivo.An object containing URLs to icon images for this file type. Opcional.Optional.
  • La propiedad displayName solo se puede aplicar a las acciones de tipo custom y se ignora para las acciones de cualquier otro tipo.The displayName property is only applicable to actions of type custom and is ignored for actions of any other type.

Propiedades availableOnAvailableOn Properties

Si establece las propiedades en la propiedad availableOn, puede personalizar la disponibilidad de la acción:By setting properties within the availableOn property, you can customize where the action is available:

Nombre del parámetroParameter name TipoType DescripciónDescription
file.extensionsfile.extensions matriz de cadenasarray of strings Una matriz de las extensiones de archivo en las que está disponible la acción. Las extensiones de archivo deben comenzar con un punto (.). Un carácter comodín * puede usarse para indicar todas las extensiones de archivo de las acciones personalizadas.An array of the file extensions the action is available on. File extensions must start with a period (.). A wildcard character * can be used to indicate all file extensions for custom actions.
folderfolder objectobject Un objeto sin parámetros indica que el controlador de archivos está disponible cuando una carpeta está seleccionada o cuando ningún archivo está seleccionado. Un valor NULL o la propiedad que no se define indica que la acción no está disponible para las carpetas.An object with no parameters indicates that the file handler is available when a folder is selected or when no files are selected. A null value or the property not being defined indicates the action is not available for folders.
allowMultiSelectallowMultiSelect booleanboolean Si true, pueden seleccionarse archivos múltiples y la acción seguirá mostrándose. Si false o no se encuentra, la acción solo se muestra cuando un elemento único está seleccionado.If true, multiple files can be selected and the action will still be displayed. If false or missing, the action is only displayed when a single item is selected.
webweb objectobject Un objeto sin parámetros indica que el controlador de archivos está disponible al explorar el sitio web.An object with no parameters indicates that the file handler is available when browsing the website.
  • Solo puede especificarse una extensión de archivo para las acciones de tipo newFile. Esta es la extensión que tendrá el archivo recién creado. Si se muestran varias extensiones de archivo, solo se usará la primera extensión de archivo.Only one file extension can be specified for actions of type newFile. This is the extension the newly created file will have. If multiple file extensions are listed, only the first file extension will be used.
  • Las propiedades folder y allowMultiSelect solo se pueden aplicar en acciones de tipo custom. Estos valores se ignoran para las acciones de cualquier otro tipo.The folder and allowMultiSelect properties are only applicable to actions of type custom. These values are ignored for actions of any other type.