Conceitos básicos dos tipos de dados do Excel

  • Artigo

Este artigo descreve como usar a API JavaScript do Excel para trabalhar com tipos de dados. Ele apresenta conceitos fundamentais para o desenvolvimento de tipos de dados.

A propriedade valuesAsJson

A valuesAsJson propriedade (ou o singular valueAsJson para NamedItem) é essencial para criar tipos de dados no Excel. Essa propriedade é uma expansão de values propriedades, como Range.values. As propriedades values e valuesAsJson são usadas para acessar o valor em uma célula, mas a propriedade values retorna apenas um dos quatro tipos básicos: cadeia de caracteres, número, booliano ou error (como cadeia de caracteres). Por outro lado, valuesAsJson retorna informações expandidas sobre os quatro tipos básicos e essa propriedade pode retornar tipos de dados, como valores numéricos formatados, entidades e imagens da web.

Os objetos a seguir oferecem a propriedade valuesAsJson.

Observação

Alguns valores de célula mudam com base na localidade de um usuário. A propriedade valuesAsJsonLocal oferece suporte à localização e está disponível em todos os mesmos objetos que valuesAsJson.

Valores da célula

A propriedade valuesAsJson retorna um alias de tipo CellValue, que é uma união dos seguintes tipos de dados.

O alias de tipo CellValue também retorna o objeto CellValueExtraProperties, que é uma interseção com o restante dos tipos *CellValue. Não é um tipo de dados em si. As propriedades do objeto CellValueExtraProperties são usadas com todos os tipos de dados para especificar detalhes relacionados à substituição de valores de células.

Esquema JSON

Cada tipo de valor de célula retornado por valuesAsJson usa um esquema de metadados JSON projetado para esse tipo. Junto com propriedades adicionais exclusivas para cada tipo de dados, todos esses esquemas de metadados JSON têm as propriedades type, basicType e basicValue em comum.

O type define o CellValueType dos dados. O basicType é sempre somente leitura e é usado como um fallback quando o tipo de dados não tem suporte ou é formatado incorretamente. O basicValue corresponde ao valor que seria retornado pela propriedade values. O basicValue é usado como substituto quando os cálculos encontram cenários incompatíveis, como uma versão mais antiga do Excel que não oferece suporte ao recurso de tipos de dados. O basicValue é somente leitura para ArrayCellValue, EntityCellValue, LinkedEntityCellValuee tipos de WebImageCellValue dados.

Além dos três campos que todos os tipos de dados compartilham, o esquema de metadados JSON para cada *CellValue tem propriedades disponíveis de acordo com esse tipo. Por exemplo, o tipo WebImageCellValue inclui as propriedades altText e attribution, enquanto o tipo EntityCellValue oferece os campos properties e text.

As seções a seguir mostram exemplos de código JSON do valor de número formatado, valor de entidade e tipos de dados de imagem da Web.

Valores de número formatados

O objeto FormattedNumberCellValue permite que os suplementos do Excel definam uma propriedade numberFormat de um valor. Depois de atribuído, esse formato de número percorre cálculos com o valor e pode ser retornado por funções.

O exemplo de código JSON a seguir mostra o esquema completo de um valor numérico formatado. O valor do número formatado myDate no exemplo de código é exibido como 16/1/1990 na interface do usuário do Excel. Se os requisitos mínimos de compatibilidade para o recurso de tipos de dados não forem atendidos, os cálculos usarão o basicValue no lugar do número formatado.

