为 Adobe 边缘交付服务构建动态参考列表块

在这篇文章中，我们将深入探讨如何利用Edge Delivery Services 和 Document Authoring的强大功能，从 DA 中的电子表格建立一个动态的项目列表。

将链接列表倒入页面与策划真正可用的内容之间存在很大差异。这个项目一开始是"，我们只需要一个 URL 和描述的列表，" ，但很快就变成了解决一些实际问题：保持内容的可维护性、避免 DOM 的臃肿，以及在不过度工程化的情况下让过滤感觉更快。

这就是 "参考列表"块；它是 Adobe Edge Delivery Services (EDS) 的一个数据驱动、可过滤的卡片网格，可从电子表格支持的 JSON 源中提取内容，支持类别和标签过滤，并以精美的动画逐步加载结果。我们制作它的目的是为了推动 边缘配送服务参考页面 的发展，各位朋友应该已经将该 页面 添加到了书签中！

让电子表格驱动一切

该区块完全由数据驱动。它获取由 EDS 表生成的 JSON 文件，网址是/en/reference-links.json 。我们决定采用多张表格的格式；一张表格用于参考项目，一张表格用于分类：

{
  "data": {
    "data": [
      {
        "url": "https://developer.adobe.com/",
        "image-url": "https://example.com/thumb.png",
        "title": "Adobe Developer Documentation",
        "description": "Official docs for building on Adobe platforms.",
        "tag": "Documentation|Official",
        "category": "Development"
      }
    ]
  },
  "categories": {
    "data": [{ "Category": "Development", "Description": "Dev tools and references" }]
  }
}

标记在单元格内使用管道（Tag1 | Tag2），这样可以保持编写的简单性和可预测性。

在创建这个区块时，毫无疑问，你会希望在将其上线之前进行一些测试。如果您只有 DA 内部的填充列表，那么在本地测试时很可能会遇到一些跨源资源共享 (CORS) 问题。要解决这个问题，只需创建自己的 JSON 文件，其中包含一些满足与 DA 表相同要求的测试条目，并启用本地 JSON 使用。

const USE_LOCAL_JSON = false;
const LOCAL_JSON_PATH = '/tools/json/reference-list.json';
const LIVE_JSON_URL = '/en/reference-links.json';

制作不会损坏的卡片

每个参考项目都会变成一张具有这种 DOM 结构的卡片：

.reference-card
  └── a.reference-link
        ├── div.reference-image-wrapper   (optional)
        │     └── img.reference-image
        └── div.reference-content
              ├── h3.reference-title
              ├── p.reference-description  (optional)
              └── div.reference-tags
                    └── span.reference-tag (one per tag)

在构建区块时，最重要的考虑因素之一是作者使用它的方便程度。为此，我们必须确保列表可以处理不同数量的信息，并且功能不变。有的有描述，有的有标签，有的两者都没有。规则是只渲染存在的东西，但不要让布局依赖于任何一个部件的存在。几个具体的决定：

• 图像是可选项，图像-url 字段（回退到图像）只有在非空的情况下才会渲染

• 图片使用 loading="lazy" ，因此屏幕外的缩略图不会阻塞初始呈现

• 所有链接均使用 rel="noopener noreferrer" ，以防止外部 URL 上的标签抢占。

  • 这通常由现代浏览器自动完成，但安全第一！

筛选名单而不重建世界

在考虑如何过滤时，事情有时会变得一团糟，尤其是在每次交互时都要重新渲染时。为了避免这种情况，我们确保从一开始就设置好每张卡片的属性，这样它就更像是一个可见性切换器了。

card.setAttribute('data-category', ref.category);
card.setAttribute('data-tags', JSON.stringify(cardTags));

我们还添加了一个函数 updateReferenceDisplay，用于在每次交互时重新评估可见性：

const categoryMatch = selectedCategory === 'all' || cardCategory === selectedCategory;
const tagMatch = cardTags.length === 0 || cardTags.some((tag) => activeTags.has(tag));

标签匹配使用OR 逻辑，任何被选中的标签都会使卡片合格。活动标签位于一个集合中，因此添加/删除和成员检查都是 O(1)。一个微妙的边缘情况：无标记项目。让它们始终通过标签过滤器意味着它们不会意外消失。

CSS 工作超出预期

虽然这不一定是一篇关于造型的博客，但如果我不提及我们在造型方面做出的一些决定，那就太失职了。特别是关于"spotlight" 牌悬浮时的效果。

.reference-grid:has(.reference-card:hover) .reference-card:not(:hover) {
  transform: scale(0.9);
  opacity: 0.6;
}

淡入动画也采用同样的方法，因此 JS 和样式之间不存在协调开销：

.reference-card { opacity: 0; }

.reference-card.fade-in {
  opacity: 1;
  animation: fade-in-up 0.5s ease-out forwards;
}

@keyframes fade-in-up {
  from { transform: translateY(20px); }
  to   { transform: translateY(0); }
}

最终想法

这个项目是一个很好的例子，说明了深思熟虑的架构如何将一种常见的模式变成真正可扩展的东西。通过将责任推向结构化数据，并使前端专注于高效的呈现和状态管理，参考列表块避免了臃肿的 DOM 和昂贵的重新呈现等常见缺陷。

真正的价值不仅在于过滤或展示，还在于系统本身。作者可以通过一种可预测、低摩擦的方式来管理内容，而实施过程仍然性能良好，易于扩展。这种模式会随着内容的增长而不断完善，而不是每次都要重新审视。

查看参考页面的运行情况！

关于作者

喜欢你听到的吗？对什么适合您有疑问？我们很乐意与您交谈！联系我们