preview-import

预览导入内容

在本地开发服务器中打开并验证导入的内容。

何时使用此技能

在以下情况下使用此技能：

• 已生成 HTML 文件（来自 generate-import-html）
• 准备在浏览器中预览并验证渲染效果
• 需要与原始页面结构进行比较

由以下技能调用： page-import 技能（步骤 5）

前置条件

你需要从之前的技能中获得：

• ✅ 路径正确的 HTML 文件（来自 generate-import-html）
• ✅ 同一目录中的图片文件夹
• ✅ 来自 scrape-webpage 的 screenshot.png（用于比较）
• ✅ 来自 metadata.json 的 documentPath（用于构造 URL）

相关技能

• page-import - 调用此技能的协调器
• generate-import-html - 提供要预览的 HTML 文件
• scrape-webpage - 提供用于比较的截图

预览工作流

步骤 1：使用 HTML 文件夹标志启动开发服务器

确定 metadata.json 中的文件夹：

• 查看 metadata.json 中的 paths.dirPath（例如 /us）
• 这是包含导入 HTML 文件的根文件夹

命令：

aem up --html-folder {dirPath}

根据导入内容位置的示例：

HTML 文件位置	命令	预览 URL
us/en.plain.html	aem up --html-folder us	http://localhost:3000/us/en
products/widget.plain.html	aem up --html-folder products	http://localhost:3000/products/widget
blog/2024/post.plain.html	aem up --html-folder blog	http://localhost:3000/blog/2024/post

为何必须这样做：

• 如果不使用 --html-folder，AEM CLI 会将请求代理到远程服务
• 远程服务上没有你本地导入的内容
• 结果：出现 404“找不到页面”错误

---

步骤 2：在浏览器中导航

对于大多数文件，直接使用文档路径：

http://localhost:3000${documentPath}

示例：

• HTML 文件：us/en/about.plain.html
• URL：http://localhost:3000/us/en/about

重要：对于 index 文件，请使用 / 而不是 /index：

If file is: index.plain.html
Preview at: http://localhost:3000/
NOT: http://localhost:3000/index

**注意：**如果使用了 --html-folder 标志（例如 aem up --html-folder drafts），请在 URL 前加上该文件夹：

File: drafts/test.plain.html
URL: http://localhost:3000/drafts/test

使用 metadata.json 中的 paths.documentPath，但对于 index 文件，请确保路径是 / 而不是 /index

---

步骤 3：验证渲染效果

检查以下内容：

• ✅ 区块以正确的样式呈现
• ✅ 布局与原始页面结构相符（与 screenshot.png 比较）
• ✅ 图片已加载（或显示适当的占位符）
• ✅ 没有显示原始 HTML
• ✅ 页面源代码中显示元数据（查看源代码，检查 <meta> 标签）
• ✅ 已正确应用区段样式

---

步骤 4：与原始页面比较

并排比较：

1. 在浏览器预览旁打开 ./import-work/screenshot.png
2. 检查内容结构是否相符
3. 验证区块是否正确装饰
4. 确认区段边界是否对齐
5. 验证样式是否一致

---

故障排除

区块无法正确渲染：

• 检查 HTML 结构是否符合预期格式
• 确认区块名称完全匹配（区分大小写）
• 查看 ../content-driven-development/references/html-structure.md，了解格式指南

图像无法加载：

• 确认图像文件夹与 HTML 文件位于同一目录
• 检查图像路径是否采用 ./images/... 格式
• 确认图像已从 ./import-work/images/ 正确复制

显示原始 HTML：

• 区块名称可能与项目中的现有区块不匹配
• 检查浏览器控制台中是否有 JavaScript 错误
• 确认区块存在于 blocks/ 目录中

页面源代码中没有元数据：

• 检查元数据区块是否位于 HTML 文件末尾
• 查看页面源代码，并在 <head> 中搜索 <meta> 标签
• 确认元数据属性符合预期格式

开发服务器未运行：

• 使用 aem up 启动服务器
• 检查是否存在端口冲突（默认端口为 3000）
• 确认当前位于正确的项目目录中

找不到页面（404）：

• **最常见原因：**缺少 --html-folder 标志——使用 aem up --html-folder {dirPath} 重新启动服务器
• 确认 HTML 文件存在于预期路径
• 检查 metadata.json 中的 documentPath 是否与 URL 匹配
• 对于索引文件，使用 /，不要使用 /index
• 检查终端输出是否确认“正在从文件夹 {folder} 提供 HTML 文件”

---

输出

此技能提供：

• ✅ 已验证的预览，与原始页面结构一致
• ✅ 正确渲染的可视化确认
• ✅ 已验证的区块装饰
• ✅ 已确认元数据存在

所有验证项均通过后，即表示导入完成。