自定义列表：项目模式、限制与示例

自定义列表是一种可重复的集合，其项目共享一个小型字段模式。每个项目可以包含标题、简洁摘要、一两个元数据值以及目标链接。这种结构为读者提供了比项目符号列表 更多的上下文，同时又不会让每个项目表现得像独立的产品卡片 。

示例——支持的导出格式

• CSV — 适用于电子表格分析的表格行。最适合平面记录。可用性： 所有套餐。操作： 查看CSV导出设置。
• JSON — 适用于应用程序和数据管道的嵌套记录。最适合保留字段关系。可用性： Pro和企业版。操作： 阅读JSON参考文档。
• Google Sheets — 适合无代码审阅数据的团队的同步工作表。可用性： Pro和企业版。操作： 连接Google Sheets。

渲染后的元素不应该是这些项目符号的装饰版本。它应展示一个包含三个项目的集合，每个项目应保留相同的title、summary、bestFor、availability和url字段。使列表成为"自定义"的是字段模型——而不是边框、图标或列数。

为什么这个元素很重要

普通的段落文字隐藏了重复性。如果用六个段落描述六个集成功能，读者必须自己去发现每个段落都包含系统名称、支持的操作、账户要求和设置链接。自定义列表通过一个项目模式来命名这些重复部分：每个项目使用的是一组已定义的字段。读者在阅读第一个条目后就能掌握这个模式，并可以预测性地扫描后续条目。

这种一致性也提高了复用性。内容管理系统可以验证必填字段，模板可以在没有页面特定标记的情况下渲染每个项目，下游应用程序可以将同一源数据转换为紧凑的移动列表或可搜索的目录。搜索引擎和AI系统获得的是离散的项目边界，而无需推断一个实体在哪里结束、另一个在哪里开始。

这个元素之所以重要，是因为两种有效结构之间存在一个常见的空白地带。当每个项目是一个紧凑的陈述时，项目符号列表适用。当每个项目需要独立的图片、多个商业属性、突出的操作按钮或足够的视觉重量来独立展示时，卡片适用。许多集合并不需要这两种极端。一个集成列表可能只需要名称、两句话的功能摘要、状态和链接。将其扁平化为项目符号列表会丢失字段；将其膨胀为卡片会浪费空间，并使参考集合显得具有推广性质。

结构化不是让每个集合都变成特制的借口。一次性设计会产生不一致的字段、排序、无障碍和响应式行为。因此，元素编写规则 优先适用：识别重复的信息需求，注册满足该需求的最小模式，并保持内容在不同渲染器之间可移植。

何时使用

当所有项目回答的是同一个读者问题、每个项目需要两到五个可见字段、且主要任务是浏览或导航而不是逐值并排对比时，使用自定义列表。适合的集合包括：集成功能、服务领域、支持格式、资源下载、合作伙伴类型、团队职责、目录预览和分组功能。

在选择之前，进行四项测试：

1. 可重复性： 每个项目是否都能使用相同的必填字段，而不会出现例外？
2. 独立性： 读者是否能在不阅读前一个项目的情况下理解后一个项目？
3. 可扫描性： 标题加摘要的模式是否比可对比值的网格更有用？
4. 操作： 每个项目是否最多只需要一个主要目标链接？

如果答案都是肯定的，那么自定义列表很可能是合适的选择。当集合未能通过其中某项测试时，使用其他元素：

• 当项目只需要一个并行的句子且没有独立的元数据时，使用项目符号列表。
• 当读者需要在备选方案之间纵向或横向扫描相同标准时，使用对比表格 。
• 当图片、价格、优惠、评分、可用性和购买操作使每个项目成为一个重要的商业单元时，使用产品卡片。
• 当位置表示顺序而非编辑排序时，使用步骤列表。
• 当每个条目本质上是一个术语-定义对时，使用词汇表或定义模式。
• 当项目需要不同的字段或每个项目需要超过约100个词的说明时，使用标题和段落文字。

