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

Os tipos de dados do Excel permitem que funções personalizadas aceitem e retornem valores além de cadeias de caracteres, números, valores boolianos e erros. Por exemplo, uma função personalizada pode retornar um número formatado ou aceitar um valor de entidade como argumento.

As funções personalizadas e a API JavaScript do Excel usam o mesmo esquema JSON para os tipos de dados. Depois de habilitado, o Excel mantém esse esquema à medida que funções personalizadas calculam e avaliam valores.

Experimente funções personalizadas com tipos de dados

Instale o Script Lab no Excel e execute o Tipos de dados: exemplo de funções personalizadas da biblioteca de Exemplos.

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

As funções personalizadas podem aceitar tipos de dados como parâmetros e criar tipos de dados como valores retornados. Para obter uma introdução aos tipos disponíveis, consulte Visão geral dos tipos de dados em suplementos do Excel.

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 mantém o erro durante todo 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

Os projetos de funções personalizadas incluem um arquivo de metadados JSON, que difere do esquema JSON usado pelas APIs de tipos de dados. Para habilitar tipos de dados para funções personalizadas, adicione manualmente a allowCustomDataForDataTypeAny propriedade ao arquivo de metadados de funções personalizadas e defina-a como true.

"allowCustomDataForDataTypeAny": true

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

Gerar um número formatado

A função personalizada a seguir aceita um número e um formato de número e, em seguida, retorna um objeto DoubleCellValue formatado.

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

A função personalizada a seguir aceita um objeto EntityCellValue e um nome de atributo. Ele retorna a propriedade da text entidade quando attribute é text. Caso contrário, ele retornará a basicValue propriedade solicitada.

Importante

Ao construir ou retornar um EntityCellValue em uma função personalizada, e esse valor contiver entidades aninhadas, defina somente a referencedValues matriz na entidade de nível raiz. A definição referencedValues em uma entidade aninhada faz com que o Excel retorne um erro #VALUE!, sem exceção de JavaScript ou diagnóstico detalhado. Use índices ReferenceCellValue em entidades aninhadas para apontar para a matriz da referencedValues entidade raiz. Para obter mais informações, consulte Valores de 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);
    }
}

Confira também

  • Last updated on