Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Puede especificar ventanas modales de tarjeta en la interfaz de usuario de Excel para varios tipos de datos de valor de celda. Las tarjetas pueden mostrar información adicional más allá de lo que ya está visible en una celda, como imágenes relacionadas, información de la categoría de producto y atribución de datos.
Nota:
En este artículo se amplía la información descrita en el artículo conceptos básicos de tipos de datos de Excel . Se recomienda leer ese artículo antes de aprender sobre las tarjetas para los valores de celda.
Las tarjetas se admiten para los siguientes tipos de valor de celda.
- EntityCellValue
- LinkedEntityCellValue
- tipos básicos string, double y Boolean
En la captura de pantalla siguiente se muestra un ejemplo de una tarjeta de valor de entidad abierta, en este caso para el producto Gumbo Mix del chef Anton de una lista de productos de la tienda de comestibles.
Propiedades de tarjeta
Use properties para especificar toda la información personalizada sobre los tipos de datos. La properties clave admite tipos de datos anidados. Cada propiedad anidada, o tipo de datos, debe tener un type valor y basicValue .
Importante
Los tipos de datos anidados properties se usan en combinación con los valores de diseño de tarjeta descritos en la sección del artículo siguiente. Después de definir un tipo de datos anidado en properties, se debe asignar en la layouts propiedad para que se muestre en la tarjeta.
El siguiente fragmento de código muestra el CÓDIGO JSON de un valor de entidad con varios tipos de datos anidados dentro de properties.
Nota:
Para experimentar con este fragmento de código en un ejemplo completo, abra Script Lab en Excel y seleccione Tipos de datos: Crear tarjetas de entidad a partir de datos en una tabla de nuestra biblioteca de ejemplos.
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.
}
};
En la captura de pantalla siguiente se muestra una tarjeta de valor de entidad que usa el fragmento de código anterior. En la captura de pantalla se muestra la información de Id. de producto, Nombre del producto, Imagen, Cantidad por unidad y Precio unitario del fragmento de código anterior.
Diseño de tarjeta
Los valores de celda tienen una tarjeta de tipo de datos predeterminada que el usuario puede ver. Especifique un diseño de tarjeta personalizado para mejorar la experiencia del usuario al ver las propiedades. La layouts propiedad define la estructura y el aspecto de la tarjeta. Use layouts para especificar atributos como un icono, el título de la tarjeta, la imagen de una tarjeta y el número de secciones que se van a mostrar.
Importante
Los valores anidados layouts se usan en combinación con los tipos de datos Propiedades de tarjeta descritos en la sección del artículo anterior. Se debe definir un tipo de datos anidado en properties para poder asignarlo layouts a para mostrarlo en la tarjeta.
La layouts propiedad contiene dos subpropiedades directas, compact y card. La card propiedad especifica la apariencia de una tarjeta cuando la tarjeta está abierta. La compact propiedad es opcional y define el icono de un valor. El icono se muestra en el valor de celda si se proporciona. También se puede mostrar en la tarjeta si se hace referencia a ella como una subpropiedad.
Consulte la EntityCompactLayoutIcons enumeración para obtener una lista completa de los iconos disponibles. El siguiente fragmento de código muestra cómo mostrar el shoppingBag icono.
Dentro de la card propiedad , use el CardLayoutStandardProperties objeto para definir los componentes de la tarjeta, como title, subTitley sections.
El valor de entidad JSON del siguiente fragmento de código muestra un card diseño con objetos anidados title y mainImage , además, tres sections dentro de la tarjeta. Tenga en cuenta que la title propiedad "Product Name" tiene un tipo de datos correspondiente en la sección de artículo propiedades de tarjeta anterior. La mainImage propiedad también tiene un tipo de datos correspondiente "Image" en la sección anterior. La sections propiedad toma una matriz anidada y usa el CardLayoutSectionStandardProperties objeto para definir la apariencia de cada sección.
Dentro de cada sección de tarjeta puede especificar elementos como layout, titley properties. La layout clave usa el CardLayoutListSection objeto y acepta el valor "List". La properties clave acepta una matriz de cadenas. Tenga en cuenta que los properties valores, como "Product ID", tienen los tipos de datos correspondientes en la sección de artículo propiedades de tarjeta anterior. Las secciones también pueden contraerse y se pueden definir con valores booleanos como contraídos o no contraídos cuando se abre la tarjeta de entidad en la interfaz de usuario de Excel.
Sugerencia
La layout clave también tiene opciones de visualización adicionales disponibles más allá de "List" las secciones de tarjeta. Use "Table" para Excel.CardLayoutTableSection y "TwoColumn" para Excel.CardLayoutTwoColumnSection. Tenga en cuenta que el "TwoColumn" diseño solo está disponible en versión preliminar.
Nota:
Para experimentar con este fragmento de código en un ejemplo completo, abra Script Lab en Excel y seleccione Tipos de datos: Crear tarjetas de entidad a partir de datos en una tabla de nuestra biblioteca de ejemplos.
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"]
}
]
}
}
};
En la captura de pantalla siguiente se muestra una tarjeta de valor de entidad que usa los fragmentos de código anteriores. En la captura de pantalla, el shoppingBag icono se muestra junto con los nombres de producto de la hoja de cálculo. En la tarjeta de entidad, el mainImage objeto se muestra en la parte superior, seguido del title objeto que usa el nombre del producto y se establece en La combinación gumbo del chef Anton. La captura de pantalla también muestra sections. La sección Cantidad y precio es contraíble y contiene Cantidad por unidad y Precio unitario. El campo Información adicional es contraíble y se contrae cuando se abre la tarjeta.
Nota:
En la captura de pantalla anterior, el branch icono se muestra junto con Condiments en la sección Categoría . Consulte Tipos de datos: Crear tarjetas de entidad a partir de datos en un ejemplo de tabla para obtener información sobre cómo establecer iconos anidados como el icono de sección Categoría .
Hay un problema conocido con los iconos anidados en Excel en Mac. En ese entorno, los iconos anidados siempre se mostrarán como el generic icono, independientemente del icono seleccionado con la EntityCompactLayoutIcons enumeración.
Metadatos de propiedad
Las propiedades de entidad tienen un campo opcional propertyMetadata que usa el CellValuePropertyMetadata objeto y ofrece las propiedades attribution, excludeFromy sublabel. El siguiente fragmento de código muestra cómo agregar un sublabel elemento a la "Unit Price" propiedad del fragmento de código anterior. En este caso, la subetiqueta identifica el tipo de moneda.
Nota:
El propertyMetadata campo solo está disponible en los tipos de datos anidados dentro de las propiedades de la entidad.
// 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"
}
},
Atribución
Agregue atribución para la información que procede de terceros para indicar el origen y cualquier información de licencia. Use Excel.CellValueAttributionAttributes para agregar atribución a un valor de celda. En el ejemplo de código siguiente se muestra cómo agregar atribución para el uso de información sobre el planeta Marte desde 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();
});
}
En la imagen siguiente se muestra cómo se muestra la atribución en la tarjeta de tipo de datos del usuario.
Información del proveedor
Puede agregar información sobre el complemento o el servicio, que es el origen de la información en la tarjeta de tipo de datos. Use Excel.CellValueProviderAttributes para agregar la información del proveedor. En el ejemplo de código siguiente se muestra cómo agregar información del proveedor para la búsqueda genérica de Contoso como origen de datos de búsqueda para el valor de celda.
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();
});
}
En la imagen siguiente se muestra cómo aparece la información del proveedor como logotipo en la tarjeta de tipo de datos para el usuario.
Pasos siguientes
Pruebe el ejemplo Crear y explorar tipos de datos en Excel en nuestro repositorio OfficeDev/Office-Add-in-samples . Este ejemplo le guía a través de la compilación y, a continuación, la transferencia local de un complemento que crea y edita tipos de datos en un libro.
Vea también
Colaborar con nosotros en GitHub
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.