Listados personalizados: esquema de elementos, límites y ejemplos

Un listado personalizado es una colección repetible de elementos que comparten un pequeño esquema de campos. Cada elemento puede tener un título, un resumen conciso, uno o dos valores de metadatos y un enlace de destino. Esta estructura proporciona a los lectores más contexto que una lista con viñetas sin hacer que cada elemento se comporte como una tarjeta de producto independiente.

Ejemplo: formatos de exportación compatibles

• CSV — Filas tabulares para análisis en hojas de cálculo. Ideal para registros planos. Disponibilidad: Todos los planes. Acción: Ver configuración de exportación CSV.
• JSON — Registros anidados para aplicaciones y pipelines de datos. Ideal para preservar relaciones entre campos. Disponibilidad: Pro y Enterprise. Acción: Leer la referencia JSON.
• Google Sheets — Hoja de cálculo sincronizada para equipos que revisan datos sin código. Disponibilidad: Pro y Enterprise. Acción: Conectar Google Sheets.

El elemento renderizado no debe ser una versión decorativa de esas viñetas. Debe exponer una colección que contenga tres elementos, y cada elemento debe preservar los mismos campos title, summary, bestFor, availability y url. El modelo de campos —no el borde, el icono ni el número de columnas— es lo que hace que el listado sea personalizado.

Por qué es importante este elemento

La prosa ordinaria oculta la repetición. Si seis integraciones se describen en seis párrafos, el lector debe descubrir que cada párrafo contiene un nombre de sistema, una acción compatible, un requisito de cuenta y un enlace de configuración. Un listado personalizado nombra esas partes recurrentes mediante un esquema de elementos: un conjunto definido de campos utilizado por cada elemento. Los lectores aprenden el patrón después de la primera entrada y pueden escanear las siguientes de forma predecible.

Esa coherencia también mejora la reutilización. Un sistema de gestión de contenidos puede validar los campos obligatorios, una plantilla puede renderizar cada elemento sin marcado específico de la página, y una aplicación downstream puede transformar la misma fuente en una lista móvil compacta o un directorio con capacidad de búsqueda. Los motores de búsqueda y los sistemas de IA reciben límites discretos entre elementos en lugar de tener que inferir dónde termina una entidad y comienza otra.

El elemento es importante porque existe un vacío común entre dos estructuras válidas. Las viñetas funcionan cuando cada elemento es una declaración compacta. Las tarjetas funcionan cuando cada elemento necesita imágenes independientes, varios atributos comerciales, una acción destacada o suficiente peso visual para sostenerse por sí solo. Muchas colecciones no necesitan ninguno de los extremos. Una lista de integraciones puede requerir un nombre, un resumen de capacidad de dos frases, un estado y un enlace. Aplanar eso en viñetas pierde los campos; inflarlo en tarjetas desperdicia espacio y hace que una colección de referencia parezca promocional.

La estructura no es una excusa para hacer que cada colección sea artesanal. Un diseño único produce campos, ordenación, accesibilidad y comportamiento responsivo inconsistentes. Por lo tanto, las reglas de redacción de elementos se aplican primero: identifica la necesidad de información repetida, registra el esquema más pequeño que la satisfaga y mantén el contenido portátil entre renderizadores.

Cuándo usarlo

Usa un listado personalizado cuando todos los elementos respondan a la misma pregunta del lector, cada uno necesite de dos a cinco campos visibles, y la tarea principal sea inspeccionar o navegar en lugar de comparar cada valor lado a lado. Las colecciones adecuadas incluyen integraciones, áreas de servicio, formatos compatibles, descargas de recursos, tipos de socios, responsabilidades de equipo, vistas previas de directorio y funciones agrupadas.

Realiza cuatro pruebas antes de elegirlo:

1. Repetibilidad: ¿Puede cada elemento usar los mismos campos obligatorios sin inventar excepciones?
2. Independencia: ¿Puede un lector entender un elemento sin leer el anterior?
3. Exploración visual: ¿Es el patrón de título más resumen más útil que una cuadrícula de valores comparables?
4. Acción: ¿Necesita cada elemento no más de un destino principal?

