Creación manual de metadatos JSON para funciones personalizadas

Artículo
03/15/2023

Como se describe en el artículo de información general sobre funciones personalizadas , un proyecto de funciones personalizadas debe incluir un archivo de metadatos JSON y un archivo de script (JavaScript o TypeScript) para registrar una función, lo que hace que esté disponible para su uso. Las funciones personalizadas se registran cuando el usuario ejecuta el complemento por primera vez y después de eso están disponibles para el mismo usuario en todos los libros.

Importante

Tenga en cuenta que las funciones personalizadas están disponibles en Excel en las siguientes plataformas.

Office en Windows
- Suscripción a Microsoft 365
- Retail perpetual Office 2016 y versiones posteriores
Office en Mac
Office en la Web

Las funciones personalizadas de Excel no se admiten actualmente en lo siguiente:

Office en iPad
versiones perpetuas con licencia por volumen de Office 2019 o versiones anteriores

Se recomienda usar la autogeneración JSON cuando sea posible en lugar de crear su propio archivo JSON. La autogeneración es menos propensa a errores del usuario y los yo office archivos scaffolding ya lo incluyen. Para obtener más información sobre las etiquetas JSDoc y el proceso de autogeneración JSON, consulte Generación automática de metadatos JSON para funciones personalizadas.

Sin embargo, puede crear un proyecto de funciones personalizado desde cero. Este proceso requiere que:

Escriba el archivo JSON.
Compruebe que el archivo de manifiesto está conectado al archivo JSON.
Asocie las funciones y idname las propiedades en el archivo de script para registrar las funciones.

En la imagen siguiente se explican las diferencias entre el uso de yo office archivos scaffolding y la escritura de JSON desde cero.

Imagen de las diferencias entre el uso del generador de Yeoman para complementos de Office y la escritura de su propio JSON.

Nota:

Recuerde conectar el manifiesto al archivo JSON que cree, a través de la <sección Recursos> del archivo de manifiesto XML si no usa el generador de Yeoman para complementos de Office.

Creación de metadatos y conexión al manifiesto

Cree un archivo JSON en el proyecto y proporcione todos los detalles sobre las funciones que contiene, como los parámetros de la función. Consulte el ejemplo de metadatos siguiente y la referencia de metadatos para obtener una lista completa de las propiedades de la función.

Asegúrese de que el archivo de manifiesto XML hace referencia al archivo JSON en la <sección Recursos> , de forma similar al ejemplo siguiente.

<Resources>
    <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
            <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
    </bt:ShortStrings>
</Resources>

Ejemplo de metadatos JSON

El siguiente ejemplo muestra el contenido de un archivo de metadatos JSON para un complemento que define funciones personalizadas. Las secciones que siguen este ejemplo proporcionan información detallada sobre las propiedades individuales de este ejemplo de JSON.

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "SECONDHIGHEST",
      "name": "SECONDHIGHEST",
      "description": "Get the second highest number from a range",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "range",
          "description": "the input range",
          "type": "number",
          "dimensionality": "matrix"
        }
      ]
    }
  ]
}

Nota:

Un archivo JSON de ejemplo completo está disponible en el historial de confirmaciones del repositorio de GitHub OfficeDev/Excel-Custom-Functions . Dado que el proyecto se ha ajustado para generar automáticamente JSON, solo hay disponible una muestra completa de JSON manuscrito en versiones anteriores del proyecto.

Referencia de metadatos

allowCustomDataForDataTypeAny

La allowCustomDataForDataTypeAny propiedad es un tipo de datos booleano. Establecer este valor en permite que true una función personalizada acepte tipos de datos como parámetros y valores devueltos. Para más información, consulte Funciones personalizadas y tipos de datos.

Nota:

A diferencia de la mayoría de las demás propiedades de metadatos JSON, allowCustomDataForDataTypeAny es una propiedad de nivel superior y no contiene ninguna subpropiedad. Consulte el ejemplo de código de metadatos JSON anterior para obtener un ejemplo de cómo dar formato a esta propiedad.

allowErrorForDataTypeAny

La allowErrorForDataTypeAny propiedad es un tipo de datos booleano. Establecer el valor en permite que true una función personalizada procese errores como valores de entrada. Todos los parámetros con el tipo any o any[][] pueden aceptar errores como valores de entrada cuando allowErrorForDataTypeAny se establece en true. El valor predeterminado allowErrorForDataTypeAny es false.

