Utilizar tipos de dados em suplementos do Excel

Quando o suplemento precisar de mais do que cadeias, números e booleanos, utilize tipos de dados do Excel. Os tipos de dados permitem-lhe devolver valores melhorados, como datas formatadas, cartões de entidade, registos ligados e imagens Web, ao mesmo tempo que suportam cálculos de folhas de cálculo.

Este artigo explica a valuesAsJson API que alimenta os tipos de dados e mostra quando deve utilizar os principais tipos de valores de célula. Para obter uma descrição geral de funcionalidades, consulte Descrição geral dos tipos de dados nos suplementos do Excel.

Para experimentar estes conceitos imediatamente, abra Script Lab no Excel e procure os Exemplos de tipos de dados na biblioteca Exemplos.

A propriedade valuesAsJson

A valuesAsJson propriedade é a API principal para ler e escrever tipos de dados do Excel. A propriedade singular valueAsJson em NamedItem serve o mesmo propósito para um único item com nome.

valuesAsJson expande em propriedades como Range.values. A values propriedade devolve apenas um dos quatro tipos básicos de valores de célula: cadeia, número, booleano ou erro. Por outro lado, valuesAsJson devolve uma estrutura JSON expandida para esses tipos básicos e para tipos de dados, como números formatados, entidades e imagens Web.

Os seguintes objetos expõem valuesAsJson.

Observação

Alguns valores de célula mudam com base na localidade de um usuário. Utilize valuesAsJsonLocal quando precisar de valores localizados. Está disponível nos mesmos objetos que valuesAsJson.

Valores da célula

valuesAsJson devolve o alias do tipo CellValue . CellValue é uma união de vários tipos de valores de célula.

Os tipos que a maioria dos suplementos utiliza são:

A união completa CellValue inclui os seguintes tipos.

CellValue é uma interseção com CellValueExtraProperties. CellValueExtraProperties não é um tipo de dados por si só. Adiciona propriedades que o ajudam a controlar a forma como os valores das células são substituídos.

Esquema JSON

Cada valor devolvido valuesAsJson utiliza um esquema de metadados JSON concebido para esse tipo de valor de célula. Apesar de cada tipo ter as suas próprias propriedades, todos os esquemas partilham type, basicTypee basicValue.

type define o CellValueType. basicType é só de leitura e fornece o tipo de contingência quando o tipo de dados não é suportado ou está formatado incorretamente. basicValue corresponde ao valor devolvido pela values propriedade e atua como contingência quando os cálculos encontram cenários incompatíveis, como uma versão mais antiga do Excel que não suporta tipos de dados. basicValue é só de leitura para ArrayCellValue, EntityCellValue, LinkedEntityCellValuee WebImageCellValue.

Além desses campos partilhados, cada *CellValue tipo tem o seu próprio esquema. Por exemplo, WebImageCellValue inclui altText e attribution, enquanto EntityCellValue inclui properties e text.

As secções seguintes mostram padrões comuns para números formatados, valores básicos com propriedades adicionais, valores de entidade, entidades ligadas, imagens Web e erros melhorados.

Valores de número formatados

Utilize DoubleCellValue quando o valor numérico subjacente for importante, mas também pretende que o Excel mantenha um formato de apresentação específico com esse valor. Um cenário comum é devolver um valor de data de série e apresentá-lo como uma data na folha de cálculo.

O exemplo seguinte mostra o esquema JSON completo de um número formatado. Neste exemplo, myDate é apresentado como 16/1/1990 na IU do Excel. Se os requisitos mínimos de compatibilidade para tipos de dados não forem cumpridos, os cálculos utilizam basicValue.

const myDate: Excel.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

O formato de número num DoubleCellValue é o formato predefinido. Se um utilizador ou outra parte do seu suplemento aplicar formatação à célula mais tarde, esse formato aplicado substitui o formato do valor.

Para experimentar valores numéricos formatados, abra Script Lab e execute o exemplo Tipos de dados: Números formatados.

Valores básicos das células

Pode adicionar propriedades a valores básicos do Excel para associar informações adicionais aos mesmos. Este padrão funciona com os tipos básicos de cadeia, duplo e booleano . Utilize-o quando quiser que um valor de célula simples carregue campos relacionados sem transformar o valor numa entidade completa.

Por exemplo, um total de faturas pode incluir campos relacionados, como Bebidas, Alimentos, Impostos e Sugestão.