不要仅仅因为设计上要求重复的方框就选择自定义列表。首先要证明存在一个稳定的内容模型。如果项目一有价格、项目二有作者简介、项目三有下载大小，那么即使CSS能让它们对齐，它们也不是同一个集合。

放置位置

将列表放置在页面定义了集合及其包含规则之后。“支持的集成功能"是一个标签；“这些集成可以将经过审核的页面发送到专属的报告工作空间"告诉读者成员资格的含义。当筛选或测试产生了这个集合时，在第一个项目之前解释该方法，这样列表就不会暗示未经验证的完整性或排名。

将集合放在靠近它所要服务的决策或导航任务的位置。集成页面应在列出支持的工作流程之前介绍连接及其结果。目录页面应在显示条目之前说明范围和筛选条件。列表式指南应在展示选中的项目之前说明评估方法。

不要用段落文字、广告、行动号召或不相关的截图打断列表。项目边界必须保持连续。将限定条件放在受影响项目的定义元数据中，或者在列表之前或之后说明集合范围的条件。如果需要超过十二个项目，将它们放在有意义的子标题下分组、添加筛选功能，或引导读者前往目录索引 。不要创建一个无休止的视觉堆叠。

结构组成

一个完整的自定义列表包含以下区域：

1. 集合标题： 以读者的语言命名该集合，而非组件的内部名称。
2. 范围说明： 定义符合纳入条件的标准，以及该集合是完整的、经筛选的还是示例性的。
3. 列表容器： 建立一个语义上的集合，并负责项目计数。
4. 项目标题： 唯一标识该实体、资源、功能或选项。
5. 项目摘要： 用一两句话解释项目的相关差异或用途。
6. 元数据组： 展示来自已注册模式的零到三个带标签的事实。
7. 主要操作： 使用描述性链接文字链接到一个明确的目标。
8. 项目边界： 使用间距、分隔线或克制的表面处理，但不使项目与所属集合分离。

范围说明可以防止一种常见的准确性错误。“可用集成"暗示完整性；“常用报表集成"则声明了一个筛选结果。作者必须选择源数据能够支持的文字表述。

设计示例

渲染器可以变化密度，但必须保留字段顺序、语义列表结构和可预测的阅读顺序。

堆叠式编辑列表

当摘要承载了大部分价值时，使用默认的堆叠式设计。保持标题在前、摘要其次、元数据第三、操作在最后。一个微妙的分隔线就足够了；每个项目不需要凸起的卡片。

紧凑目录预览

当标题和一个元数据值足以让读者选择目标时，使用紧凑变体。摘要可以更短，但标签必须保持可见。绝不要用一个未加说明的彩色圆点来替代有意义的状态。

分组列表

当一个稳定的分类可以将八到二十四个项目的集合划分为若干部分时，使用分组。分组标题必须描述真正的分类体系，如导出类型或服务区域。不要仅仅为了实现等列布局而进行分组。

窄视口

在窄宽度下，保留源顺序并将元数据堆叠在摘要下方。不要隐藏仍然相关的字段、缩小文字以维持列数，或将操作按钮移离其所属项目。

参数

以下模式是经过有意约束的。只有当某个字段在整个集合中都有用时，它才成为组件的一部分，而不是因为某个项目恰好有该字段的数据。

三个项目是最低要求，因为一对项目通常更适合作为段落文字、两栏对比或两个内容充实的卡片。十二个是常规最大值，因为扫描长而无筛选的堆叠会变得低效。分组的二十四个上限是一个护栏而非目标；更大或频繁变化的集合需要目录、搜索、分页或数据驱动的应用程序。

仅当可见顺序表达声明的排名时才选择ordered=true。编辑上的便利、字母排序或数据源顺序并不构成排名。当排名真实存在时，说明方法论并在可见输出和任何结构化数据中保留该位置。

语法与代码示例

