Listagens Personalizadas: Schema de Itens, Limites e Exemplos

Uma listagem personalizada é uma coleção repetível de itens que compartilham um pequeno schema de campos. Cada item pode ter um título, um resumo conciso, um ou dois valores de metadados e um link de destino. Essa estrutura dá aos leitores mais contexto do que uma lista de marcadores sem fazer cada item se comportar como um cartão de produto independente.

Exemplo — formatos de exportação suportados

• CSV — Linhas tabulares para análise em planilhas. Melhor para registros planos. Disponibilidade: Todos os planos. Ação: Ver configuração de exportação CSV.
• JSON — Registros aninhados para aplicações e pipelines de dados. Melhor para preservar relacionamentos entre campos. Disponibilidade: Pro e Enterprise. Ação: Ler a referência JSON.
• Google Sheets — Uma planilha sincronizada para equipes que revisam dados sem código. Disponibilidade: Pro e Enterprise. Ação: Conectar Google Sheets.

O elemento renderizado não deve ser uma versão decorativa desses marcadores. Ele deve expor uma coleção contendo três itens, e cada item deve preservar os mesmos campos title, summary, bestFor, availability e url. O modelo de campos — não a borda, ícone ou contagem de colunas — é o que torna a listagem personalizada.

Por que este elemento é importante

A prosa comum esconde repetição. Se seis integrações são descritas em seis parágrafos, o leitor precisa descobrir que cada parágrafo contém um nome de sistema, ação suportada, requisito de conta e link de configuração. Uma listagem personalizada nomeia essas partes recorrentes através de um schema de item: um conjunto definido de campos usado por cada item. Os leitores aprendem o padrão após a primeira entrada e podem escanear as entradas seguintes de forma previsível.

Essa consistência também melhora a reutilização. Um sistema de gerenciamento de conteúdo pode validar campos obrigatórios, um template pode renderizar cada item sem marcação específica da página, e uma aplicação downstream pode transformar a mesma fonte em uma lista móvel compacta ou um diretório pesquisável. Mecanismos de busca e sistemas de IA recebem limites discretos de itens, em vez de precisarem inferir onde uma entidade termina e outra começa.

O elemento é importante porque existe uma lacuna comum entre duas estruturas válidas. Marcadores funcionam quando cada item é uma declaração compacta. Cartões funcionam quando cada item precisa de imagens independentes, vários atributos comerciais, uma ação proeminente ou peso visual suficiente para se sustentar sozinho. Muitas coleções não precisam de nenhum extremo. Uma lista de integrações pode exigir um nome, um resumo de capacidade de duas frases, um status e um link. Achatar isso em marcadores perde os campos; inflar em cartões desperdiça espaço e faz uma coleção de referência parecer promocional.

Estrutura não é desculpa para tornar cada coleção sob medida. Um design único produz campos, ordenação, acessibilidade e comportamento responsivo inconsistentes. As regras de escrita de elementos portanto se aplicam primeiro: identifique a necessidade de informação repetida, registre o menor schema que a satisfaz e mantenha o conteúdo portátil entre renderizadores.

Quando usar

Use uma listagem personalizada quando todos os itens responderem à mesma pergunta do leitor, cada um precisar de dois a cinco campos visíveis, e a tarefa principal for inspecionar ou navegar em vez de comparar cada valor lado a lado. Coleções adequadas incluem integrações, áreas de serviço, formatos suportados, downloads de recursos, tipos de parceiros, responsabilidades de equipe, prévias de diretório e recursos agrupados.

Execute quatro testes antes de escolhê-lo:

1. Repetibilidade: Todos os itens podem usar os mesmos campos obrigatórios sem inventar exceções?
2. Independência: Um leitor consegue entender um item sem ler o item anterior?
3. Escaneabilidade: O padrão título-mais-resumo é mais útil que uma grade de valores comparáveis?
4. Ação: Cada item precisa de no máximo um destino principal?

