building-blocks

构建模块

本技能将指导你遵循既定模式和最佳实践，实现 AEM Edge Delivery 模块。模块通过 JavaScript 装饰和 CSS 样式，将编写的内容转化为丰富的交互式体验。

重要提示：此技能只能在第 5 步（实施）期间，由 content-driven-development 技能调用。

如果你尚未遵循 CDD 流程，请停止并先调用 content-driven-development 技能。

相关技能

• content-driven-development：使用此技能前必须先调用，以确保内容和内容模型已准备就绪
• da-auth：如果实施开始前需要将测试内容推送到 DA，请获取有效的 Adobe IMS 令牌
• block-collection-and-party：用于查找类似模块，了解其模式
• testing-blocks：在第 5 步期间自动调用，进行全面测试

何时使用此技能

content-driven-development 会在第 5 步（实施）期间自动调用此技能。此技能适用于：

模块开发：

• 创建新的模块文件和结构
• 实现 JavaScript 装饰
• 添加 CSS 样式

核心功能：

• 修改 Scripts.js（装饰、实用工具、自动模块化）
• 全局样式（styles.css、lazy-styles.css）
• 延迟功能（delayed.js）
• 配置更改

组合场景：

• 同时需要核心更改（实用工具、全局样式等）的模块

前提条件（由 CDD 验证）：

• ✅ 测试内容已就绪（位于 CMS 或本地草稿中）
• ✅ 内容模型已定义并记录（如适用）
• ✅ 测试内容 URL 可用
• ✅ 开发服务器正在运行

模块实施工作流

跟踪进度：

• 第 1 步：查找类似模块，了解其模式（适用于新模块或重大更改）
• 第 2 步：创建或修改模块结构（文件和目录）
• 第 3 步：实现 JavaScript 装饰（仅限 CSS 的情况可跳过）
• 第 4 步：添加 CSS 样式
• 第 5 步：测试实施情况（调用 testing-blocks 技能）

**注意：**如果更改需要修改核心内容（scripts.js 中的实用工具、全局样式等），请先进行这些更改并测试，然后再返回此工作流。请参阅下文的“修改核心文件时”。

第 1 步：查找类似模块

**适用场景：**创建新模块或进行重大结构修改

**跳过此步骤的情况：**对现有模块进行小幅修改（调整 CSS、少量修改装饰）

快速开始：

1. 在代码库中搜索类似模块：

   ls blocks/
   

2. 使用 block-collection-and-party 技能查找参考实现

3. 查看类似模块的模式：

   • DOM 操作策略
   • CSS 架构
   • 变体处理
   • 性能优化

第 2 步：创建或修改模块结构

对于新模块：

1. 创建模块目录和文件：

   mkdir -p blocks/{block-name}
   touch blocks/{block-name}/{block-name}.js
   touch blocks/{block-name}/{block-name}.css
   

2. 基本 JavaScript 结构：

   /**
    * decorate the block
    * @param {Element} block the block
    */
   export default async function decorate(block) {
     // Your decoration logic here
   }
   

3. 基本 CSS 结构：

   /* All selectors scoped to block */
   main .{block-name} {
     /* block styles */
   }
   

对于现有模块：

1. 找到模块目录：blocks/{block-name}/
2. 查看当前实现：

   # View the initial HTML structure from the server
   curl http://localhost:3000/{test-content-path}
   

3. 了解现有的装饰逻辑和样式

第 3 步：实现 JavaScript 装饰

核心模式——重复使用现有 DOM 元素：

export default async function decorate(block) {
  // Platform delivers images as <picture> elements with <source> tags
  const picture = block.querySelector('picture');
  const heading = block.querySelector('h2');

  // Create new structure, re-using existing elements
  const figure = document.createElement('figure');
  figure.append(picture);  // Re-uses picture element

  const wrapper = document.createElement('div');
  wrapper.className = 'content-wrapper';
  wrapper.append(heading, figure);

  block.replaceChildren(wrapper);

  // Only check variants when they affect decoration logic
  // CSS-only variants like 'dark', 'wide' don't need JS
  if (block.classList.contains('carousel')) {
    // Carousel variant needs different DOM structure/behavior
    setupCarousel(block);
  }
}

