Uso de tipos de datos con funciones personalizadas en Excel

  • Artículo

Los tipos de datos expanden la API de JavaScript de Excel para admitir tipos de datos más allá de los cuatro tipos de valor de celda originales (cadena, número, booleano y error). Los tipos de datos incluyen compatibilidad con imágenes web, valores de número con formato, entidades y matrices dentro de entidades.

Estos tipos de datos amplían la eficacia de las funciones personalizadas, ya que las funciones personalizadas aceptan tipos de datos como valores de entrada y salida. Puede generar tipos de datos a través de funciones personalizadas o tomar los tipos de datos existentes como argumentos de función en cálculos. Una vez establecido el esquema JSON de un tipo de datos, este esquema se mantiene a lo largo de los cálculos.

Para más información sobre el uso de tipos de datos con un complemento de Excel, vea Información general sobre los tipos de datos en complementos de Excel.

Cómo las funciones personalizadas controlan los tipos de datos

Las funciones personalizadas pueden reconocer tipos de datos y aceptarlos como valores de parámetro. Una función personalizada puede crear un nuevo tipo de datos para un valor devuelto. Las funciones personalizadas usan el mismo esquema JSON para los tipos de datos que la API de JavaScript de Excel, y este esquema JSON se mantiene a medida que las funciones personalizadas se calculan y evalúan.

Nota:

Las funciones personalizadas no admiten la funcionalidad completa de los objetos de error mejorados que ofrecen los tipos de datos. Una función personalizada puede aceptar un objeto de error de tipos de datos, pero no se mantendrá a lo largo del cálculo. En este momento, las funciones personalizadas solo admiten los errores incluidos en el objeto CustomFunctions.Error.

Habilitación de tipos de datos para funciones personalizadas

Los proyectos de funciones personalizadas incluyen un archivo de metadatos JSON. Este archivo de metadatos JSON difiere del esquema JSON que usan las API de tipos de datos. Para usar la integración de tipos de datos con funciones personalizadas, el archivo de metadatos JSON de las funciones personalizadas debe actualizarse manualmente para incluir la propiedad allowCustomDataForDataTypeAny. Establezca esta propiedad en true.

Para obtener una descripción completa del proceso manual de creación de metadatos JSON, consulte Creación manual de metadatos JSON para funciones personalizadas. Consulte allowCustomDataForDataTypeAny para más información sobre esta propiedad.

Generar un valor de número con formato

En el ejemplo de código siguiente se muestra cómo crear un tipo de datos FormattedNumberCellValue con una función personalizada. La función toma un número básico y una configuración de formato como parámetros de entrada y devuelve un tipo de datos de valor de número con formato como resultado.

/**
 * Take a number as the input value and return a formatted number value as the output.
 * @customfunction
 * @param {number} value
 * @param {string} format (e.g. "0.00%")
 * @returns A formatted number value.
 */
function createFormattedNumber(value, format) {
    return {
        type: "FormattedNumber",
        basicValue: value,
        numberFormat: format
    }
}

Entrada de un valor de entidad

En el ejemplo de código siguiente se muestra una función personalizada que toma un tipo de datos EntityCellValue como entrada. Si el parámetro attribute se establece en text, la función devuelve la propiedad text del valor de entidad. De lo contrario, la función devuelve la propiedad basicValue del valor de entidad.

/**
 * Accept an entity value data type as a function input.
 * @customfunction
 * @param {any} value
 * @param {string} attribute
 * @returns {any} The text value of the entity.
 */
function getEntityAttribute(value, attribute) {
    if (value.type == "Entity") {
        if (attribute == "text") {
            return value.text;
        } else {
            return value.properties[attribute].basicValue;
        }
    } else {
        return JSON.stringify(value);
    }
}

Pasos siguientes

Para experimentar con funciones personalizadas y tipos de datos, instale Script Lab en Excel y pruebe el fragmento de código Tipos de datos: funciones personalizadas en nuestra biblioteca de ejemplos.

Vea también