Usar tipos de dados com funções personalizadas no Excel
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 da Web, valores de número 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 manual de criação de metadados JSON, consulte Criar metadados JSON manualmente para funções personalizadas. Consulte allowCustomDataForDataTypeAny para obter detalhes adicionais sobre essa propriedade.
Gerar um valor de número formatado
O exemplo de código a seguir mostra como criar um tipo de dados FormattedNumberCellValue com uma função personalizada. A função usa um número básico e uma configuração de formato como parâmetros de entrada e retorna um tipo de dados de valor numérico formatado como a saída.
/**
* 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
}
}
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 {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);
}
}
Próximas etapas
Para experimentar funções personalizadas e tipos de dados, instale Script Lab no Excel e experimente os tipos de dados: snippet de funções personalizadas em nossa biblioteca de exemplos.