Usar tipos de dados em suplementos do Excel

Quando o suplemento precisar de mais do que cadeias de caracteres, números e booleanos, use tipos de dados do Excel. Os tipos de dados permitem retornar valores aprimorados, como datas formatadas, cartões de entidade, registros vinculados e imagens da Web, enquanto ainda dão suporte a cálculos de planilha.

Este artigo explica a API que alimenta os valuesAsJson tipos de dados e mostra quando usar os principais tipos de valor de célula. Para obter uma visão geral de recursos, consulte Visão geral de tipos de dados em suplementos do Excel.

Para experimentar esses conceitos imediatamente, abra o Script Lab no Excel e procure os exemplos de tipos de dados na biblioteca de exemplos.

A propriedade valuesAsJson

A valuesAsJson propriedade é a API principal para ler e gravar tipos de dados do Excel. A propriedade singular valueAsJson em NamedItem serve à mesma finalidade para um único item nomeado.

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

Os objetos a seguir expõem valuesAsJson.

Observação

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

Valores da célula

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

Os tipos que a maioria dos suplementos usa 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ó. Ela adiciona propriedades que ajudam a controlar como os valores de célula são substituídos.

Esquema JSON

Cada valor que valuesAsJson retorna usa um esquema de metadados JSON projetado para esse tipo de valor de célula. Embora cada tipo tenha suas próprias propriedades, todos os esquemas compartilham type, basicType, e basicValue.

type define o CellValueType. basicType é somente leitura e fornece o tipo de fallback quando o tipo de dados não tem suporte ou está formatado incorretamente. basicValue corresponde ao valor retornado pela values propriedade e atua como fallback quando os cálculos encontram cenários incompatíveis, como uma versão mais antiga do Excel que não dá suporte a tipos de dados. basicValue é somente leitura para ArrayCellValue, EntityCellValue, LinkedEntityCellValuee WebImageCellValue.

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

As seções a seguir mostram padrões comuns para números formatados, valores básicos com propriedades extras, valores de entidade, entidades vinculadas, imagens da web e erros aprimorados.

Valores de número formatados

Use DoubleCellValue quando o valor numérico subjacente for importante, mas você também quiser que o Excel mantenha um formato de exibição específico com esse valor. Um cenário comum é retornar um valor de data serial e exibi-lo como uma data na planilha.

O exemplo a seguir mostra o esquema JSON completo para um número formatado. Neste exemplo, myDate é exibido como 16/01/1990 na interface do usuário do Excel. Se os requisitos mínimos de compatibilidade para os tipos de dados não forem atendidos, os cálculos usarão 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 em a DoubleCellValue é o formato padrão. Se um usuário ou outra parte do suplemento aplicar formatação à célula posteriormente, esse formato aplicado substituirá o formato do valor.

Para experimentar valores de número formatados, abra o Script Lab e execute o exemplo Tipos de dados: números formatados.

Valores básicos de célula

Você pode adicionar propriedades aos valores básicos do Excel para associar informações extras a eles. Esse padrão funciona com os tipos básicos de cadeia de caracteres, duplo e booliano . Use-o quando quiser que um valor de célula simples carregue os campos relacionados sem transformar o valor em uma entidade completa.

Por exemplo, o total da fatura pode incluir campos relacionados, como Bebidas, Comida, Impostos e Gorjeta.

Captura de tela dos campos bebidas, comida, impostos e gorjetas mostrados para o valor da célula selecionada.

Para obter o passo a passo completo, consulte Adicionar propriedades a 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 exibir esses dados em uma entidade card.

O exemplo a seguir mostra o esquema JSON completo para um valor de entidade que representa uma fatura. A entidade inclui texto de exibição mais propriedades para uma imagem, uma data de vencimento 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 and basicValue definem como os cálculos leem uma entidade quando os requisitos mínimos de compatibilidade para tipos de dados não são atendidos. Nesse caso, a entidade é exibida como um erro #VALUE! na interface do usuário do Excel.

Importante

Um valor de entidade pode definir uma referencedValues matriz que armazena valores de célula adicionais. Esses valores são referenciados pelo índice de dentro do arquivo properties.

  • A referencedValues matriz só tem suporte na entidade de nível raiz em uma árvore de valores de célula.
  • Entidades aninhadas, que são entidades usadas como valores de propriedade dentro de outra entidade, não devem definir seus próprios referencedValues.
  • Se uma entidade aninhada incluir uma referencedValues matriz, a API do Excel no JavaScript lançará um GeneralException erro no código do suplemento ou de script, ou o Excel exibirá um erro #VALUE! quando uma função personalizada produzir o valor.

Para fazer referência a valores de uma entidade aninhada, use índices ReferenceCellValue que apontam para a matriz da referencedValues entidade raiz.

Para explorar tipos de dados de entidade, abra o Script Lab e execute Tipos de dados: Crie cartões de entidade a partir de dados em uma tabela. Para obter exemplos mais detalhados, consulte Tipos de dados: valores de entidade com referências e Tipos de dados: propriedades de atribuição de valor de entidade.

Valores de célula de entidade vinculada

LinkedEntityCellValue representa uma entidade conectada a uma fonte de dados externa. Use entidades vinculadas quando precisar de cartões para conjuntos de dados grandes ou atualizados com frequência e não quiser carregar todos os detalhes na pasta de trabalho de uma vez.

Os domínios de dados de Ações e Geografia disponíveis na interface do usuário do Excel são exemplos de valores de células de entidade vinculadas.

Os valores de células de entidade vinculada oferecem as seguintes vantagens sobre os valores de entidade regulares.

  • Valores de células de entidades vinculadas podem se aninhar, e o Excel não recupera entidades vinculadas aninhadas até que o usuário ou a planilha faça referência a elas. Esse comportamento ajuda a reduzir o tamanho do arquivo e melhorar o desempenho da pasta de trabalho.
  • O Excel usa um cache para que células diferentes possam fazer referência ao mesmo valor de célula de entidade vinculada. Isso também ajuda no desempenho da pasta de trabalho.

Para obter detalhes de implementação, consulte Criar tipos de dados de entidade vinculada em suplementos do Excel.

Valores de imagem da Web

Use WebImageCellValue quando o suplemento precisar armazenar uma imagem em um intervalo ou como parte de um valor de entidade. Esse tipo inclui propriedades como address, altText, e relatedImagesAddress.

As basicType propriedades and basicValue definem como os cálculos leem uma imagem da Web quando os requisitos mínimos de compatibilidade para tipos de dados não são atendidos. Nesse caso, a imagem da Web é exibida como um erro #VALUE! na interface do usuário do Excel.

O exemplo a seguir mostra o esquema JSON completo de uma imagem da 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 imagem da Web, abra o Script Lab e execute Tipos de dados: Imagens da Web.

Suporte a erros aprimorado

As APIs de tipos de dados expõem erros existentes da interface do usuário do Excel como objetos. Essa abordagem permite que o suplemento defina ou recupere propriedades como type, errorTypee errorSubType.

Os objetos de erro a seguir expandiram o suporte por meio de tipos de dados.

Cada objeto de erro pode acessar uma enumeração por meio de errorSubType. Essa enumeração fornece mais detalhes sobre o erro específico. Por exemplo, BlockedErrorCellValueSubType fornece informações adicionais sobre por que isso BlockedErrorCellValue ocorreu.

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

Próximas etapas

Confira também

  • Last updated on