Nota:

A diferencia de las demás propiedades de metadatos JSON, allowErrorForDataTypeAny es una propiedad de nivel superior y no contiene ninguna subpropiedad. Consulte el ejemplo de código de metadatos JSON anterior para obtener un ejemplo de cómo dar formato a esta propiedad.

funciones

La propiedad functions es una matriz de objetos de la función personalizada. En la siguiente tabla se enumeran las propiedades de cada objeto.

Propiedad	Tipo de datos	Obligatorio	Descripción
`description`	string	No	La descripción de la función que ven los usuarios finales en Excel. Por ejemplo, Convierte un valor de Celsius a Fahrenheit.
`helpUrl`	string	No	Dirección URL que presenta la función. (Se muestra en un panel de tareas). Por ejemplo, `http://contoso.com/help/convertcelsiustofahrenheit.html`.
`id`	string	Sí	Un identificador único para la función. Este identificador solo puede contener caracteres alfanuméricos y puntos y no se debe cambiar cuando se establece.
`name`	string	Sí	El nombre de la función que ven los usuarios finales en Excel. En Excel, este nombre de función tiene el prefijo del espacio de nombres de funciones personalizadas que se especifica en el archivo de manifiesto XML.
`options`	object	No	Le permite personalizar algunos aspectos de cómo y cuándo Excel ejecuta la función. Ver opciones para obtener más información.
`parameters`	matriz	Sí	Matriz que define los parámetros de entrada de la función. Consulte los parámetros para obtener más información.
`result`	object	Sí	Objeto que define el tipo de información que la función devuelve. Ver resultados para obtener más información.

opciones

El objeto options le permite personalizar algunos aspectos de cómo y cuándo Excel ejecuta la función. En la siguiente tabla se enumeran las propiedades del objeto options.

Propiedad	Tipo de datos	Obligatorio	Descripción
`cancelable`	boolean	No El valor predeterminado es `false`.	Si `true`, Excel llama al controlador `CancelableInvocation` cuando el usuario realiza una acción que tiene el efecto de cancelar la función, por ejemplo, desencadenar manualmente el recálculo o editar una celda que hace referencia a la función. Las funciones cancelables normalmente solo se usan para las funciones asincrónicas que devuelven un único resultado y necesitan controlar la cancelación de una solicitud de datos. Una función no puede usar las `stream` propiedades y `cancelable` .
`requiresAddress`	booleano	No El valor predeterminado es `false`.	Si `true`es , la función personalizada puede acceder a la dirección de la celda que la invocó. La `address` propiedad del parámetro invocation contiene la dirección de la celda que invocó la función personalizada. Una función no puede usar las `stream` propiedades y `requiresAddress` .
`requiresParameterAddresses`	booleano	No El valor predeterminado es `false`.	Si `true`es , la función personalizada puede acceder a las direcciones de los parámetros de entrada de la función. Esta propiedad debe usarse en combinación con la `dimensionality` propiedad del objeto de resultado y `dimensionality` debe establecerse en `matrix`. Consulte Detección de la dirección de un parámetro para obtener más información.
`stream`	booleano	No El valor predeterminado es `false`.	Si es `true`, la función puede producir varias salidas en la celda, incluso cuando se invoca una sola vez. Esta opción es útil para cambiar rápidamente orígenes de datos, como un precio de cotizaciones. La función no debería tener una instrucción `return`. En su lugar, el valor de resultado se pasa como argumento de la `StreamingInvocation.setResult` función de devolución de llamada. Para obtener más información, consulte Creación de una función de streaming.
`volatile`	booleano	No El valor predeterminado es `false`.	Si `true`es , la función se recalcula cada vez que Excel vuelve a calcular, en lugar de solo cuando los valores dependientes de la fórmula han cambiado. Una función no puede usar las `stream` propiedades y `volatile` . Si las `stream` propiedades y `volatile` se establecen `true`en , se omitirá la propiedad volatile.

parámetros

La propiedad parameters es una matriz de objetos del parámetro. En la siguiente tabla se enumeran las propiedades de cada objeto.

