Compartilhar via

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 de NamedItem) é parte integrante da criação de 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 só de leitura e é utilizado como contingência quando o tipo de dados não é suportado ou está 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 é só de leitura para ArrayCellValueos tipos de dados , EntityCellValue, LinkedEntityCellValuee WebImageCellValue .

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 valores numéricos formatados ao abrir o Laboratório de Scripts e verificar os Tipos de dados: Fragmento de números formatados na 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, este tipo de dados de entidade é apresentado como um erro #VALUE! na IU 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 os tipos de dados de entidades, comece por aceder ao Laboratório de Scripts no Excel e abrir os Tipos de dados: Criar cartões de entidade a partir de dados num fragmento de tabela na nossa biblioteca de Exemplos . Os Tipos de dados: valores de entidade com referências e Tipos de dados: fragmentos de propriedades de atribuição de valor de entidade oferecem uma análise mais aprofundada das funcionalidades 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, este tipo de dados de imagem Web é apresentado como um erro #VALUE! na IU 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 tipos de dados de imagens Web ao abrir o Laboratório de Scripts e selecionar os Tipos de dados: fragmento de imagens Web na 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 ao verificar os Tipos de dados: Definir fragmento de valores de erro na nossa biblioteca de Exemplosdo Laboratório de Scripts.

Próximas etapas

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

Utilize o exemplo Criar e explorar tipos de dados no Excel no nosso repositório OfficeDev/Office-Add-in-samples para experimentar mais profundamente os tipos de dados ao criar e sideload de um suplemento que cria e edita tipos de dados num livro.

Confira também