完整的 JavaScript 指南包括：

• 高级 DOM 操作模式
• 获取数据和加载模块
• 性能优化技巧
• aem.js 中的辅助函数
• 代码风格和 lint 规则

请阅读 references/js-guidelines.md

第 4 步：添加 CSS 样式

基本模式——使用作用域、支持响应式，并使用自定义属性：

/* All selectors MUST be scoped to block */
main .my-block {
  /* Use CSS custom properties for consistency */
  background-color: var(--background-color);
  color: var(--text-color);
  font-family: var(--body-font-family);
  max-width: var(--max-content-width);

  /* Mobile-first styles (default) */
  padding: 1rem;
  flex-direction: column;
}

main .my-block h2 {
  font-family: var(--heading-font-family);
  font-size: var(--heading-font-size-m);
}

main .my-block .item {
  display: flex;
  gap: 1rem;
}

/* Tablet and up */
@media (width >= 600px) {
  main .my-block {
    padding: 2rem;
  }
}

/* Desktop and up */
@media (width >= 900px) {
  main .my-block {
    flex-direction: row;
    padding: 4rem;
  }
}

/* Variants - most are CSS-only */
main .my-block.dark {
  background-color: var(--dark-color);
  color: var(--clr-white);
}

完整的 CSS 指南包括：

• 所有可用的 CSS 自定义属性
• 现代 CSS 特性（网格、逻辑属性等）
• 性能优化
• 命名约定
• 常见模式和反模式

阅读 references/css-guidelines.md

关于迭代验证的说明： 在构建过程中，你可以随时在浏览器中测试更改（加载测试内容 URL、检查控制台、验证布局和功能）。如需了解全面的测试指南，包括浏览器测试技巧、响应式测试和验证方法，请参阅第 5 步中调用的 testing-blocks 技能。

第 5 步：测试实现

实现完成后，调用 testing-blocks 技能。

testing-blocks 技能将指导你完成：

• 浏览器测试（功能，以及在不同视口下的响应式表现）
• 代码检查并修复问题
• 为逻辑复杂的工具编写单元测试（如有需要）
• 截取屏幕截图以进行验证
• 性能验证

向 testing-blocks 技能提供：

• 正在测试的区块名称
• 测试内容 URL（来自 CDD 流程的第 4 步）
• 需要测试的任何变体
• 用于对照验证的现有实现／设计／样稿截图
• 需要验证的验收标准（来自 CDD 流程的第 2 步）

测试完成后，返回 CDD 工作流。

---

修改核心文件时

如果更改需要修改核心文件（scripts.js、styles.css、delayed.js），请遵循以下原则：

常见核心文件：

• scripts.js - 装饰工具、自动区块化逻辑、页面加载
• styles.css - 全局样式（优先加载）、CSS 自定义属性
• lazy-styles.css - 全局样式（延迟加载）
• delayed.js - 营销、分析、第三方集成

关键原则：

1. 先进行核心更改（再进行依赖这些更改的区块更改）
2. 使用现有内容独立测试核心更改，然后再用于区块
3. 考虑影响范围——核心更改可能影响多个区块／页面
4. 彻底测试——确认现有功能没有退化
5. 保持精简——只添加必要内容
6. 通过代码注释记录——大多数核心更改不需要单独的文档

测试核心更改：

• 使用会涉及受影响功能的现有内容 URL 进行测试
• 对于自动区块化：测试应该／不应该触发该功能的页面
• 对于全局样式：在多个区块和页面上进行测试
• 检查控制台是否有错误
• 验证响应式表现

详细模式：

• JavaScript：参阅 references/js-guidelines.md
• CSS：参阅 references/css-guidelines.md

---

参考资料

• references/js-guidelines.md - 完整的 JavaScript 模式和最佳实践
• references/css-guidelines.md - 完整的 CSS 模式和最佳实践