Compartilhar via

Conceitos básicos dos tipos de dados do Excel

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 DoubleCellValue permite que os suplementos do Excel definam uma numberFormat propriedade para 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.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"
};

A formatação de números é considerada o formato predefinido. Se o utilizador, ou outro código, aplicar formatação a uma célula que contenha um número formatado, o formato aplicado substitui o formato do número.

Comece a experimentar valores numéricos formatados ao abrir Script Lab e verificar os Tipos de dados: Fragmento de números formatados na nossa biblioteca de Exemplos.

Valores básicos das células

Adicione propriedades a valores básicos de células no Excel para associar informações adicionais aos valores. Semelhante aos valores de entidade, pode adicionar propriedades aos tipos básicos de cadeia, duplo e booleano . Cada propriedade é um par chave/valor. O exemplo seguinte mostra o número 104,67 (um duplo) que representa uma fatura com campos adicionados denominados 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 mais informações, veja Adicionar propriedades a valores básicos de células.

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

Para explorar os tipos de dados de entidades, comece por aceder a Script Lab 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.

Valores de células de entidade ligadas

Os valores de células de entidade ligadas, ou objetos LinkedEntityCellValue, são tipos de dados integrados de origens de dados externas e podem apresentar os dados como uma entidade card. Permitem-lhe dimensionar os seus tipos de dados para representar grandes conjuntos de dados sem transferir todos os dados para o livro. Os domínios de dados Ações e Geografia disponíveis através da IU do Excel fornecem valores de células de entidade ligadas.

Os valores das células de entidade ligadas estão ligados a uma origem de dados externa. Fornecem as seguintes vantagens em função dos valores de entidade regulares:

  • Os valores das células de entidade ligadas podem aninhar e os valores das células de entidade ligada aninhadas não são obtidos até serem referenciados pelo utilizador ou pela folha de cálculo. Isto ajuda a reduzir o tamanho do ficheiro e a melhorar o desempenho do livro.
  • O Excel utiliza uma cache para permitir que células diferentes referenciem o mesmo valor de célula de entidade ligada de forma totalmente integrada. Isto também melhora o desempenho do livro.

Para obter mais informações, veja Criar valores de células de entidade ligada.

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 Script Lab 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 dos tipos de dados ao consultar Os tipos de dados: Definir fragmento de valores de erro na nossa biblioteca Script LabSamples.

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