Si las respuestas son afirmativas, es probable que un listado personalizado sea adecuado. Usa otro elemento cuando la colección falle en alguna de esas pruebas:

• Usa una lista con viñetas cuando los elementos necesiten solo una frase paralela y ningún metadato separado.
• Usa una tabla comparativa cuando los lectores deban examinar los mismos criterios vertical u horizontalmente entre alternativas.
• Usa una tarjeta de producto cuando la imagen, el precio, la oferta, la valoración, la disponibilidad y la acción de compra conviertan cada elemento en una unidad comercial sustancial.
• Usa una lista de pasos cuando la posición exprese secuencia en lugar de orden editorial.
• Usa un glosario o patrón de definición cuando cada entrada sea fundamentalmente un par término-definición.
• Usa encabezados y prosa cuando los elementos requieran campos diferentes o más de unas 100 palabras de explicación cada uno.

No selecciones un listado personalizado simplemente porque el diseño requiera recuadros repetidos. Primero demuestra que existe un modelo de contenido estable. Si el elemento uno tiene un precio y el elemento dos tiene una biografía de autor mientras que el elemento tres tiene un tamaño de descarga, no son una sola colección aunque CSS pueda alinearlos.

Dónde colocarlo

Coloca el listado después de que la página defina la colección y su regla de inclusión. «Integraciones compatibles» es una etiqueta; «Estas integraciones pueden enviar páginas auditadas a un espacio de trabajo de informes propio» les dice a los lectores qué significa la pertenencia. Cuando la selección o las pruebas hayan creado el conjunto, explica ese método antes del primer elemento para que el listado no implique integridad o clasificación no respaldada.

Coloca la colección cerca de la tarea de decisión o navegación a la que sirve. Una página de integración debe presentar la conexión y su resultado antes de enumerar los flujos de trabajo compatibles. Un directorio debe explicar el alcance y los filtros antes de mostrar las entradas. Un listicle debe indicar su método de evaluación antes de presentar los elementos seleccionados.

No interrumpas un listado con prosa, anuncios, llamadas a la acción o capturas de pantalla no relacionadas. Los límites de los elementos deben permanecer consecutivos. Coloca las salvedades dentro de los metadatos definidos del elemento afectado o explica una condición de toda la colección antes o después de la lista completa. Si son necesarios más de doce elementos, agrúpalos bajo subtítulos significativos, añade filtrado o dirige a los lectores a un Índice de directorio . No crees una pila visual interminable.

Anatomía

Un listado personalizado completo tiene estas regiones:

1. Título de la colección: nombra el conjunto en el lenguaje del lector, no en el nombre interno del componente.
2. Declaración de alcance: define qué califica para la inclusión y si la colección es completa, seleccionada o ilustrativa.
3. Contenedor de lista: establece una colección semántica y es propietario del recuento de elementos.
4. Título del elemento: identifica de forma única la entidad, recurso, capacidad u opción.
5. Resumen del elemento: explica la diferencia relevante o el uso del elemento en una o dos frases.
6. Grupo de metadatos: expone de cero a tres hechos etiquetados del esquema registrado.
7. Acción principal: enlaza a un destino claro utilizando texto de anclaje descriptivo.
8. Límite del elemento: usa espaciado, una regla o un tratamiento superficial moderado sin desconectar el elemento de su colección.

La declaración de alcance previene un fallo de precisión común. «Integraciones disponibles» implica integridad; «Integraciones de informes comunes» declara una selección. El autor debe elegir la redacción que los datos fuente puedan respaldar.

Ejemplos de diseño

El renderizador puede variar la densidad, pero debe preservar el orden de los campos, la estructura semántica de la lista y una secuencia de lectura predecible.

Listado editorial apilado

Usa el diseño apilado predeterminado cuando los resúmenes aporten la mayor parte del valor. Mantén el título primero, el resumen segundo, los metadatos terceros y la acción al final. Un divisor sutil es suficiente; cada elemento no necesita una tarjeta elevada.

Vista previa compacta de directorio

Usa una variante compacta cuando los títulos y un valor de metadatos permitan a los lectores elegir un destino. El resumen puede ser más corto, pero las etiquetas deben permanecer visibles. Nunca sustituyas un estado significativo por un punto de color sin explicación.