Se as respostas forem sim, uma listagem personalizada é provavelmente adequada. Use outro elemento quando a coleção falhar em um desses testes:

• Use uma lista de marcadores quando os itens precisarem apenas de uma frase paralela e nenhum metadado separado.
• Use uma tabela de comparação quando os leitores precisarem escanear os mesmos critérios vertical ou horizontalmente entre alternativas.
• Use um cartão de produto quando imagem, preço, oferta, avaliação, disponibilidade e ação de compra tornarem cada item uma unidade comercial substancial.
• Use uma lista de etapas quando a posição expressar sequência em vez de ordenação editorial.
• Use um glossário ou padrão de definição quando cada entrada for fundamentalmente um par termo-definição.
• Use títulos e prosa quando os itens exigirem campos diferentes ou mais de cerca de 100 palavras de explicação cada.

Não selecione uma listagem personalizada meramente porque o design pede caixas repetidas. Primeiro prove que existe um modelo de conteúdo estável. Se o item um tem um preço e o item dois tem uma biografia do autor enquanto o item três tem um tamanho de download, eles não são uma coleção, mesmo que CSS possa alinhá-los.

Onde posicionar

Posicione a listagem depois que a página definir a coleção e sua regra de inclusão. “Integrações suportadas” é um rótulo; “Estas integrações podem enviar páginas auditadas para um espaço de trabalho de relatórios próprio” diz aos leitores o que a participação significa. Quando a seleção ou teste criou o conjunto, explique esse método antes do primeiro item para que a listagem não sugira completude ou classificação não suportada.

Coloque a coleção perto da tarefa de decisão ou navegação que ela atende. Uma página de integração deve apresentar a conexão e seu resultado antes de listar fluxos de trabalho suportados. Um diretório deve explicar escopo e filtros antes de mostrar entradas. Um guia de lista deve declarar seu método de avaliação antes de apresentar itens selecionados.

Não interrompa uma listagem com prosa, anúncios, chamadas para ação ou capturas de tela não relacionadas. Os limites dos itens devem permanecer consecutivos. Coloque qualificações dentro dos metadados definidos do item afetado ou explique uma condição de toda a coleção antes ou depois da lista inteira. Se mais de doze itens forem necessários, agrupe-os sob subtítulos significativos, adicione filtragem ou direcione leitores para um Índice de diretório . Não crie uma pilha visual infinita.

Anatomia

Uma listagem personalizada completa tem estas regiões:

1. Título da coleção: nomeia o conjunto na linguagem do leitor, não no nome interno do componente.
2. Declaração de escopo: define o que se qualifica para inclusão e se a coleção é completa, selecionada ou ilustrativa.
3. Contêiner da lista: estabelece uma coleção semântica e é responsável pela contagem de itens.
4. Título do item: identifica exclusivamente a entidade, recurso, capacidade ou opção.
5. Resumo do item: explica a diferença relevante ou uso do item em uma ou duas frases.
6. Grupo de metadados: expõe zero a três fatos rotulados do schema registrado.
7. Ação principal: link para um destino claro usando texto âncora descritivo.
8. Limite do item: usa espaçamento, uma linha ou tratamento de superfície contido sem desconectar o item de sua coleção.

A declaração de escopo previne uma falha comum de precisão. “Integrações disponíveis” implica completude; “Integrações comuns de relatórios” declara uma seleção. O autor deve escolher a redação que a fonte de dados pode suportar.

Exemplos de design

O renderizador pode variar a densidade, mas deve preservar a ordem dos campos, a estrutura semântica de lista e uma sequência de leitura previsível.

Listagem editorial empilhada

Use o design empilhado padrão quando os resumos carregarem a maior parte do valor. Mantenha o título primeiro, resumo em segundo, metadados em terceiro e ação por último. Um divisor sutil é suficiente; cada item não precisa de um cartão elevado.

Prévia compacta de diretório

