Compartir a través de

Creación manual de metadatos JSON para funciones personalizadas

  • Artículo

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 la web
  • Office en Windows
    • Suscripción a Microsoft 365
    • Retail perpetual Office 2016 y versiones posteriores
    • Licencia por volumen perpetua de Office 2021 y versiones posteriores
  • Office en Mac

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 en Windows

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:

No olvide conectar el manifiesto al archivo JSON que cree, a través de la <sección Recursos> del archivo de manifiesto de solo complemento 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 de solo complemento 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 de solo complemento.
options objeto 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 truees , 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 truees , 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 truees , 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 trueen , 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, stringo 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 truees , 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, stringo 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",
      ...
    }
  ]
}

Siguientes pasos

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.

Vea también