Listado agrupado

Usa grupos cuando una clasificación estable reduzca una colección de ocho a veinticuatro elementos en secciones. Los encabezados de grupo deben describir una taxonomía genuina, como tipo de exportación o región de servicio. No agrupes meramente para lograr columnas iguales.

Vista de ventana estrecha

En anchos reducidos, preserva el orden fuente y apila los metadatos debajo del resumen. No ocultes campos que siguen siendo relevantes, reduzcas el texto para mantener columnas ni muevas las acciones lejos de su elemento.

Parámetros

El esquema siguiente está intencionadamente restringido. Un campo pasa a formar parte del componente solo cuando es útil en toda la colección, no porque un elemento tenga datos para él.

Tres elementos son el mínimo porque un par suele ser más claro como prosa, una comparación de dos columnas o dos tarjetas sustanciales. Doce es el máximo normal porque escanear una pila larga sin filtrar se vuelve ineficiente. El techo agrupado de veinticuatro es una barrera de protección, no un objetivo; los conjuntos más grandes o que cambian con frecuencia necesitan un directorio, búsqueda, paginación o una aplicación basada en datos.

Elige ordered=true solo cuando el orden visible exprese una clasificación declarada. La conveniencia editorial, la ordenación alfabética o el orden de la fuente de datos no crean una clasificación. Cuando la clasificación sea real, indica la metodología y conserva la posición tanto en la salida visible como en cualquier dato estructurado.

Sintaxis y ejemplos de código

La directiva portátil define el contrato de autoría. Los adaptadores de plataforma pueden almacenar los datos de forma diferente, pero deben preservar los mismos nombres de campo, orden de elementos, opcionalidad y salida visible.

Directiva Markdown portátil

:::custom-listing{title="Export formats" variant=stacked}
Estos son los formatos disponibles para enviar registros de auditoría completados a otro espacio de trabajo.

:::item{id=csv title="CSV" url="/docs/exports/csv/"}
Filas tabulares para análisis en hojas de cálculo e ingesta de archivos planos.

- Ideal para: Análisis en hojas de cálculo
- Disponibilidad: Todos los planes
- Acción: Ver configuración de exportación CSV
:::

:::item{id=json title="JSON" url="/docs/exports/json/"}
Registros anidados que preservan relaciones para aplicaciones y pipelines de datos.

- Ideal para: Flujos de trabajo automatizados
- Disponibilidad: Pro y Enterprise
- Acción: Leer la referencia JSON
:::

:::item{id=sheets title="Google Sheets" url="/docs/exports/google-sheets/"}
Una hoja de cálculo sincronizada para equipos que revisan datos sin código.

- Ideal para: Revisión compartida
- Disponibilidad: Pro y Enterprise
- Acción: Conectar Google Sheets
:::
:::

Las URL de ejemplo describen únicamente la sintaxis portátil; una implementación debe reemplazarlas con destinos verificados. No publiques una ruta de ejemplo como un enlace activo solo porque aparece en un bloque de código.

Adaptador Hugo

{{< custom-listing title="Export formats" variant="stacked" >}}
  {{< custom-listing-item id="csv" title="CSV" url="/docs/exports/csv/" action-label="View CSV export setup" >}}
  Filas tabulares para análisis en hojas de cálculo e ingesta de archivos planos.

  **Ideal para:** Análisis en hojas de cálculo  
  **Disponibilidad:** Todos los planes
  {{< /custom-listing-item >}}
{{< /custom-listing >}}

Esta notación especifica un adaptador futuro o a nivel de proyecto; no autoriza la creación de un shortcode local de página. Todos los parámetros tienen nombre. Hasta que exista un adaptador, renderiza la colección como HTML semántico con <ul> y <li> o como Markdown nativo en lugar de descartar silenciosamente las relaciones entre campos.

Bloque de WordPress

<!-- wp:amicited/custom-listing {"title":"Export formats","variant":"stacked"} -->
<ul class="custom-listing">
  <li data-item-id="csv">
    <h3>CSV</h3>
    <p>Filas tabulares para análisis en hojas de cálculo e ingesta de archivos planos.</p>
    <dl><dt>Ideal para</dt><dd>Análisis en hojas de cálculo</dd><dt>Disponibilidad</dt><dd>Todos los planes</dd></dl>
    <a href="/docs/exports/csv/">Ver configuración de exportación CSV</a>
  </li>
