Utilizar tipos de dados com funções personalizadas no Excel

2025-06-27

Os tipos de dados expandem a API JavaScript do Excel para dar suporte a tipos de dados além dos quatro tipos de valor de célula originais (cadeia de caracteres, número, booliano e erro). Os tipos de dados incluem suporte para imagens Web, números formatados, entidades e matrizes dentro de entidades.

Esses tipos de dados ampliam o poder das funções personalizadas, pois as funções personalizadas aceitam tipos de dados como valores de entrada e saída. Você pode gerar tipos de dados por meio de funções personalizadas ou levar os tipos de dados existentes como argumentos de função nos cálculos. Depois que o esquema JSON de um tipo de dados é definido, esse esquema é mantido em todos os cálculos.

Para saber mais sobre como usar tipos de dados com um suplemento do Excel, consulte Exibição de tipos de dados em suplementos do Excel.

Como as funções personalizadas lidam com tipos de dados

As funções personalizadas podem reconhecer tipos de dados e aceitá-los como valores de parâmetro. Uma função personalizada pode criar um novo tipo de dados para um valor retornado. As funções personalizadas usam o mesmo esquema JSON para tipos de dados que a API JavaScript do Excel, e esse esquema JSON é mantido conforme as funções personalizadas calculam e avaliam.

Observação

As funções personalizadas não dão suporte à funcionalidade completa dos objetos de erro aprimorados oferecidos pelos tipos de dados. Uma função personalizada pode aceitar um objeto de erro de tipos de dados, mas não será mantida durante o cálculo. No momento, as funções personalizadas só dão suporte aos erros incluídos no objeto CustomFunctions.Error.

Habilitar tipos de dados para funções personalizadas

Projetos de funções personalizadas incluem um arquivo de metadados JSON. Esse arquivo de metadados JSON difere do esquema JSON usado pelas APIs de tipos de dados. Para usar a integração de tipos de dados com funções personalizadas, o arquivo de metadados JSON de funções personalizadas deve ser atualizado manualmente para incluir a propriedade allowCustomDataForDataTypeAny. Defina essa propriedade como true.

Para obter uma descrição completa do processo de criação manual de metadados JSON, veja Criar metadados JSON manualmente para funções personalizadas. Consulte allowCustomDataForDataTypeAny para obter detalhes adicionais sobre essa propriedade.

Exportar um número formatado

O seguinte exemplo de código mostra como criar um número formatado com uma função personalizada. Esta ação utiliza o objeto DoubleCellValue . A função utiliza um número básico e uma definição de formato como parâmetros de entrada e devolve um número formatado como tipo de dados duplo para a saída.

/**
 * 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
    }
}

Inserir um valor de entidade

O exemplo de código a seguir mostra uma função personalizada que usa um tipo de dados EntityCellValue como uma entrada. Se o parâmetro attribute for definido como text, a função retornará a propriedade text do valor da entidade. Caso contrário, a função retornará a propriedade basicValue do valor da entidade.

/**
 * 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);
    }
}

Próximas etapas

Para experimentar funções personalizadas e tipos de dados, instale Script Lab no Excel e experimente o fragmento Tipos de dados: Funções personalizadas na nossa biblioteca de Exemplos.

Compartilhar via