Use uma variante compacta quando títulos e um valor de metadado permitirem que os leitores escolham um destino. O resumo pode ser mais curto, mas os rótulos devem permanecer visíveis. Nunca substitua um status significativo por um ponto colorido não explicado.

Listagem agrupada

Use grupos quando uma classificação estável reduzir uma coleção de oito a vinte e quatro itens em seções. Os cabeçalhos de grupo devem descrever uma taxonomia genuína, como tipo de exportação ou região de serviço. Não agrupe meramente para obter colunas iguais.

Viewport estreito

Em larguras estreitas, preserve a ordem da fonte e empilhe metadados abaixo do resumo. Não oculte campos que permanecem relevantes, reduza texto para manter colunas ou mova ações para longe de seu item.

Parâmetros

O schema abaixo é intencionalmente restrito. Um campo se torna parte do componente apenas quando é útil em toda a coleção, não porque um item por acaso tem dados para ele.

Três itens são o mínimo porque um par geralmente é mais claro como prosa, uma comparação de duas colunas ou dois cartões substanciais. Doze é o máximo normal porque escanear uma pilha longa sem filtro se torna ineficiente. O teto de vinte e quatro para agrupados é uma proteção, não um alvo; conjuntos maiores ou que mudam com frequência precisam de um diretório, busca, paginação ou uma aplicação orientada a dados.

Escolha ordered=true apenas quando a ordem visível expressar uma classificação declarada. Conveniência editorial, ordenação alfabética ou ordem da fonte de dados não criam uma classificação. Quando a classificação é real, declare a metodologia e mantenha a posição tanto na saída visível quanto em quaisquer dados estruturados.

Sintaxe e exemplos de código

A diretiva portátil define o contrato de autoria. Adaptadores de plataforma podem armazenar os dados de forma diferente, mas devem preservar os mesmos nomes de campo, ordem de itens, opcionalidade e saída visível.

Diretiva Markdown portátil

:::custom-listing{title="Export formats" variant=stacked}
These are the formats available for sending completed audit records to another workspace.

:::item{id=csv title="CSV" url="/docs/exports/csv/"}
Tabular rows for spreadsheet analysis and flat-file ingestion.

- Best for: Spreadsheet analysis
- Availability: All plans
- Action: View CSV export setup
:::

:::item{id=json title="JSON" url="/docs/exports/json/"}
Nested records that preserve relationships for applications and data pipelines.

- Best for: Automated workflows
- Availability: Pro and Enterprise
- Action: Read the JSON reference
:::

:::item{id=sheets title="Google Sheets" url="/docs/exports/google-sheets/"}
A synchronized worksheet for teams that review data without code.

- Best for: Shared review
- Availability: Pro and Enterprise
- Action: Connect Google Sheets
:::
:::

As URLs de exemplo descrevem apenas a sintaxe portátil; uma implementação deve substituí-las por destinos verificados. Não publique um caminho de exemplo como um link ativo meramente porque aparece em um bloco 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" >}}
  Tabular rows for spreadsheet analysis and flat-file ingestion.

  **Best for:** Spreadsheet analysis  
  **Availability:** All plans
  {{< /custom-listing-item >}}
{{< /custom-listing >}}

Esta notação especifica um adaptador futuro ou de nível de projeto; não autoriza a criação de um shortcode local na página. Todos os parâmetros são nomeados. Até que um adaptador exista, renderize a coleção como HTML semântico com <ul> e <li> ou como Markdown nativo, em vez de descartar silenciosamente as relações de campo.

Bloco WordPress

<!-- wp:amicited/custom-listing {"title":"Export formats","variant":"stacked"} -->
<ul class="custom-listing">
  <li data-item-id="csv">
    <h3>CSV</h3>
    <p>Tabular rows for spreadsheet analysis and flat-file ingestion.</p>
    <dl><dt>Best for</dt><dd>Spreadsheet analysis</dd><dt>Availability</dt><dd>All plans</dd></dl>
    <a href="/docs/exports/csv/">View CSV export setup</a>
  </li>
