List Filter Online Introducción
El formato de columna es una función de SharePoint Online que modifica la presentación de una columna mediante una descripción JSON: un estado como etiqueta coloreada, un número con un color según su valor o una persona como vínculo para iniciar un correo electrónico. La descripción se guarda en la propia columna y SharePoint la aplica en todas las vistas de la lista.
List Filter Online puede utilizar estas descripciones. Al activar la opción, el elemento web lee el JSON de formato de cada columna que lo tenga y lo usa para representar las celdas, de modo que la tabla de la página se parezca a la lista de origen. El elemento web implementa un subconjunto de uso habitual del lenguaje de formato. Este artículo detalla qué admite, qué no admite y qué ocurre cuando un formato excede ese subconjunto.
📝 Nota
El elemento web aplica únicamente formato de columna. No lee el formato de vista, es decir, el JSON que da formato a filas o a toda la vista, porque no utiliza vistas de lista.
Activar el formato de columna
Edite la página, abra el panel de propiedades del elemento web y expanda Apariencia. Active Usar formato de columna de la lista. La opción está desactivada de forma predeterminada.
El JSON no se introduce en el elemento web. Procede de la definición de la columna en la lista de origen, la misma que SharePoint modifica al abrir Configuración de columna → Dar formato a esta columna y guardar un formato. El elemento web lo carga junto con las demás propiedades de las columnas, por lo que también aplica formatos de listas de otros sitios. El formato es independiente por columna: las que lo tienen se representan con él y las demás mantienen el formato elegido en el configurador (consulte KB10258. Configurar columnas en List Filter Online: títulos, formatos y opciones de visualización).
Cuando se aplica un formato, este sustituye la celda completa, incluida la opción Vinculado al elemento. Incluya un vínculo en el propio formato si quiere que se pueda seguir haciendo clic en el valor.
Funciones compatibles
Elementos
Un formato es un árbol de elementos. Cada elemento es un objeto con las siguientes claves:
elmType: uno de los valoresdiv,span,a,img,buttonop. Cualquier otro valor, salvo los no compatibles indicados más adelante, se representa comodiv.txtContent: texto del elemento, como cadena literal, token de campo o expresión.style: propiedades CSS del elemento (véase más adelante).attributes: atributos HTML del elemento (véase más adelante).children: matriz de elementos secundarios, representados en orden.
Las claves que el elemento web no reconoce, como $schema o debugMode, se ignoran.
Estilos
El objeto style puede establecer las siguientes propiedades CSS. Cada valor puede ser un literal o una expresión:
background, background-color, border, border-top, border-right, border-bottom, border-left, border-color, border-style, border-width, border-radius, box-shadow, color, cursor, direction, display, fill, flex-direction, flex-wrap, align-items, justify-content, font-family, font-size, font-style, font-weight, letter-spacing, line-height, text-align, text-decoration, text-overflow, text-transform, white-space, word-break, overflow, opacity, visibility, padding, padding-top, padding-right, padding-bottom, padding-left, margin, margin-top, margin-right, margin-bottom, margin-left, width, min-width, max-width, height, min-height, max-height.
Las propiedades no incluidas, como position o z-index, que podrían alterar el diseño de la tabla, se omiten sin aviso. También se omiten los valores que contienen url(, por lo que no se pueden cargar imágenes de fondo mediante estilos.
Atributos
| Atributo | Elementos | Comportamiento |
|---|---|---|
class | todos | Establece la clase CSS. Se aceptan clases de SharePoint como sp-field-severity--good, pero no aportan estilo en la página. Utilice style para los colores. |
title | todos | Establece la información sobre herramientas. |
href | a | Dirección del vínculo. Se permiten http:, https:, mailto:, tel: y direcciones relativas. Cualquier otro esquema se descarta y el elemento se representa sin vínculo. Los vínculos reciben rel="noreferrer". |
target | a | Ventana de destino del vínculo. Si no se especifica, se usa _blank, una pestaña nueva. |
src, alt | img | Dirección y texto alternativo de la imagen. Se aplican las mismas reglas que para href. Una imagen sin src válido no se representa. |
iconName | todos | Nombre de un icono de Fluent UI, como Mail o CheckMark, que se inserta delante del texto del elemento. |
Los demás atributos, incluidos role, aria-*, d y data-interception, se ignoran.
Tokens de campo
| Token | Valor |
|---|---|
@currentField | Valor de la columna a la que se aplica el formato. |
@currentField.prop | Propiedad del valor: para una persona, title, email, id, jobTitle, department o picture; para una búsqueda, lookupValue o lookupId; para un hipervínculo, Url o Description. |
[$Field] | Valor de otra columna del mismo elemento, identificada por su nombre interno. |
[$Field.prop] | Propiedad de ese valor, con los mismos nombres de propiedad. |
@me | Dirección de correo electrónico del usuario actual. |
@now | Fecha y hora actuales. |
Los tokens pueden aparecer solos ("txtContent": "@currentField") o dentro de una cadena más larga ("txtContent": "Propietario: [$Owner.title]"). Una columna con varios valores -personas, búsquedas o términos- se muestra como lista separada por comas. El acceso a propiedades, como [$Owner.email], devuelve la propiedad del primer valor. Las personas y búsquedas muestran su nombre; las fechas se muestran con el formato regional.
Expresiones
Las expresiones pueden escribirse como árboles de operadores, objetos con operator y operands, o como cadenas que comienzan por =, con la sintaxis de SharePoint similar a Excel. Ambas formas admiten las mismas operaciones:
- aritmética:
+(también concatena cadenas),-,*,/,%; - comparación:
==,!=,>,<,>=,<=; las fechas se comparan por su marca de tiempo; - lógica:
&&,||,!, el condicional? :(en un árbol, el operador?o:con tres operandos) y la funciónif(condition, whenTrue, whenFalse); - conversión:
toString(),Number(),Date(); - números:
abs(),floor(),ceiling(); - cadenas:
toLowerCase(),toUpperCase(),indexOf(),substring(),length().
En las cadenas =, los literales de texto se escriben entre comillas simples o dobles, los números con dígitos y los booleanos como true y false. Los paréntesis agrupan subexpresiones y los tokens de campo se usan directamente: =if([$Priority] == 'High', '#a4262c', '#323130').
Funciones no compatibles
El elemento web no implementa las siguientes partes del lenguaje de formato de columna:
forEach: repetición de un elemento por cada valor de una columna multivalor;customRowAction: botones que inician un flujo, abren un panel o establecen el valor de un campo;elmType: "filepreview": vistas previas de documentos;elmType: "svg"ypath: gráficos vectoriales en línea;- los tokens
@rowIndex,@window,@thumbnail,@currentWeby otros no indicados anteriormente; - los operadores y funciones no indicados anteriormente, como
toLocaleString(),toLocaleDateString(),startsWith(),padStart(),replace(),split(),join(),getDate(),addDays(),getUserImage(),cos()ysin().
No puede representarse un formato que utilice forEach, customRowAction, filepreview, svg, un operador o función desconocidos, un token @ desconocido en una expresión = o un error de sintaxis en una expresión =. En ese caso, el elemento web descarta el formato y muestra la columna con su presentación predeterminada, elegida en el configurador, como si la opción estuviera desactivada para esa columna. Las demás columnas no se ven afectadas. En cambio, los atributos y propiedades de estilo desconocidos simplemente se omiten y se aplica el resto del formato.
❗ Importante
Los formatos generados por el diseñador de SharePoint y los ejemplos de Microsoft suelen utilizar funciones ajenas al subconjunto compatible, como forEach, customRowAction, getUserImage() o toLocaleDateString(). Un formato que funciona en la lista puede, por tanto, volver a la presentación predeterminada en el elemento web. Compruebe siempre el resultado en la página después de activar la opción y simplifique el formato si una columna no se muestra como esperaba.
📝 Nota
Los valores pueden llegar como texto con la configuración regional de la lista. Use Number() o Date() solo con formatos que estas funciones reconozcan: los separadores decimales, de miles y los formatos de fecha locales pueden convertirse incorrectamente. Una referencia a otra columna no garantiza un número o una fecha sin procesar. Compruebe los valores reales y simplifique el formato si la conversión no es fiable.
Dentro de cadenas más largas se sustituyen @currentField, sus propiedades y las referencias [$Field]. Use @me y @now solos o en expresiones =. Un token @ desconocido provoca la presentación predeterminada en una expresión =; en texto normal permanece literal.
Ejemplos
Los siguientes formatos se mantienen dentro del subconjunto compatible.
Una etiqueta de estado. El valor de elección se muestra sobre un fondo redondeado cuyo color depende del valor:
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "div",
"txtContent": "@currentField",
"style": {
"display": "inline-block",
"padding": "2px 10px",
"border-radius": "12px",
"font-weight": "600",
"color": "#ffffff",
"background-color": "=if(@currentField == 'Approved', '#107c10', if(@currentField == 'Rejected', '#a4262c', '#8a8886'))"
}
}
Un número coloreado según su valor, escrito como árbol de operadores. Los importes superiores a 1000 se muestran en rojo y negrita:
{
"elmType": "span",
"txtContent": "@currentField",
"style": {
"color": {
"operator": "?",
"operands": [
{ "operator": ">", "operands": [ { "operator": "Number()", "operands": [ "@currentField" ] }, 1000 ] },
"#a4262c",
"#107c10"
]
},
"font-weight": "=if(Number(@currentField) > 1000, '700', '400')"
}
}
Un vínculo con icono. La persona de la columna Asignado a se representa como vínculo de correo con un icono de sobre. El formato se establece en la propia columna Asignado a y utiliza las propiedades del valor de persona:
{
"elmType": "a",
"attributes": {
"href": "='mailto:' + @currentField.email",
"title": "=@currentField.title",
"iconName": "Mail",
"target": "_blank"
},
"txtContent": "@currentField.title",
"style": {
"color": "#0078d4",
"text-decoration": "none"
}
}
Rendimiento
El JSON de una columna se analiza una sola vez, cuando se representa su primera celda. El árbol analizado se reutiliza para todas las demás celdas y las siguientes páginas de elementos. Solo los tokens y expresiones se evalúan por celda. Por ello, activar la opción apenas aumenta el tiempo de presentación de la tabla, incluso en páginas largas.