</ul>
<!-- /wp:amicited/custom-listing -->

Los bloques nativos son una alternativa aceptable cuando producen una lista, un elemento de lista por entrada, encabezados reales, una lista de definiciones para metadatos etiquetados y enlaces descriptivos. Un bloque genérico de Columnas no es un sustituto fiable porque el orden fuente y la agrupación de elementos a menudo se rompen en móvil.

Ejemplos

Bueno: un listado de recursos coherente

Recursos de migración

Estos recursos ayudan a los equipos a preparar, ejecutar y validar una migración de sitio.

1. Hoja de cálculo de mapeo de redirecciones — Registra cada URL antigua, su destino aprobado, propietario y estado de validación. Formato: Hoja de cálculo. Etapa: Planificación. Acción: Descargar la hoja de redirecciones.
2. Script de validación para el día del lanzamiento — Verifica códigos de respuesta, cadenas de redirección, objetivos canónicos e indexabilidad del conjunto de URL migradas. Formato: Script. Etapa: Lanzamiento. Acción: Revisar configuración de validación.
3. Vista de monitoreo posterior al lanzamiento — Rastrea fallos de rastreo y cambios inesperados de tráfico después del despliegue. Formato: Panel. Etapa: Monitoreo. Acción: Configurar la vista de monitoreo.

Esto funciona porque cada elemento usa los mismos cinco campos: título, resumen, formato, etapa y acción. El alcance explica por qué los recursos pertenecen al mismo conjunto. La numeración refleja la etapa de migración declarada, no una afirmación de que el primer recurso sea «el mejor». Cada acción identifica su destino en lugar de repetir «Más información».

Malo: recuadros sin un modelo compartido

Cosas útiles

• Lista de verificación SEO — Nuestra guía favorita. Actualizada recientemente. Más información.
• Auditoría premium — 499 €, incluye llamada e informe. Cinco estrellas. Comprar ahora.
• Viktor — Líder técnico con sede en Bratislava, disponible los martes.
• Documentación de API — Autenticación, límites, errores, ejemplos, SDK, registro de cambios, estado, soporte y veinte temas más.

Esto falla antes de que comience el diseño visual. El conjunto mezcla un recurso, un servicio, una persona y un área de documentación. Los campos cambian en cada elemento, «recientemente» no tiene fecha, la valoración carece de fuente y escala, y la profundidad del elemento varía desde un fragmento hasta un esquema de sección. Divide el contenido por propósito, luego elige el elemento registrado para cada colección. Un borde alrededor de datos inconsistentes no crea un listado personalizado.

Malo: un listado que debería ser una tabla

Supongamos que seis planes muestran cada uno el precio mensual, el precio anual, el límite de usuarios, el almacenamiento, el tiempo de respuesta del soporte y la disponibilidad de SSO. Los lectores necesitan comparar los mismos seis valores en todos los planes. Un listado les obligaría a recordar el plan uno mientras se desplazan hasta el plan seis. Usa una tabla comparativa porque la tarea es la evaluación cruzada de elementos. Si cada plan también necesita una declaración de posicionamiento y una acción de compra, colócalas fuera o junto a la tabla usando el componente de plan registrado de la página; no dupliques valores contradictorios en dos fuentes.

Marcado de esquema y accesibilidad

Renderiza la colección con semántica de lista nativa. Usa <ul> cuando el orden de los elementos no tenga significado y <ol> cuando la página declare una secuencia o clasificación genuina. Cada entrada pertenece a un <li>. Dentro de él, usa un encabezado real al nivel de documento correcto, un párrafo para el resumen y <dl>, <dt> y <dd> para los metadatos etiquetados. Un lector de pantalla debe encontrar el título del elemento antes que su descripción, datos y acción.