可移植指令定义了作者契约。平台适配器可以以不同方式存储数据，但必须保留相同的字段名称、项目顺序、可选性和可见输出。

可移植Markdown指令

:::custom-listing{title="导出格式" variant=stacked}
以下是将完成的审核记录发送到其他工作空间时可用的格式。

:::item{id=csv title="CSV" url="/docs/exports/csv/"}
适用于电子表格分析和平面文件导入的表格行。

- 最适合：电子表格分析
- 可用性：所有套餐
- 操作：查看CSV导出设置
:::

:::item{id=json title="JSON" url="/docs/exports/json/"}
保留关系和适用于应用程序及数据管道的嵌套记录。

- 最适合：自动化工作流程
- 可用性：Pro和企业版
- 操作：阅读JSON参考文档
:::

:::item{id=sheets title="Google Sheets" url="/docs/exports/google-sheets/"}
适合无代码审阅数据的团队的同步工作表。

- 最适合：共享审阅
- 可用性：Pro和企业版
- 操作：连接Google Sheets
:::
:::

示例URL仅描述可移植语法；实现时必须将其替换为经过验证的目标地址。不要仅仅因为示例路径出现在代码块中就将其作为实际链接发布。

Hugo适配器

{{< custom-listing title="导出格式" variant="stacked" >}}
  {{< custom-listing-item id="csv" title="CSV" url="/docs/exports/csv/" action-label="查看CSV导出设置" >}}
  适用于电子表格分析和平面文件导入的表格行。

  **最适合：** 电子表格分析  
  **可用性：** 所有套餐
  {{< /custom-listing-item >}}
{{< /custom-listing >}}

此标记指定了一个未来或项目级别的适配器；它不授权创建页面级别的短代码。所有参数均为命名参数。在适配器存在之前，将集合渲染为语义HTML（使用<ul>和<li>）或原生Markdown，而不是静默丢弃字段关系。

WordPress区块

<!-- wp:amicited/custom-listing {"title":"导出格式","variant":"stacked"} -->
<ul class="custom-listing">
  <li data-item-id="csv">
    <h3>CSV</h3>
    <p>适用于电子表格分析和平面文件导入的表格行。</p>
    <dl><dt>最适合</dt><dd>电子表格分析</dd><dt>可用性</dt><dd>所有套餐</dd></dl>
    <a href="/docs/exports/csv/">查看CSV导出设置</a>
  </li>
</ul>
<!-- /wp:amicited/custom-listing -->

当原生区块能生成一个列表、每个条目一个列表项、真实标题、用于带标签元数据的定义列表以及描述性链接时，它们是可接受的降级方案。通用的列区块不是可靠的替代方案，因为源顺序和项目分组在移动设备上常常出现问题。

示例

好示例：一致的资源列表

迁移资源

以下资源为准备、执行和验证网站迁移的团队提供支持。

1. 重定向映射表 — 记录每个旧URL、其批准的目标地址、所有者和验证状态。格式： 电子表格。阶段： 规划。操作： 下载重定向映射表。
2. 上线日验证脚本 — 检查已迁移URL集的响应代码、重定向链、规范目标和可索引性。格式： 脚本。阶段： 上线。操作： 查看验证设置。
3. 上线后监控视图 — 跟踪部署后的爬取失败和意外流量变化。格式： 仪表盘。阶段： 监控。操作： 配置监控视图。

这个示例之所以有效，是因为每个项目使用相同的五个字段：标题、摘要、格式、阶段和操作。范围说明解释了这些资源为何属于同一集合。编号反映了声明的迁移阶段，而不是声称第一个资源"最好”。每个操作都标识了其目标，而不是重复"了解更多”。

差示例：无共享模型的方框

有用的东西

• SEO清单 — 我们最喜欢的指南。最近更新过。了解更多。
• 高级审核 — €499，包含通话和报告。五星好评。立即购买。
• Viktor — 技术负责人，位于布拉迪斯拉发，周二有空。
• API文档 — 认证、限制、错误、示例、SDK、变更日志、状态、支持以及另外二十多个主题。