Propiedad	Tipo de datos	Obligatorio	Descripción
`description`	string	No	Una descripción del parámetro. Esto se muestra en IntelliSense de Excel.
`dimensionality`	string	No	Debe ser `scalar` (un valor que no es de matriz) o `matrix` (una matriz 2 dimensiones).
`name`	string	Sí	Nombre del parámetro. Este nombre se muestra en IntelliSense de Excel.
`type`	string	No	El tipo de datos del parámetro. Puede ser `boolean`, `number`, `string`o `any`, que le permite usar cualquiera de los tres tipos anteriores. Si no se especifica esta propiedad, el tipo de datos tiene como valor predeterminado `any`.
`optional`	booleano	No	Si `true`, el parámetro es opcional.
`repeating`	booleano	No	Si `true`es , los parámetros se rellenan desde una matriz especificada. Tenga en cuenta que las funciones de todos los parámetros repetitivos se consideran parámetros opcionales por definición.

result

El objeto result que define el tipo de información que la función devuelve. En la siguiente tabla se enumeran las propiedades del objeto result.

Propiedad	Tipo de datos	Obligatorio	Descripción
`dimensionality`	string	No	Debe ser `scalar` (un valor que no es de matriz) o `matrix` (una matriz 2 dimensiones).
`type`	string	No	Tipo de datos del resultado. Puede ser `boolean`, `number`, `string`o `any` (que permite usar cualquiera de los tres tipos anteriores). Si no se especifica esta propiedad, el tipo de datos tiene como valor predeterminado `any`.

Asignación de nombres de funciones a metadatos JSON

Para que una función funcione correctamente, debe asociar la propiedad de id la función a la implementación de JavaScript. Asegúrese de que hay una asociación; de lo contrario, la función no se registrará y no se podrá usar en Excel. En el ejemplo de código siguiente se muestra cómo realizar la asociación mediante la CustomFunctions.associate() función . En el ejemplo se define la función personalizada add y se asocia con el objeto en el archivo de metadatos JSON donde el valor de la propiedad id es ADD.

/**
 * Add two numbers
 * @customfunction
 * @param {number} first First number
 * @param {number} second Second number
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

El siguiente JSON muestra los metadatos JSON asociados con el código JavaScript de la función personalizada anterior.

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

Tenga en cuenta los siguientes procedimientos recomendados al crear funciones personalizadas en el archivo JavaScript y especificar la información correspondiente en el archivo de metadatos JSON.

En el archivo de metadatos JSON, asegúrese de que el valor de cada propiedad id contiene solo caracteres alfanuméricos y puntos.
En el archivo de metadatos JSON, asegúrese de que el valor de cada propiedad id sea único en el ámbito del archivo. Es decir, no debe haber dos objetos de función en el archivo de metadatos con el mismo valor id.
No cambie el valor de una propiedad id en el archivo de metadatos JSON después de que se haya asociado a un nombre de función de JavaScript correspondiente. Puede cambiar el nombre de función que ven los usuarios finales en Excel mediante la actualización de la propiedad name en el archivo de metadatos JSON, pero nunca debe cambiar el valor de una propiedad id una vez que se haya establecido.
En el archivo JavaScript, especifique una asociación de función personalizada mediante CustomFunctions.associate después de cada función.

En el ejemplo siguiente se muestran los metadatos JSON que corresponden a las funciones definidas en el ejemplo de código JavaScript anterior. Los id valores de propiedad y name están en mayúsculas, lo que es un procedimiento recomendado al describir las funciones personalizadas. Solo tiene que agregar este JSON si va a preparar manualmente su propio archivo JSON y no a usar la autogeneración. Para obtener más información sobre la autogeneración, consulte Generación automática de metadatos JSON para funciones personalizadas.

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

Pasos siguientes

Obtenga información sobre los procedimientos recomendados para asignar un nombre a la función o descubra cómo localizar la función mediante el método JSON manuscrito descrito anteriormente.

Creación manual de metadatos JSON para funciones personalizadas

Creación de metadatos y conexión al manifiesto

Ejemplo de metadatos JSON

Referencia de metadatos

allowCustomDataForDataTypeAny

allowErrorForDataTypeAny

funciones

opciones

parámetros

result

Asignación de nombres de funciones a metadatos JSON

Pasos siguientes

Vea también

Comentarios

Recursos adicionales