No conviertas todo el elemento en un enlace de gran tamaño cuando contenga otro control o varias regiones de texto. Dale al enlace principal una etiqueta descriptiva como «Ver configuración de exportación CSV». Si se usa un patrón de enlace expandido, su indicador de enfoque debe permanecer visible y su nombre accesible debe seguir describiendo el destino. Los iconos necesitan texto alternativo solo cuando comunican información que no está ya presente en el texto. Los iconos decorativos deben ocultarse de la tecnología de asistencia.

El orden visual y el orden fuente deben coincidir. Un diseño de escritorio de varias columnas debe colapsarse sin leer el elemento uno, el elemento tres, el elemento cinco y luego el elemento dos. Las etiquetas de metadatos no pueden desaparecer solo porque los valores repetidos aparezcan visualmente alineados; «Enterprise» solo no le dice a un lector no visual si describe disponibilidad, audiencia o soporte.

Los datos estructurados ItemList son opcionales, no un gancho de estilo predeterminado. Úsalos cuando la colección visible sea una lista finita significativa y la página se beneficie de identificar esa colección. Asigna cada entrada visible a itemListElement. Incluye position solo para una lista ordenada real, y asegúrate de que los nombres, URL y recuentos coincidan con el contenido renderizado. No marques menús de navegación, avances de funciones arbitrarios o un conjunto parcial como si fueran una lista completa clasificada. Cuando las entradas sean entidades identificables como organizaciones o aplicaciones de software, usa el tipo elegible más específico solo cuando la página proporcione y verifique los datos de identidad requeridos.

Reglas de redacción

1. Explica la pertenencia antes de presentar a los miembros. Los lectores necesitan saber si el conjunto es completo, seleccionado, patrocinado, clasificado o ilustrativo antes de interpretar omisiones u orden. Indica la regla de inclusión en la frase de alcance.
2. Define un esquema de elementos antes de redactar los elementos. Los campos coherentes permiten a los lectores aprender un patrón de exploración y a la validación detectar contenido faltante. Registra los campos obligatorios y opcionales antes de que los autores llenen la colección.
3. Mantén los campos obligatorios realmente universales. Un campo nominalmente obligatorio que los autores llenan con «N/A» en la mitad de las entradas es el campo equivocado o evidencia de que la colección contiene diferentes tipos de elementos.
4. Limita los metadatos visibles a tres pares. Más campos desplazan la tarea hacia la comparación y dificultan la exploración de cada fila. Traslada los datos secundarios a la página de destino o usa una tabla.
5. Redacta resúmenes para la diferencia, no para la repetición. El título ya nombra el elemento. Usa el resumen para explicar su capacidad, audiencia, limitación o función relevante.
6. Usa etiquetas y unidades paralelas. No alternes «Plan», «Disponible en» y «Nivel» para el mismo concepto. Normaliza fechas, monedas, unidades y vocabulario de estado antes de renderizar.
7. Asigna a cada elemento una acción principal. Los botones en competencia convierten una lista de referencia en una cuadrícula de tarjetas y oscurecen el siguiente paso previsto. Coloca los destinos secundarios en la página de detalle.
8. Declara un orden significativo. Los órdenes alfabético, cronológico, clasificado, editorial y de sistema fuente crean expectativas diferentes. Nombra el orden cuando pueda afectar la interpretación.
9. Establece recuentos mínimo y máximo. Usa de tres a doce elementos normalmente, hasta veinticuatro solo en grupos útiles. Cambia de patrón cuando la colección salga de esos límites.
10. Mantén una única fuente de verdad. Si el precio, el estado, la disponibilidad u otro campo volátil aparece en otro lugar, llena cada representación desde la misma fuente propia y expón una fecha de verificación cuando sea necesario.

Tipos de publicación que lo usan