这个例子在视觉设计开始之前就失败了。该集合混合了资源、服务、人员和文档区域。每个项目的字段都在变化，“最近"没有日期，评分缺乏来源和量级，项目深度从片段到章节大纲不等。应该按照目的拆分内容，然后为每个集合选择已注册的元素。给不一致的数据加上边框并不能创建自定义列表。

差示例：本应使用表格的列表

假设六个套餐各自显示月费、年费、用户限制、存储空间、支持响应时间和SSO可用性。读者需要对比每个套餐的这六个相同值。列表形式会迫使他们记住套餐一的内容，同时滚动到套餐六。因为任务是跨项目对比，所以应使用对比表格。如果每个套餐还需要定位说明和购买操作，应将这些内容放在表格外部或旁边，使用页面已注册的套餐组件；不要在两个来源中重复相互矛盾的值。

模式标记与无障碍

使用原生列表语义渲染集合。当项目顺序无意义时使用<ul>，当页面声明了真实的顺序或排名时使用<ol>。每个条目属于一个<li>。在其中，使用文档层级正确的真实标题、用于摘要的段落以及用于带标签元数据的<dl>、<dt>和<dd>。屏幕阅读器应在描述、事实和操作之前遇到项目标题。

当整个项目包含另一个控件或多个文本区域时，不要将其变为一个过大的链接。为主链接提供描述性标签，如"查看CSV导出设置”。如果使用了拉伸链接模式，其焦点指示器必须保持可见，其无障碍名称仍必须描述目标。图标仅在传达文本中未包含的信息时才需要替代文本。装饰性图标应对辅助技术隐藏。

视觉顺序和源顺序必须一致。多列桌面布局在折叠时不能变成项目一、项目三、项目五然后项目二的顺序。元数据标签不能因为重复值在视觉上对齐而消失；单独的"企业版"并不能让非视觉读者知道它描述的是可用性、受众还是支持。

ItemList结构化数据是可选的，不是默认的样式挂钩。当可见集合是一个有意义的有限列表且页面受益于标识该集合时使用它。将每个可见条目映射到itemListElement。仅对真正的有序列表包含position，并确保名称、URL和计数与渲染内容匹配。不要将导航菜单、随意的功能预告或部分集合标记为完整的排名列表。当条目是可识别的实体（如组织或软件应用）时，只有当页面提供并验证了所需的身份数据时，才使用最具体的符合条件的类型。

编写规则

1. 在展示成员之前说明成员资格。 读者需要在解读遗漏或排序之前知道该集合是完整的、经过筛选的、赞助的、排名的还是示例性的。在范围说明句中说明包含规则。
2. 在起草项目之前定义一个项目模式。 一致的字段让读者可以学习一种扫描模式，也让验证工具能够发现缺失内容。在作者填充集合之前注册必填和可选字段。
3. 确保必填字段真正通用。 一个名义上必填但作者在半数字段中填写"不适用"的字段，要么是错误的字段，要么证明该集合包含不同类型的项目。
4. 将可见元数据限制在三对以内。 更多字段会使任务偏向对比，并使每一行难以扫描。将次要事实移动到目标页面或使用表格。
5. 撰写用于区分而非重复的摘要。 标题已经命名了项目。使用摘要来解释其相关能力、受众、限制或角色。
6. 使用并行的标签和单位。 不要为同一概念交替使用"套餐”、“可用版本"和"层级”。在渲染之前统一日期、货币、单位和状态词汇。
7. 为每个项目提供一个主要操作。 冲突的按钮会将参考列表变成卡片网格，并模糊预期的下一步操作。将次要目标放在详情页面。
8. 声明有意义的排序。 字母顺序、时间顺序、排名顺序、编辑顺序和源系统顺序会产生不同的预期。当排序可能影响解读时，说明排序方式。
9. 设置最小和最大计数。 常规使用三到十二个项目，仅在有用的分组中最多使用二十四个。当集合超出这些范围时，切换模式。
10. 维护单一事实来源。 如果价格、状态、可用性或其他易变字段出现在其他地方，则从同一自有源填充每个表现形式，并在需要时提供验证日期。