// This is an example of the complete JSON of a formatted number value.
// In this case, the number is formatted as a date.
const myDate: Excel.FormattedNumberCellValue = {
    type: Excel.CellValueType.formattedNumber,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

Comece a experimentar com valores de número formatados abrindo Script Lab e verificando os tipos de dados: snippet de números formatados em nossa biblioteca De exemplos.

Valores de entidade

Um valor de entidade é um contêiner dos tipos de dados, semelhante a um objeto em programação orientada a objetos. As entidades também suportam matrizes como propriedades de um valor de entidade. O objeto EntityCellValue permite que os suplementos definam propriedades como type, text e properties. A propriedade properties permite que o valor de entidade defina e contenha tipos de dados adicionais.

As propriedades basicType e basicValue definem como os cálculos leem esse tipo de dados de entidade se os requisitos mínimos de compatibilidade para usar tipos de dados não forem atendidos. Nesse cenário, esse tipo de dados de entidade é exibido como um erro #VALUE! na interface do usuário do Excel.

O exemplo de código JSON a seguir mostra o esquema completo de um valor de entidade que contém texto, uma imagem, uma data e um valor de texto adicional.

// This is an example of the complete JSON for an entity value.
// The entity contains text and properties which contain an image, a date, and another text value.
const myEntity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "A llama",
    properties: {
        image: myImage,
        "start date": myDate,
        "quote": {
            type: Excel.CellValueType.string,
            basicValue: "I love llamas."
        }
    }, 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Os valores de entidade também oferecem uma propriedade layouts que cria um cartão para a entidade. O cartão é exibido como uma janela modal na interface do usuário do Excel e pode exibir informações adicionais contidas no valor da entidade, além do que é visível na célula. Para saber mais, confira Usar cartões com tipos de dados de valor de entidade.

Para explorar tipos de dados de entidade, comece acessando Script Lab no Excel e abrindo os tipos de dados: crie cartões de entidade a partir de dados em um snippet de tabela em nossa biblioteca De exemplos. Os tipos de dados: valores de entidade com referências e tipos de dados: snippets de propriedades de atribuição de valor de entidade oferecem um olhar mais profundo sobre os recursos da entidade.

Entidades Vinculadas

Os valores de entidade vinculados ou objetos LinkedEntityCellValue são um tipo de valor de entidade. Esses objetos integram os dados fornecidos por um serviço externo e podem exibir esses dados como um cartão de entidade, como valores de entidade regulares. Os Tipos de dados de Ações e Geografia disponíveis através da interface do usuário do Excel são valores de entidade vinculados.

Valores de imagem da Web

O objeto WebImageCellValue cria a capacidade de armazenar uma imagem como parte de uma entidade ou como um valor independente em um intervalo. Esse objeto oferece muitas propriedades, incluindo address, altText e relatedImagesAddress.

As propriedades basicType e basicValue definem como os cálculos leem o tipo de dados de imagem da Web se os requisitos mínimos de compatibilidade para usar o recurso de tipos de dados não forem atendidos. Nesse cenário, esse tipo de dados de imagem da Web é exibido como um erro #VALUE! na interface do usuário do Excel.

O exemplo de código JSON a seguir mostra o esquema completo de uma imagem da Web.

// This is an example of the complete JSON for a web image.
const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw", 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Experimente os tipos de dados de imagem da Web abrindo Script Lab e selecionando os tipos de dados: snippet de imagens da Web em nossa biblioteca de exemplos.

Suporte a erros aprimorado

As APIs de tipos de dados expõem erros existentes da IU do Excel como objetos. Agora que esses erros são acessíveis como objetos, os suplementos podem definir ou recuperar propriedades como type, errorType e errorSubType.

Veja a seguir uma lista de todos os objetos de erro com suporte expandido por meio de tipos de dados.

Cada um dos objetos de erro pode acessar uma enumeração por meio da propriedade errorSubType, e essa enumeração contém dados adicionais sobre o erro. Por exemplo, o objeto de erro BlockedErrorCellValue pode acessar a enumeração BlockedErrorCellValueSubType. O enumeração BlockedErrorCellValueSubType oferece dados adicionais sobre o que causou o erro.

Saiba mais sobre os objetos de erro de tipos de dados verificando os tipos de dados: defina snippet de valores de erro em nossa biblioteca Script LabSamples.

Próximas etapas

Saiba como os tipos de dados de entidade estendem o potencial dos suplementos do Excel para além de uma grade bidimensional com o artigo Usar cartões com tipos de dados de valor de entidade .

Use o repositório Criar e explorar tipos de dados no Excel em nosso repositório OfficeDev/Office-Add-in-samples para experimentar mais profundamente os tipos de dados criando e carregando um suplemento que cria e edita tipos de dados em uma pasta de trabalho.

Confira também