Utilizar cartões com tipos de dados de valor de célula

Pode especificar card janelas modais na IU do Excel para vários tipos de dados de valores de células. Os cartões podem apresentar informações adicionais para além do que já está visível numa célula, como imagens relacionadas, informações de categorias de produtos e atribuições de dados.

Observação

Este artigo expande as informações descritas no artigo Conceitos principais de tipos de dados do Excel . Recomendamos que leia este artigo antes de saber mais sobre cartões para valores de células.

Os cartões são suportados para os seguintes tipos de valores de célula.

• EntityCellValue
• LinkedEntityCellValue
• tipos básicos de cadeia, duplo e Booleano

A seguinte captura de ecrã mostra um exemplo de um valor de entidade aberto card, neste caso para o produto Gumbo Mix do Chef Anton a partir de uma lista de produtos de mercearia.

Propriedades do cartão

Utilize properties para especificar todas as informações personalizadas sobre os seus tipos de dados. A properties chave suporta tipos de dados aninhados. Cada propriedade aninhada, ou tipo de dados, tem de ter uma type definição e basicValue .

Importante

Os tipos de dados aninhados properties são utilizados em combinação com os valores de esquema Cartão descritos na secção do artigo subsequente. Depois de definir um tipo de dados aninhado em properties, tem de ser atribuído na layouts propriedade a apresentar no card.

O fragmento de código seguinte mostra o JSON para um valor de entidade com vários tipos de dados aninhados no properties.

Observação

Para experimentar este fragmento de código num exemplo completo, abra Script Lab no Excel e selecione Tipos de dados: Criar cartões de entidade a partir de dados numa tabela na nossa biblioteca de Exemplos.

const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
        "Product ID": {
            type: Excel.CellValueType.string,
            basicValue: productID.toString() || ""
        },
        "Product Name": {
            type: Excel.CellValueType.string,
            basicValue: productName || ""
        },
        "Image": {
            type: Excel.CellValueType.webImage,
            address: product.productImage || ""
        },
        "Quantity Per Unit": {
            type: Excel.CellValueType.string,
            basicValue: product.quantityPerUnit || ""
        },
        "Unit Price": {
            type: Excel.CellValueType.double,
            basicValue: product.unitPrice,
            numberFormat: "$* #,##0.00"
        },
        Discontinued: {
            type: Excel.CellValueType.boolean,
            basicValue: product.discontinued || false
        }
    },
    layouts: {
        // Enter layout settings here.
    }
};

A captura de ecrã seguinte mostra um valor de entidade card que utiliza o fragmento de código anterior. A captura de ecrã mostra as informações ID do Produto, Nome do Produto, Imagem, Quantidade Por Unidade e Preço Unitário do fragmento de código anterior.

Esquema de cartão

Os valores das células têm um tipo de dados predefinido card que o utilizador pode ver. Especifique um esquema de card personalizado para melhorar a experiência do utilizador ao visualizar as propriedades. A layouts propriedade define a estrutura e o aspeto do card. Utilize layouts para especificar atributos como um ícone, card título, imagem para um card e o número de secções a apresentar.

Importante

Os valores aninhados layouts são utilizados em combinação com os tipos de dados de propriedades do Cartão descritos na secção do artigo anterior. Um tipo de dados aninhado tem de ser definido no properties antes de poder ser atribuído layouts para ser apresentado no card.

A layouts propriedade contém dois subpropriedades diretas compact e card. A card propriedade especifica o aspeto de uma card quando o card está aberto. A compact propriedade é opcional e define o ícone de um valor. O ícone é apresentado no valor da célula, se for fornecido. Também pode ser apresentado no card se for referenciado como uma subpropriedade.

Veja a enumeração EntityCompactLayoutIcons para obter uma lista completa dos ícones disponíveis. O fragmento de código seguinte mostra como apresentar o shoppingBag ícone.

card Na propriedade , utilize o CardLayoutStandardProperties objeto para definir os componentes do card como title, subTitlee sections.

O valor da entidade JSON no fragmento de código seguinte mostra um card esquema com objetos e mainImage aninhadostitle, bem como três sections dentro do card. Tenha em atenção que a title propriedade "Product Name" tem um tipo de dados correspondente na secção de artigo propriedades do Cartão anterior. A mainImage propriedade também tem um tipo de dados correspondente "Image" na secção anterior. A sections propriedade utiliza uma matriz aninhada e utiliza o CardLayoutSectionStandardProperties objeto para definir o aspeto de cada secção.

Em cada card secção, pode especificar elementos como layout, titlee properties. A layout chave utiliza o CardLayoutListSection objeto e aceita o valor "List". A properties chave aceita uma matriz de cadeias. Tenha em atenção que os properties valores, como "Product ID", têm tipos de dados correspondentes na secção do artigo propriedades do Cartão anterior. As secções também podem ser minimizáveis e podem ser definidas com valores booleanos como fechados ou não fechados quando a entidade card é aberta na IU do Excel.

Dica

A layout chave também tem opções de visualização adicionais disponíveis para além "List" card secções. Utilize "Table" para Excel.CardLayoutTableSection e "TwoColumn" para Excel.CardLayoutTwoColumnSection. Tenha em atenção que o "TwoColumn" esquema só está disponível em pré-visualização.

Observação

Para experimentar este fragmento de código num exemplo completo, abra Script Lab no Excel e selecione Tipos de dados: Criar cartões de entidade a partir de dados numa tabela na nossa biblioteca de Exemplos.

