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

Você pode especificar janelas modais de card na interface do usuário do Excel para vários tipos de dados de valor de célula. Os cartões podem exibir informações adicionais além do que já está visível em uma célula, como imagens relacionadas, informações de categorias de produtos e atribuições de dados.

Há suporte para cartões nos seguintes tipos de valores de célula.

• EntityCellValue
• LinkedEntityCellValue
• tipos básicos, duplos e booleanos

A captura de tela a seguir mostra um exemplo de um card de valor de entidade aberta, neste caso, para o produto Chef Anton's Gumbo Mix de uma lista de produtos de mercearia.

Propriedades do cartão

Use properties para especificar todas as informações personalizadas sobre os tipos de dados. A properties chave dá suporte a tipos de dados aninhados. Cada propriedade aninhada, ou tipo de dados, deve ter uma type configuração e basicValue .

O trecho de código a seguir mostra o JSON de um valor de entidade com vários tipos de dados aninhados em properties.

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 tela a seguir mostra um card de valor de entidade que usa o snippet de código anterior. A captura de tela mostra as informações de ID do Produto, Nome do Produto, Imagem, Quantidade por Unidade e Preço Unitário do snippet de código anterior.

Layout do cartão

Os valores de célula têm um tipo de dados padrão card que o usuário pode visualizar. Especifique um layout de card personalizado para melhorar a experiência do usuário ao visualizar propriedades. A layouts propriedade define a estrutura e a aparência do card. Use layouts para especificar atributos como um ícone, um título de card, uma imagem para um card e o número de seções a serem exibidas.

A layouts propriedade contém duas subpropriedades diretas compact e card. A card propriedade especifica a aparência de um card quando o card é aberto. A compact propriedade é opcional e define o ícone de um valor. O ícone será mostrado no valor da célula, se ele for fornecido. Ele também poderá ser mostrado no card se ele for referenciado como uma subpropriedade.

Consulte a EntityCompactLayoutIcons enumeração para obter uma lista completa de ícones disponíveis. O próximo trecho de código mostra como exibir o shoppingBag ícone.

Dentro da card propriedade, use o CardLayoutStandardProperties objeto para definir os componentes do card como title, subTitle, e sections.

O valor da entidade JSON no próximo trecho de código mostra um card layout com objetos e mainImage aninhadostitle, bem como três sections dentro do card. Observe que a title propriedade "Product Name" tem um tipo de dados correspondente na seção anterior do artigo Propriedades do cartão . A mainImage propriedade também tem um tipo de dados correspondente "Image" na seção anterior. A sections propriedade usa uma matriz aninhada e usa o CardLayoutSectionStandardProperties objeto para definir a aparência de cada seção.

Dentro de cada seção do card, você pode especificar elementos como layout, title, e properties. A layout chave usa o CardLayoutListSection objeto e aceita o valor "List". A properties chave aceita uma matriz de cadeias de caracteres. Observe que os properties valores, como "Product ID", têm tipos de dados correspondentes na seção anterior do artigo Propriedades do cartão . As seções também podem ser recolhíveis e podem ser definidas com valores booleanos como recolhidos ou não recolhidos quando o entity card é aberto na interface do usuário do Excel.

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 tela a seguir mostra um card de valor de entidade que usa os trechos de código anteriores. Na captura de tela, o shoppingBag ícone é exibido ao lado dos nomes dos produtos na planilha. No entity card, o mainImage objeto é exibido na parte superior, seguido pelo title objeto que usa o Nome do Produto e é definido como Chef Anton's Gumbo Mix. A captura de tela também mostra sections. A seção Quantidade e preço é recolhível e contém Quantidade por Unidade e Preço Unitário. O campo Informações adicionais é recolhível e é recolhido quando o card é aberto.

Metadados de propriedade

As propriedades de entidade têm um campo opcional propertyMetadata que usa o CellValuePropertyMetadata objeto e oferece as propriedades attribution, excludeFrom, e sublabel. O trecho de código a seguir mostra como adicionar um sublabel à "Unit Price" propriedade do trecho de código anterior. Nesse caso, o sub-rótulo identifica o tipo de moeda.

// 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 atribuição para informações provenientes de terceiros para indicar a fonte e qualquer informação de licença. Use Excel.CellValueAttributionAttributes para adicionar atribuição a um valor de célula. O exemplo de código a seguir mostra como adicionar atribuição para uso de informações sobre o planeta Marte da Wikipedia.

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 a seguir mostra como a atribuição é exibida no tipo de dados card para o usuário.

Informações do provedor

Você pode adicionar informações sobre seu suplemento, ou serviço, que é a fonte para as informações no tipo de dados card. Use Excel.CellValueProviderAttributes para adicionar as informações do provedor. O exemplo de código a seguir mostra como adicionar informações do provedor para a pesquisa genérica da Contoso como a fonte de 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 a seguir mostra como as informações do provedor aparecem como o logotipo no data type card para o usuário.

Próximas etapas

Experimente o exemplo Criar e explorar tipos de dados no Excel em nosso repositório OfficeDev/Office-Add-in-samples . Este exemplo orienta você na criação e no sideload de um suplemento que cria e edita tipos de dados em uma pasta de trabalho.

Confira também

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