Uso de tipos de datos con funciones personalizadas en Excel

Los tipos de datos de Excel permiten que las funciones personalizadas acepten y devuelvan valores más allá de cadenas, números, valores booleanos y errores. Por ejemplo, una función personalizada puede devolver un número con formato o aceptar un valor de entidad como argumento.

Las funciones personalizadas y la API de JavaScript de Excel usan el mismo esquema JSON para los tipos de datos. Una vez habilitado, Excel mantiene ese esquema a medida que las funciones personalizadas calculan y evalúan los valores.

Prueba de funciones personalizadas con tipos de datos

Instale Script Lab en Excel y, a continuación, ejecute el ejemplo Tipos de datos: funciones personalizadas desde la biblioteca de ejemplos.

Cómo las funciones personalizadas controlan los tipos de datos

Las funciones personalizadas pueden aceptar tipos de datos como parámetros y crear tipos de datos como valores devueltos. Para obtener una introducción a los tipos disponibles, vea Información general sobre los tipos de datos en complementos de Excel.

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 mantiene el error durante todo el 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, que difiere del esquema JSON que usan las API de tipos de datos. Para habilitar los tipos de datos para funciones personalizadas, agregue manualmente la allowCustomDataForDataTypeAny propiedad al archivo de metadatos de funciones personalizadas y establézcala en true.

"allowCustomDataForDataTypeAny": 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.

Salida de un número con formato

La siguiente función personalizada acepta un número y un formato numérico y, a continuación, devuelve un objeto DoubleCellValue con formato.

/**
 * Take a number as the input value and return a double 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: "Double",
        basicValue: value,
        numberFormat: format
    };
}

Entrada de un valor de entidad

La siguiente función personalizada acepta un objeto EntityCellValue y un nombre de atributo. Devuelve la propiedad de la text entidad cuando attribute es text. De lo contrario, devuelve el basicValue de la propiedad solicitada.

Importante

Al construir o devolver un EntityCellValue objeto en una función personalizada y ese valor contiene entidades anidadas, defina solo la referencedValues matriz en la entidad de nivel raíz. La definición referencedValues en una entidad anidada hace que Excel devuelva un error #VALUE! sin excepción de JavaScript ni diagnósticos detallados. Use índices ReferenceCellValue en entidades anidadas para apuntar a la matriz de referencedValues la entidad raíz en su lugar. Para obtener más información, vea Valores de entidad.

/**
 * Accept an entity value data type as a function input.
 * @customfunction
 * @param {Excel.EntityCellValue} 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);
    }
}

Vea también

  • Last updated on