Creación manual de metadatos JSON para funciones personalizadas

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
  • Office 2021 perpetuo/LTSC con licencia por volumen 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 2021 o versiones anteriores en Windows

Nota:

El manifiesto unificado para Microsoft 365 no admite actualmente proyectos de funciones personalizadas. Debe usar el manifiesto de solo complemento para proyectos de funciones personalizadas. Para obtener más información, vea Manifiesto de complementos de Office.

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.

Nota:

No olvide conectar el manifiesto al archivo JSON que cree, a través de la <Resources> sección 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 haga referencia al archivo JSON de la <Resources> sección, 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": "GETPLANETS", 
      "name": "GETPLANETS", 
      "description": "A function that uses the custom enum as a parameter.", 
      "parameters": [ 
        { 
          "name": "value", 
          "type": "string", 
          "customEnumType": "PLANETS" 
        }
      ]
    }
  ],
  "enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          "name": "Mercury", 
          "value": "mercury", 
          "tooltip": "Mercury is the first planet from the sun." 
        }, 
        { 
          "name": "Venus", 
          "value": "venus", 
          "tooltip": "Venus is the second planet from the sun." 
        }
      ] 
    }
  ]
}

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.

Si la función personalizada usa el cellValueTypeparámetro , no es necesario establecer el allowCustomDataForDataTypeAny valor para aceptar tipos de datos como parámetros y valores devueltos.

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. 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.

enumeraciones

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

Sugerencia

Para obtener información sobre cómo crear enumeraciones personalizadas para las funciones personalizadas, consulte Creación de enumeraciones personalizadas para las funciones personalizadas. Para obtener información sobre cómo editar metadatos para enumeraciones personalizadas, consulte Edición de enumeraciones personalizadas en metadatos JSON.

Propiedad	Tipo de datos	Obligatorio	Descripción
name	string	Sí	Breve descripción de la constante.
tooltip	string	No	Información adicional sobre la constante que se puede mostrar como información sobre herramientas en las interfaces de usuario.
value	string	Sí	Valor de la constante.

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	Booleano	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 .
capturesCallingObject	Booleano	No El valor predeterminado es false.	Si truees , el tipo de datos al que hace referencia la función personalizada se pasa como primer argumento a la función personalizada. Para obtener más información, vea Referencia al valor de entidad como un objeto de llamada.
excludeFromAutoComplete	Booleano	No El valor predeterminado es false.	Si truees , la función personalizada no aparece en el menú Autocompletar de fórmulas en Excel. Para obtener más información, vea Excluir funciones personalizadas de la interfaz de usuario de Excel. Una función no puede tener las excludeFromAutoComplete propiedades y linkedEntityLoadService establecidas en true.
linkedEntityLoadService	Booleano	No El valor predeterminado es false.	Si truees , la función personalizada proporciona un servicio de carga que devuelve valores actualizados de celda de entidad vinculada para cualquier identificador de entidad vinculado solicitado por Excel. Una función no puede tener las excludeFromAutoComplete propiedades y linkedEntityLoadService establecidas en true. Para obtener más información, vea Función de servicio de carga de entidades vinculadas.
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.
requiresStreamAddress	Booleano	No El valor predeterminado es false.	Si truees , la función puede acceder a la dirección de la celda que llama a la función de streaming. La address propiedad del parámetro invocation contiene la dirección de la celda que invocó la función de streaming. La función también debe haber stream establecido en true.
requiresStreamParameterAddresses	Booleano	No El valor predeterminado es false.	Si truees , la función puede acceder a las direcciones de parámetro de la celda que llama a la función de streaming. La parameterAddresses propiedad del parámetro invocation contiene las direcciones de parámetro de la función de streaming. La función también debe haber stream establecido en true.
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.
cellValueType	string	No	Subcampo de la type propiedad . Especifica los tipos de datos de Excel aceptados por la función personalizada. Acepta los valores cellvalueque no distinguen mayúsculas de minúsculas , booleancellvalue, doublecellvalue, entitycellvalue, errorcellvalue, linkedentitycellvalue, localimagecellvalue, stringcellvaluey webimagecellvalue. El type campo debe tener el valor any para usar el cellValueType subcampo.
customEnumType	string	No	de id la enumeración de la enums matriz. Esto asocia la enumeración personalizada a la función y permite a Excel mostrar los miembros de enumeración en el menú Autocompletar de fórmula.
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 todos los parámetros repetidos se consideran parámetros opcionales por definición.

Sugerencia

Consulte el siguiente fragmento de código para obtener un ejemplo de cómo dar formato al cellValueType parámetro en metadatos JSON.

"parameters": [
    {
        "name": "range",
        "description": "the input range",
        "type": "any",
            "cellValueType": "webimagecellvalue"
    }
]

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.

Asociación de nombres de función 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",
      ...
    }
  ]
}

Edición de enumeraciones personalizadas en metadatos JSON

Cree o edite metadatos de enumeración directamente con la enums propiedad . Cada enumeración personalizada debe tener un valor de identificador único y un valor de tipo de o stringnumber. No se admiten enumeraciones de tipo mixto.

Si crea manualmente los metadatos JSON para la enumeración personalizada, puede asociar esas enumeraciones a funciones personalizadas de TypeScript o JavaScript. Para obtener más información sobre cómo crear enumeraciones personalizadas, consulte Creación de enumeraciones personalizadas para las funciones personalizadas.

El siguiente fragmento de código JSON muestra los metadatos de dos enumeraciones: una PLANETS enumeración que contiene los planetas Mercurio y Venus, y una DAYS enumeración que incluye los días lunes y martes.

"enums": [ 
  { 
    "id": "PLANETS", 
    "type": "string", 
    "values": [ 
      { 
        "name": "Mercury", 
        "value": "mercury", 
        "tooltip": "Mercury is the first planet from the sun." 
      }, 
      { 
        "name": "Venus", 
        "value": "venus", 
        "tooltip": "Venus is the second planet from the sun." 
      }
    ] 
  },
  {
    "id": "DAYS", 
    "type": "number", 
    "values": [ 
      { 
        "name": "Monday",
        "value": 1,
        "tooltip": "Monday is the first working day of a week."
      },
      { 
        "name": "Tuesday",
        "value": 2,
        "tooltip": "Tuesday is the second working day of a week."
      }
    ] 
  }
]

Cada constante de la values matriz de la enumeración es un objeto con las siguientes propiedades.

• value: valor de la constante.
• name: una breve descripción de la constante.
• información sobre herramientas (opcional): información adicional sobre la constante que se puede mostrar como información sobre herramientas en las interfaces de usuario.

Para asociar la enumeración personalizada a una función, agregue la propiedad customEnumType al parameters objeto . El customEnumType valor debe coincidir con el id de la enumeración. Tenga en cuenta que el customEnumType valor no distingue mayúsculas de minúsculas. El siguiente fragmento de código JSON muestra un functions objeto asociado a la PLANETS enumeración.

"functions": [ 
  {
    "description": "A function that uses the custom enum as a parameter.", 
    "id": "GETPLANETS", 
    "name": "GETPLANETS", 
    "parameters": [ 
      { 
        "name": "value", 
        "type": "string", 
        "customEnumType": "PLANETS" 
      }
    ], 
    "result": {} 
  } 
]

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.

Vea también

• Generar automáticamente metadatos JSON de funciones personalizadas
• Opciones de parámetros de funciones personalizadas
• Crear funciones personalizadas en Excel