const entity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: productName,
    properties: {
        // Enter property settings here.
    },
    layouts: {
        compact: {
            icon: Excel.EntityCompactLayoutIcons.shoppingBag
        },
        card: {
            title: { 
                property: "Product Name" 
            },
            mainImage: { 
                property: "Image" 
            },
            sections: [
                {
                    layout: "List",
                    properties: ["Product ID"]
                },
                {
                    layout: "List",
                    title: "Quantity and price",
                    collapsible: true,
                    collapsed: false, // This section will not be collapsed when the card is opened.
                    properties: ["Quantity Per Unit", "Unit Price"]
                },
                {
                    layout: "List",
                    title: "Additional information",
                    collapsible: true,
                    collapsed: true, // This section will be collapsed when the card is opened.
                    properties: ["Discontinued"]
                }
            ]
        }
    }
};

A captura de ecrã seguinte mostra um valor de entidade card que utiliza os fragmentos de código anteriores. Na captura de ecrã, o shoppingBag ícone é apresentado juntamente com os nomes dos produtos na folha de cálculo. Na entidade card, o mainImage objeto é apresentado na parte superior, seguido do title objeto que utiliza o Nome do Produto e está definido como Gumbo Mix do Chef Anton. A captura de ecrã também mostra sections. A secção Quantidade e preço é minimizável e contém Quantidade Por Unidade e Preço Unitário. O campo Informações adicionais é minimizável e é fechado quando o card é aberto.

Observação

Na captura de ecrã anterior, o branch ícone é apresentado juntamente com Condimentos na secção Categoria . Veja Os Tipos de dados: Criar cartões de entidade a partir de dados num exemplo de tabela para saber como definir ícones aninhados, como o ícone da secção Categoria .

Existe um problema conhecido com ícones aninhados no Excel no Mac. Nesse ambiente, os ícones aninhados serão sempre apresentados como o generic ícone, independentemente do ícone selecionado com a enumeração EntityCompactLayoutIcons .

Metadados de propriedade

As propriedades da entidade têm um campo opcional propertyMetadata que utiliza o CellValuePropertyMetadata objeto e oferece as propriedades attribution, excludeFrome sublabel. O fragmento de código seguinte mostra como adicionar um sublabel à propriedade a "Unit Price" partir do fragmento de código anterior. Neste caso, a sub-etiqueta identifica o tipo de moeda.

Observação

O propertyMetadata campo só está disponível em tipos de dados aninhados nas propriedades da entidade.

// This code snippet is an excerpt from the `properties` field of the 
// preceding `EntityCellValue` snippet. "Unit Price" is a property of 
// an entity value.
    "Unit Price": {
        type: Excel.CellValueType.double,
        basicValue: product.unitPrice,
        numberFormat: "$* #,##0.00",
        propertyMetadata: {
          sublabel: "USD"
        }
    },

Atribuição

Adicione a atribuição para informações provenientes de terceiros para indicar a origem e quaisquer informações de licença. Utilize Excel.CellValueAttributionAttributes para adicionar a atribuição a um valor de célula. O seguinte exemplo de código mostra como adicionar a atribuição para a utilização de informações sobre o planeta Marte a partir da Wikipédia.

async function createPlanet() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        const attributionObject: Excel.CellValueAttributionAttributes = {
            licenseAddress: "https://en.wikipedia.org/wiki/Wikipedia:Wikipedia_is_free_content",
            licenseText: "Free usage information",
            sourceAddress: "https://en.wikipedia.org/wiki/Mars",
            sourceText: "Wikipedia"
        };

        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    basicValue: 6779, // kilometers (radius)
                    properties: {
                        Name: {
                            type: Excel.CellValueType.string,
                            basicType: Excel.RangeValueType.string,
                            basicValue: "Mars",
                            propertyMetadata: {
                                sublabel: "Planetary Body",
                                attribution: [attributionObject]
                            }
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

A imagem seguinte mostra como a atribuição é apresentada no tipo de dados card para o utilizador.

Informações do fornecedor

Pode adicionar informações sobre o seu suplemento ou serviço, que é a origem das informações no tipo de dados card. Utilize Excel.CellValueProviderAttributes para adicionar as informações do seu fornecedor. O seguinte exemplo de código mostra como adicionar informações do fornecedor para a pesquisa genérica da Contoso como a origem dos dados de pesquisa para o valor da célula.

async function createSearchEntry() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");

        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.string,
                    basicType: Excel.RangeValueType.string,
                    basicValue: "cell function - Microsoft support",
                    properties: {
                        "Search Keywords": {
                            type: Excel.CellValueType.string,
                            basicType: Excel.RangeValueType.string,
                            basicValue: "Cell Values"
                        }
                    },
                    provider: {
                        description: "Contoso generic search",
                        // Image credit: Ignacio javier igjav, Public domain, via Wikimedia Commons
                        logoSourceAddress: "https://upload.wikimedia.org/wikipedia/commons/f/f9/Lupa.png",
                        logoTargetAddress: "https://contoso.com"
                    }
                }
            ]
        ];

        await context.sync();
    });
}

A imagem seguinte mostra como as informações do fornecedor são apresentadas como o logótipo no tipo de dados card para o utilizador.

Próximas etapas

Experimente o exemplo Criar e explorar tipos de dados no Excel no nosso repositório OfficeDev/Office-Add-in-samples . Este exemplo orienta-o ao longo da criação e, em seguida, do sideload de um suplemento que cria e edita tipos de dados num livro.

Confira também

• Visão geral dos tipos de dados em suplementos do Excel
• Conceitos básicos dos tipos de dados do Excel
• Criar e explorar tipos de dados no Excel
• Referência da API JavaScript do Excel