• Una Guía tipo listicle usa un listado personalizado cuando cada entrada seleccionada necesita el mismo resumen, ajuste, limitación y enlace de continuación, pero no una matriz de comparación densa.
• Una Página Mejor-X-para-Y puede usarlo para recomendaciones específicas por audiencia después de explicar el método de evaluación. La clasificación debe ser explícita, no implícita por el orden visual.
• Una Página Alternativas-a-X puede presentar opciones de reemplazo con campos coherentes de «mejor para», concesiones y enlace de detalle antes de una comparación más específica.
• Una Página de categoría usa un listado compacto o agrupado para previsualizar un conjunto manejable de productos o servicios hijos cuando el filtrado aún no es necesario.
• Un índice de directorio usa el elemento solo para una vista previa o un directorio pequeño y estable. Los conjuntos grandes de entidades necesitan búsqueda, filtros, paginación y una interfaz de directorio respaldada por datos.
• Un Perfil de empresa puede listar unidades de negocio, certificaciones o ubicaciones verificadas cuando cada entrada comparte los mismos campos.
• Un Perfil de proveedor puede listar servicios, regiones o modelos de contratación compatibles sin convertir el perfil en una cuadrícula de productos.
• Una Página de integración puede listar flujos de trabajo, objetos de datos, disparadores o destinos compatibles utilizando un esquema predecible de capacidad y requisito.

La presencia de una colección no requiere este elemento. Úsalo solo cuando el modelo de campos personalizado mejore la recuperación o la navegación. Un conjunto corto de requisitos previos sigue perteneciendo a viñetas, y una matriz de capacidades sigue perteneciendo a una tabla.

Lista de verificación de QA

• La colección tiene un título y una frase de alcance que define la inclusión.
• Cada elemento representa el mismo tipo de entidad, recurso, capacidad u opción.
• Los campos obligatorios y opcionales están documentados antes de la entrada de contenido.
• Cada elemento tiene un ID estable único, título y resumen de 12 a 60 palabras.
• Ningún elemento inventa un campo que esté ausente del esquema registrado.
• La colección contiene de 3 a 12 elementos, o grupos justificados con no más de 24 en total.
• Los elementos tienen no más de tres pares de metadatos visibles y una acción principal.
• Las etiquetas, unidades, estados, fechas y redacción de las acciones son coherentes.
• El orden se declara cuando implica clasificación, cronología o prioridad.
• Se eligió una tabla cuando la comparación entre elementos es la tarea principal.
• La salida usa un <ul> o <ol> semántico con un <li> por elemento.
• Los encabezados siguen la jerarquía de la página y los metadatos usan semántica de término–descripción.
• El foco del teclado es visible y los enlaces describen sus destinos.
• El orden fuente coincide con el orden visual en anchos de escritorio y móvil.
• El marcado ItemList, si está presente, coincide con los elementos visibles, orden, recuento, nombres y URL.
• Los valores volátiles provienen de una fuente propia e incluyen una fecha de verificación adecuada.

Preguntas frecuentes

Las preguntas siguientes resuelven los límites que con mayor frecuencia hacen que un listado personalizado se desvíe hacia viñetas, tarjetas o tablas.

¿Qué es un listado personalizado?

Un listado personalizado es una colección repetible cuyos elementos comparten un pequeño esquema de campos con nombre, como título, resumen, metadatos y enlace. Se sitúa entre una lista simple con viñetas y una cuadrícula de tarjetas visualmente independientes.

¿Cuántos elementos debe contener un listado personalizado?

Usa de tres a doce elementos como rango editorial normal. Dos elementos normalmente necesitan prosa o un componente lado a lado. Más de doce necesitan agrupación útil, filtrado, paginación o un patrón de directorio; la variante agrupada no debe exceder los veinticuatro elementos.

¿Cuándo debe convertirse un listado personalizado en una tabla?

Usa una tabla cuando los lectores deban comparar la mayoría de los elementos en los mismos tres o más campos, especialmente valores numéricos, fechas, estados o capacidades de sí o no. Mantén un listado cuando los resúmenes y los enlaces de continuación importen más que la comparación entre elementos.

¿Necesita un listado personalizado el esquema ItemList?

No. Añade ItemList solo cuando la colección sea significativa y finita, cada elemento marcado sea visible y cualquier posición refleje un orden declarado. Los listados de navegación ordinaria, avances y contenido relacionado normalmente necesitan HTML semántico en lugar de un esquema especial.

¿Pueden los elementos tener campos diferentes?

Solo los campos opcionales definidos por el esquema compartido pueden estar ausentes. No permitas que los autores inventen campos por elemento. Si varios elementos necesitan un modelo de información diferente, divídelos en otro listado o elige un elemento más adecuado.