</ul>
<!-- /wp:amicited/custom-listing -->

Blocos nativos são uma alternativa aceitável quando produzem uma lista, um item de lista por entrada, cabeçalhos reais, uma lista de definição para metadados rotulados e links descritivos. Um bloco genérico de Colunas não é um substituto confiável porque a ordem da fonte e o agrupamento de itens frequentemente quebram no mobile.

Exemplos

Bom: uma listagem consistente de recursos

Recursos de migração

Estes recursos apoiam equipes na preparação, execução e validação de uma migração de site.

1. Planilha de mapeamento de redirecionamentos — Registra cada URL antiga, seu destino aprovado, responsável e status de validação. Formato: Planilha. Estágio: Planejamento. Ação: Baixar a planilha de redirecionamentos.
2. Script de validação do dia do lançamento — Verifica códigos de resposta, cadeias de redirecionamento, alvos canônicos e indexabilidade do conjunto de URLs migradas. Formato: Script. Estágio: Lançamento. Ação: Revisar configuração de validação.
3. Visão de monitoramento pós-lançamento — Acompanha falhas de rastreamento e mudanças inesperadas de tráfego após a implantação. Formato: Dashboard. Estágio: Monitoramento. Ação: Configurar a visão de monitoramento.

Isso funciona porque cada item usa os mesmos cinco campos: título, resumo, formato, estágio e ação. O escopo explica por que os recursos pertencem ao mesmo conjunto. A numeração reflete o estágio de migração declarado, não uma afirmação de que o primeiro recurso é o “melhor”. Cada ação identifica seu destino em vez de repetir “Saiba mais”.

Ruim: caixas sem um modelo compartilhado

Coisas úteis

• Checklist de SEO — Nosso guia favorito. Atualizado recentemente. Saiba mais.
• Auditoria Premium — €499, inclui uma chamada e relatório. Cinco estrelas. Compre agora.
• Viktor — Líder técnico baseado em Bratislava, disponível às terças.
• Docs da API — Autenticação, limites, erros, exemplos, SDKs, changelog, status, suporte e mais vinte tópicos.

Isso falha antes mesmo do design visual começar. O conjunto mistura um recurso, serviço, pessoa e área de documentação. Os campos mudam em cada item, “recentemente” não tem data, a avaliação não tem fonte e escala, e a profundidade do item varia de um fragmento a um esboço de seção. Divida o conteúdo por propósito, depois escolha o elemento registrado para cada coleção. Uma borda em volta de dados inconsistentes não cria uma listagem personalizada.

Ruim: uma listagem que deveria ser uma tabela

Suponha que seis planos mostrem cada um preço mensal, preço anual, limite de usuários, armazenamento, tempo de resposta do suporte e disponibilidade de SSO. Os leitores precisam comparar os mesmos seis valores em todos os planos. Uma listagem os forçaria a lembrar do plano um enquanto rolam até o plano seis. Use uma tabela de comparação porque a tarefa é avaliação entre itens. Se cada plano também precisar de uma declaração de posicionamento e ação de compra, coloque-as fora ou ao lado da tabela usando o componente de plano registrado da página; não duplique valores conflitantes em duas fontes.

Marcação Schema e acessibilidade

Renderize a coleção com semântica de lista nativa. Use <ul> quando a ordem dos itens não tiver significado e <ol> quando a página declarar uma sequência ou classificação genuína. Cada entrada pertence a um <li>. Dentro dele, use um cabeçalho real no nível correto do documento, um parágrafo para o resumo e <dl>, <dt> e <dd> para metadados rotulados. Um leitor de tela deve encontrar o título do item antes de sua descrição, fatos e ação.

Não torne o item inteiro um link superdimensionado quando ele contiver outro controle ou várias regiões de texto. Dê ao link principal um rótulo descritivo como “Ver configuração de exportação CSV.” Se um padrão de link esticado for usado, seu indicador de foco deve permanecer visível e seu nome acessível ainda deve descrever o destino. Ícones precisam de texto alternativo apenas quando comunicam informações não presentes no texto. Ícones decorativos devem ser ocultados da tecnologia assistiva.