Captura de ecrã dos campos de bebidas, alimentos, impostos e gorjetas apresentados para o valor de célula selecionado.

Para obter as instruções completas, consulte Adicionar propriedades aos valores de células básicas do Excel.

Valores de entidade

Um EntityCellValue pode armazenar texto, tipos de dados aninhados e matrizes e o Excel pode apresentar esses dados numa entidade card.

O exemplo seguinte mostra o esquema JSON completo de um valor de entidade que representa uma fatura. A entidade inclui propriedades de texto a apresentar mais para uma imagem, uma data para conclusão e um valor de status.

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.
};

As basicType propriedades e basicValue definem como os cálculos leem uma entidade quando os requisitos mínimos de compatibilidade para tipos de dados não são cumpridos. Nesse caso, a entidade é apresentada como um erro #VALUE! na IU do Excel.

Importante

Um valor de entidade pode definir uma referencedValues matriz que armazena valores de célula adicionais. Estes valores são referenciados por índice a propertiespartir do .

  • A referencedValues matriz só é suportada na entidade ao nível da raiz numa árvore de valores de células.
  • As entidades aninhadas, que são entidades utilizadas como valores de propriedade dentro de outra entidade, não podem definir as suas próprias referencedValues.
  • Se uma entidade aninhada incluir uma referencedValues matriz, a API do Excel em JavaScript gera um GeneralException erro no suplemento ou código de script ou o Excel apresenta um erro #VALUE! quando uma função personalizada produz o valor.

Para referenciar valores de uma entidade aninhada, utilize índices ReferenceCellValue que apontam para a matriz da referencedValues entidade raiz.

Para explorar os tipos de dados de entidades, abra Script Lab e execute Tipos de dados: Criar cartões de entidade a partir de dados numa tabela. Para obter exemplos mais aprofundados, veja Tipos de dados: Valores de entidade com referências e Tipos de dados: propriedades de atribuição de valor de entidade.

Valores de células de entidade ligadas

LinkedEntityCellValue representa uma entidade que está ligada a uma origem de dados externa. Utilize entidades ligadas quando precisar de cartões para conjuntos de dados grandes ou atualizados frequentemente e não quiser carregar todos os detalhes para o livro de uma só vez.

Os domínios de dados Ações e Geografia disponíveis na IU do Excel são exemplos de valores de células de entidade ligadas.

Os valores das células de entidade ligadas oferecem as seguintes vantagens em função dos valores de entidade regulares.

  • Os valores das células de entidade ligadas podem ser aninhados e o Excel não obtém entidades ligadas aninhadas até que o utilizador ou a folha de cálculo as referencie. Este comportamento ajuda a reduzir o tamanho do ficheiro e a melhorar o desempenho do livro.
  • O Excel utiliza uma cache para que células diferentes possam referenciar o mesmo valor de célula de entidade ligada. Isto também ajuda no desempenho do livro.

Para obter detalhes de implementação, veja Criar tipos de dados de entidades ligadas em suplementos do Excel.

Valores de imagem da Web

Utilize WebImageCellValue quando o seu suplemento precisar de armazenar uma imagem num intervalo ou como parte de um valor de entidade. Este tipo inclui propriedades como address, altTexte relatedImagesAddress.

As basicType propriedades e basicValue definem como os cálculos leem uma imagem Web quando os requisitos mínimos de compatibilidade para tipos de dados não são cumpridos. Nesse caso, a imagem Web é apresentada como um erro #VALUE! na IU do Excel.

O exemplo seguinte mostra o esquema JSON completo de uma imagem Web.

const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw",
    basicType: Excel.RangeValueType.error,
    basicValue: "#VALUE!"
};

Para experimentar tipos de dados de imagens Web, abra Script Lab e execute Tipos de dados: imagens Web.

Suporte a erros aprimorado

As APIs de tipos de dados expõem erros de IU do Excel existentes como objetos. Esta abordagem permite que o suplemento defina ou obtenha propriedades como type, errorTypee errorSubType.

Os seguintes objetos de erro expandiram o suporte através de tipos de dados.

Cada objeto de erro pode aceder a uma enumeração através de errorSubType. Essa enumeração fornece mais detalhes sobre o erro específico. Por exemplo, BlockedErrorCellValueSubType fornece informações adicionais sobre o motivo do BlockedErrorCellValue erro.

Para saber mais, abra Script Lab e execute Tipos de dados: Definir valores de erro.

Próximas etapas

Confira também

  • Last updated on