使用此元素的文章类型

• 列表式指南 在以下情况下使用自定义列表：每个选中的条目需要相同的摘要、适用性、限制和跳转链接，但不需要密集的对比矩阵。
• 最佳X推荐页 可以在解释评估方法后，使用自定义列表来针对特定受众进行推荐。排名必须明确，而非通过视觉顺序暗示。
• X替代方案页 可以用一致的"最适合”、权衡因素和详情链接字段来展示替代选项，然后再进行更窄范围的对比。
• 分类页面 在筛选功能尚不需要时，使用紧凑或分组列表来预览可控数量的子产品或服务。
• 目录索引仅在预览或小型稳定目录时使用此元素。大型实体集合需要搜索、筛选、分页和数据驱动的目录界面。
• 公司简介 可以在每个条目共享相同字段时，列出经过验证的业务部门、认证或地点。
• 供应商简介 可以列出支持的服务、区域或合作模式，而无需将简介变成产品网格。
• 集成页面 可以使用可预测的能力和要求模式来列出支持的工作流程、数据对象、触发器或目标。

集合的存在并不要求使用此元素。仅当自定义字段模型能改善检索或导航时才使用它。简短的前提条件列表仍应使用项目符号列表，功能矩阵仍应使用表格。

QA检查清单

• 集合有标题和定义纳入标准的范围说明句。
• 每个项目代表相同类型的实体、资源、功能或选项。
• 在内容录入之前已记录必填和可选字段。
• 每个项目有唯一的稳定ID、标题和12–60个词的摘要。
• 没有项目自创已注册模式中不存在的字段。
• 集合包含3–12个项目，或在有合理分组的情况下不超过24个。
• 项目不超过三个可见元数据对和一个主要操作。
• 标签、单位、状态、日期和操作措辞一致。
• 当排序暗示排名、时间顺序或优先级时已声明。
• 当跨项目对比是主要任务时，已选择表格而非列表。
• 输出使用一个语义化的<ul>或<ol>，每个项目一个<li>。
• 标题遵循页面层级，元数据使用术语-描述语义。
• 键盘焦点可见，链接描述其目标。
• 桌面和移动宽度下源顺序与视觉顺序一致。
• ItemList标记（如有）与可见项目、顺序、数量、名称和URL匹配。
• 易变值来自自有源，并包含适当的验证日期。

常见问题

以下问题解决了最常导致自定义列表 滑向项目符号列表、卡片或表格的边界问题。

什么是自定义列表？

自定义列表是一种可重复的集合，其项目共享一个小的、命名字段模式，例如标题、摘要、元数据和链接。它介于简单的项目符号列表和视觉上独立的卡片网格之间。

自定义列表应包含多少项目？

常规编辑范围使用三到十二个项目。两个项目通常需要段落文字或并排组件。超过十二个需要有用的分组、筛选、分页或目录模式；分组变体不得超过二十四个项目。

何时自定义列表应变为表格？

当读者需要对比大多数项目在相同三个或更多字段上的信息时，特别是数值、日期、状态或是否具备某项功能时，应使用表格。当摘要和跳转链接比跨项目对比更重要时，应保留列表形式。

自定义列表是否需要ItemList模式标记？

不需要。仅当集合有意义且有限、每个标记的项目都可见、且任何位置都反映声明的顺序时，才添加ItemList。普通的导航、摘要和相关内容列表通常需要语义化HTML而不是特殊模式标记。

项目可以有不同的字段吗？

只有共享模式定义的可选字段才可以缺失。不允许作者为每个项目自创字段。如果几个项目需要不同的信息模型，应将其拆分为另一个列表或选择更合适的元素。