A ordem visual e a ordem da fonte devem corresponder. Um layout desktop de várias colunas deve colapsar sem ler item um, item três, item cinco e depois item dois. Rótulos de metadados não podem desaparecer só porque valores repetidos aparecem visualmente alinhados; “Enterprise” sozinho não diz a um leitor não visual se descreve disponibilidade, público ou suporte.

Dados estruturados ItemList são opcionais, não um gancho de estilo padrão. Use-os quando a coleção visível for uma lista finita significativa e a página se beneficiar da identificação dessa coleção. Mapeie cada entrada visível para itemListElement. Inclua position apenas para uma lista ordenada real e garanta que nomes, URLs e contagens correspondam ao conteúdo renderizado. Não marque menus de navegação, teasers arbitrários de recursos ou um conjunto parcial como se fossem uma lista classificada completa. Quando as entradas forem entidades identificáveis, como organizações ou aplicações de software, use o tipo elegível mais específico apenas quando a página fornecer e verificar os dados de identidade exigidos.

Regras de escrita

1. Explique a participação antes de apresentar os membros. Os leitores precisam saber se o conjunto é completo, selecionado, patrocinado, classificado ou ilustrativo antes de interpretar omissão ou ordem. Declare a regra de inclusão na frase de escopo.
2. Defina um schema de item antes de redigir os itens. Campos consistentes permitem que os leitores aprendam um padrão de escaneamento e que a validação detecte conteúdo faltante. Registre campos obrigatórios e opcionais antes que os autores preencham a coleção.
3. Mantenha os campos obrigatórios verdadeiramente universais. Um campo nominalmente obrigatório que os autores preenchem com “N/A” em metade das entradas é o campo errado ou evidência de que a coleção contém tipos diferentes de itens.
4. Limite metadados visíveis a três pares. Mais campos deslocam a tarefa para comparação e tornam cada linha difícil de escanear. Mova fatos secundários para a página de destino ou use uma tabela.
5. Escreva resumos para diferença, não repetição. O título já nomeia o item. Use o resumo para explicar sua capacidade, público, limitação ou função relevante.
6. Use rótulos e unidades paralelos. Não alterne “Plano,” “Disponível em” e “Nível” para o mesmo conceito. Normalize datas, moedas, unidades e vocabulário de status antes de renderizar.
7. Dê a cada item uma ação principal. Botões concorrentes transformam uma lista de referência em uma grade de cartões e obscurecem o próximo passo pretendido. Coloque destinos secundários na página de detalhes.
8. Declare ordem significativa. Ordem alfabética, cronológica, classificada, editorial e de sistema fonte criam expectativas diferentes. Nomeie a ordem quando ela puder afetar a interpretação.
9. Defina contagens mínimas e máximas. Use de três a doze itens normalmente, com até vinte e quatro apenas em grupos úteis. Mude de padrão quando a coleção ficar fora desses limites.
10. Mantenha uma única fonte de verdade. Se preço, status, disponibilidade ou outro campo volátil aparecer em outro lugar, preencha cada representação a partir da mesma fonte própria e exponha uma data de verificação onde necessário.

Tipos de post que usam este elemento

• Um Guia de lista usa uma listagem personalizada quando cada entrada selecionada precisa do mesmo resumo, adequação, limitação e link adiante, mas não de uma matriz densa de comparação.
• Uma Página Melhor-X-para-Y pode usá-la para recomendações específicas de público após explicar o método de avaliação. A classificação deve ser explícita, não implícita pela ordem visual.
• Uma Página Alternativas-para-X pode apresentar opções de substituição com campos consistentes de “melhor para”, tradeoff e link de detalhes antes de uma comparação mais restrita.
• Uma Página de categoria usa uma listagem compacta ou agrupada para pré-visualizar um conjunto gerenciável de produtos ou serviços filhos quando a filtragem ainda não é necessária.
• Um índice de diretório usa o elemento apenas para uma prévia ou um diretório pequeno e estável. Conjuntos grandes de entidades precisam de busca, filtros, paginação e uma interface de diretório baseada em dados.
• Um Perfil da empresa pode listar unidades de negócio, certificações ou locais verificados quando cada entrada compartilha os mesmos campos.
• Um Perfil do fornecedor pode listar serviços, regiões ou modelos de engajamento suportados sem transformar o perfil em uma grade de produtos.
• Uma Página de integração pode listar fluxos de trabalho, objetos de dados, gatilhos ou destinos suportados usando um schema previsível de capacidade-e-requisito.

A presença de uma coleção não exige este elemento. Use-o apenas quando o modelo de campo personalizado melhorar a recuperação ou navegação. Um curto conjunto de pré-requisitos ainda pertence a marcadores, e uma matriz de capacidades ainda pertence a uma tabela.

Checklist de QA

• A coleção tem um título e uma frase de escopo que define a inclusão.
• Cada item representa o mesmo tipo de entidade, recurso, capacidade ou opção.
• Os campos obrigatórios e opcionais são documentados antes da entrada de conteúdo.
• Cada item tem um ID estável único, título e resumo de 12 a 60 palavras.
• Nenhum item inventa um campo ausente do schema registrado.
• A coleção contém de 3 a 12 itens, ou grupos justificados com no máximo 24 no total.
• Os itens têm no máximo três pares de metadados visíveis e uma ação principal.
• Rótulos, unidades, status, datas e redação da ação são consistentes.
• A ordem é declarada quando implica classificação, cronologia ou prioridade.
• Uma tabela foi escolhida quando a comparação entre itens é a tarefa principal.
• A saída usa um <ul> ou <ol> semântico com um <li> por item.
• Os cabeçalhos seguem a hierarquia da página e os metadados usam semântica de termo–descrição.
• O foco do teclado é visível e os links descrevem seus destinos.
• A ordem da fonte corresponde à ordem visual em larguras desktop e mobile.
• A marcação ItemList, se presente, corresponde aos itens visíveis, ordem, contagem, nomes e URLs.
• Valores voláteis vêm de uma fonte própria e incluem uma data de verificação apropriada.

FAQ

As perguntas abaixo resolvem os limites que mais frequentemente fazem uma listagem personalizada derivar para marcadores, cartões ou tabelas.

O que é uma listagem personalizada?

Uma listagem personalizada é uma coleção repetível cujos itens compartilham um pequeno schema de campos nomeados, como título, resumo, metadados e link. Ela fica entre uma simples lista de marcadores e uma grade de cartões visualmente independente.

Quantos itens uma listagem personalizada deve conter?

Use de três a doze itens como a faixa editorial normal. Dois itens geralmente precisam de prosa ou um componente lado a lado. Mais de doze precisam de agrupamento útil, filtragem, paginação ou um padrão de diretório; a variante agrupada não deve exceder vinte e quatro itens.

Quando uma listagem personalizada deve se tornar uma tabela?

Use uma tabela quando os leitores precisarem comparar a maioria dos itens entre os mesmos três ou mais campos, especialmente valores numéricos, datas, status ou capacidades sim/não. Mantenha uma listagem quando resumos e links adiante forem mais importantes que a comparação entre itens.

Uma listagem personalizada precisa do schema ItemList?

Não. Adicione ItemList apenas quando a coleção for significativa e finita, cada item marcado estiver visível e qualquer posição refletir uma ordem declarada. Listagens comuns de navegação, teaser e conteúdo relacionado geralmente precisam de HTML semântico em vez de schema especial.

Os itens podem ter campos diferentes?

Apenas campos opcionais definidos pelo schema compartilhado podem estar ausentes. Não permita que autores inventem campos por item. Se vários itens precisarem de um modelo de informação diferente, divida-os em outra listagem ou escolha um elemento mais adequado.