Web-Dev-For-Beginners 温室（Terrarium）实战教程：系统化调研、记录并验证一个 DOM 接口的方法

本文以 Terrarium 课程第三部分的 DOM 接口调研作业 为主体，完整还原"选定 DOM 接口 → 撰写技术调研文档 → 提交可运行代码示例"的完整研究流程，并结合本仓库 solution 目录下的温室拖拽实现 深入讲解评分标准与实战要求。读完后，你将掌握一套可复用的 DOM API 调研方法论：如何按入门/进阶/高级分层选题、如何组织 300–500 词的调研文档、代码示例的验收准则，以及如何把调研结论与真实项目代码互相印证。

一、作业背景：从"会拖拽"到"懂 DOM 生态"

这份作业出现在 Terrarium 课程第三部分 之后。该课程部分的主题是用原生 JavaScript 实现 DOM 操作与闭包（closures），最终成果是一个可以把 14 株植物随意拖拽摆放的交互式温室页面。调研作业的目标不再是"继续写功能"，而是把课堂上亲手体验过的 DOM 能力放进更广阔的 DOM 接口世界中考察。

原文明确列出了四项学习目标，完成作业后你应该能够：

• Research：深入研究并理解某一个具体的 DOM 接口；
• Analyze：分析真实网站中 DOM 操作的具体实现；
• Connect：把理论概念与实际应用建立联系；
• Develop：锻炼技术文档写作与分析能力。

这四项能力组合起来，本质上就是"API 调研 → 源码印证 → 应用迁移"的工程师工作流。下文按作业原文的三个步骤逐步展开。

二、Step 1：如何选择调研的 DOM 接口

作业的第一步是选定一个调研对象。原文建议参照 MDN 的 DOM 接口总览页面（Mozilla Developer Networks 的 Document_Object_Model 文档）挑选自己感兴趣的接口，并为了方便选题，按难度分成了三档，共 12 个推荐方向：

入门友好档（Beginner-Friendly Options）：

接口	一句话定位
Element.classList	动态管理 CSS 类
Document.querySelector()	进阶的元素选择
Element.addEventListener()	指针事件之外的事件处理
Window.localStorage	客户端数据持久化存储

进阶挑战档（Intermediate Challenges）：

接口	一句话定位
Intersection Observer API	检测元素是否进入可视区域
MutationObserver	监听 DOM 结构变化
Drag and Drop API	区别于本课指针事件方案的另一种拖放实现
Geolocation API	获取用户地理位置

高级探索档（Advanced Exploration）：

接口	一句话定位
Web Components	自定义元素与 Shadow DOM
Canvas API	程序化图形绘制
Web Workers	后台线程计算
Service Workers	离线功能支持

选题时有一个隐含的"最佳实践"：优先选与已学内容形成对照的接口。例如 Terrarium 的拖拽用的是 Pointer Events + 闭包，如果你选 Drag and Drop API 调研，就能自然回答作业里"与温室项目对比"的要求；如果选 Window.localStorage，则正好对接课程结尾"用 localStorage 记住植物位置"的扩展挑战（见下文第五节）。

三、Step 2：撰写结构化调研文档（300–500 词）

作业要求产出一份 300–500 词的分析文档，原文把它拆成三个强制板块，每个板块都有明确的动词要求：

3.1 技术概览（Technical Overview）

• Define：用初学者能听懂的语言，定义你选的接口是做什么的；
• Explain：说明它提供的关键方法、属性或事件；
• Describe：描述它被设计用来解决什么类型的问题。

这一板块的验收标准是"能否讲给没写过代码的人听"。以课程自身使用的 Pointer Events 为例，合格的表述应当覆盖：pointerdown/pointermove/pointerup 三个核心事件、clientX/clientY 坐标属性，以及它"一套 API 同时兼容鼠标、触摸和手写笔"的跨设备价值。

3.2 真实实现分析（Real-World Implementation）

• Find：找一个实际使用了该接口的网站（审查其代码或研究公开示例）；
• Document：尽可能附上具体的实现代码片段；
• Analyze：分析开发者为什么选择了这种方案；
• Explain：说明它如何提升了用户体验。

这是评分表中权重最高、也最容易丢分的板块——评分标准里明确区分了"找到真实案例且分析充分"与"案例模糊或描述不准确"（见第五节 Rubric）。用浏览器开发者工具直接审查目标页面，是最可靠的取证方式。

3.3 实际应用（Practical Application）

• Compare：把你的接口与 Terrarium 项目中用过的技术做对比；
• Suggest：提出该接口如何能增强或扩展温室功能；
• Identify：识别其他适合使用该接口的项目场景。

这一板块要求调研必须"落地"到当前项目。比如选 localStorage，对比点就是：温室当前的拖拽位置刷新页面后即丢失，而 localStorage 可以把它持久化；选 Intersection Observer，则可以讨论用它检测植物是否被拖出玻璃罐可视范围。

四、Step 3：代码示例的验收标准

文档之外，作业还要求提交一段独立可运行的代码示例。原文给出了四条硬性要求：

要求	含义
Functional	代码实际测试后必须能跑通
Commented	每一部分都要有注释解释其作用
Relevant	要连接到一个真实的使用场景，而不是玩具代码
Beginner-friendly	初学者要能读懂

这四条与第五节评分表中"Code Example"维度一一对应：A 档要求"可运行、注释完善、清晰展示接口能力"，D 档则是"代码有错误或解释糟糕"。也就是说，代码示例本身就是评分对象的一部分，不是附录。

五、提交格式与评分标准

5.1 标准提交模板

原文规定了统一的 Markdown 提交结构，四段标题不可缺省：

# [Interface Name] DOM Investigation

## What It Does
[技术概览]

## Real-World Example
[网站分析与实现细节]

## Code Demonstration
[带注释的可运行示例]

## Reflection
[与温室项目的关联及未来应用场景]

注意最后一段 Reflection 对应的是 Step 2 的 Practical Application 板块——它要求把接口拉回 Terrarium 项目的语境，避免调研变成纯理论摘抄。

5.2 评分 Rubric（原文完整继承）

评分维度	优秀 (A)	合格 (B)	发展中 (C)	待改进 (D)
技术理解	解释准确、术语规范，体现深刻理解	理解扎实，解释基本准确	基础理解，存在个别误解	理解有限，存在明显错误
真实案例分析	找到真实实现并配合具体例子做透彻分析	找到真实案例且分析足够	找到了案例但分析缺乏深度	真实案例关联模糊或不准确
代码示例	可运行、注释完善，清晰展示接口能力	可运行且注释充分	能跑但文档化不足	代码有错误或解释很差
写作质量	结构清晰、表达生动，技术沟通规范	组织良好，技术写作到位	组织与清晰度尚可	组织混乱或表意不清
批判性思维	概念间建立深刻联系，并提出有创意的应用	分析思路好，关联恰当	有分析但深度不足	批判性思维证据有限

六、执行策略与写作规范

原文在"Tips for Success"中给出三组可操作的建议，这里完整保留并补充执行要点。

调研策略（Research Strategies）：

• 从 MDN 文档入手，获取权威定义；
• 在 GitHub 或 CodePen 上寻找可参考的代码示例；
• 用浏览器开发者工具审查热门网站的实际用法；
• 配合教程视频理解可视化流程。

写作规范（Writing Guidelines）：

• 用自己的话转述，而不是复制文档；
• 附上具体例子和代码片段；
• 把技术概念讲得像在教朋友；
• 把你的接口放到更大的 Web 开发脉络里谈。

代码示例构思（Code Example Ideas）：

• 做一个能展示该接口核心能力的最小 Demo；
• 在相关处基于 Terrarium 项目的概念往上搭；
• 功能优先于视觉设计；
• 提交前务必亲自测试。

此外，该作业文档本身已被翻译成 19 种语言版本，存放在 translations 目录 中（含中文简体版 assignment.zh-cn.md），可作为跨语言课堂的对照材料。

七、纵深解读：把课程自身代码当作"标准答案"来读

作业要求"把接口与 Terrarium 项目对比"，而本仓库恰好提供了完整的对照样本。下面以仓库中的真实代码为证据，演示一份合格调研文档应当如何取证与展开。

7.1 项目侧证据：Pointer Events + 闭包如何落地

课程给出的最终实现位于 3-terrarium/solution/script.js。整个文件只有约 60 行，却完整演示了"事件生命周期 + 闭包状态管理 + 资源清理"三个调研维度。

（1）入口：为 14 株植物各自创建独立的拖拽闭包

script.js 第 3–16 行 对 plant1 到 plant14 逐一调用 dragElement(document.getElementById('plantN'))。这些元素定义在 solution/index.html 中——左侧 7 株、右侧 7 株，均带唯一 id。这解释了课程为何强调"用 ID 而不是 class 做元素定位"：getElementById 返回单个精确引用，而 14 个 id 各自独立，才能支撑下文"每株植物一套私有坐标"的设计。

（2）核心：dragElement 闭包与四个私有坐标变量

dragElement 函数（第 23–64 行） 在函数体内声明了 pos1/pos2/pos3/pos4 四个私有变量，并通过 terrariumElement.onpointerdown = pointerDrag 把起始事件挂到元素上。文件第 18–21 行的注释直接点明了设计意图：

闭包 = 函数与其外围词法环境引用的组合；创建一个闭包，以便你能跟踪被拖拽的元素。

对调研文档的启示是：分析真实实现时，要指认"状态放在哪里"——这里的状态是每株植物一份、互不干扰的坐标记忆，这正是闭包"私有变量在父函数执行结束后依然存活"的特性带来的。

（3）事件生命周期：down → move → up 三步曲

• pointerDrag（第 31–41 行）：先 e.preventDefault() 阻止浏览器默认行为（如拖拽选中文字），再用 e.clientX/e.clientY 记录按下坐标，然后把 onpointermove/onpointerup 挂到 document 级别——挂在文档上而非元素上，保证指针快速移出植物时拖拽不中断；
• elementDrag（第 43–57 行）：每次移动都计算 pos1 = pos3 - e.clientX、pos2 = pos4 - e.clientY（"旧坐标减新坐标"的增量），随后把 style.top/style.left 更新为 offsetTop - pos2、offsetLeft - pos1，并刷新 pos3/pos4 作为下一帧基准；
• stopElementDrag（第 59–63 行）：将 document.onpointerup 和 document.onpointermove 置为 null，完成清理，避免监听器残留。

这套"按下记录 → 移动增量 → 松手清理"的闭环，正是课程 README 中状态图（Ready → DragStart → Dragging → DragEnd）所描述的流程的代码对应物。如果调研你的接口是 addEventListener()，那么本项目就是一个现成的"反面样本对照"：它用的是属性赋值式（onpointerdown =）绑定，调研中可以对比两种绑定方式在解绑语义上的差异。

7.2 CSS 前提：为什么 offsetTop/offsetLeft 能工作

拖拽代码修改的是 style.top/style.left，这依赖 solution/style.css 中的定位上下文：植物容器使用 position: absolute，#left-container 定位在 left: 0，#terrarium 相关元素同样参与绝对定位布局。课程 README 中也强调过 offsetTop/offsetLeft 是"相对于最近的定位祖先"的值。写调研文档的 Practical Application 板块时，这类"JS 行为依赖 CSS 定位上下文"的跨层依赖，正是"为什么这样设计"问题的典型答案素材。

7.3 一个可以直接完成的调研 Demo 思路：localStorage 持久化

课程 README 的 Additional Challenge 中列出了"用 localStorage 记住植物位置"的扩展。如果 Step 1 选择了入门档的 Window.localStorage，一条最短的验证路径是：在 pointerDrag 的松手清理逻辑（对应 stopElementDrag）处，把当前 14 个元素的 offsetTop/offsetLeft 序列化后写入 localStorage；页面加载时读出并逐元素回写 style。这样"技术概览（存什么、怎么存）→ 真实案例（浏览器控制台验证 Storage 面板）→ 代码示例（读写 + 容错）→ 反思（对比温室现状：刷新即失忆）"四个板块就全部闭环了。

八、与课程流程的衔接

• 前置依赖：作业开头提到"你现在已经亲手体验过 DOM 操作的力量"，前提是完成了 Terrarium 前两课（HTML 结构 + CSS 布局）与本课的拖拽实现；3-terrarium/solution 目录提供了完整的可运行参照（index.html + style.css + script.js）。
• 交付物边界：提交物是"一份 300–500 词的文档 + 一段可运行、带注释的代码 + 按标准模板组织的结构"，而不是另一个完整项目；功能优先于视觉设计是原文明确的取向。
• 进阶出口：README 中"Review & Self Study"部分列出的 Event Delegation、Intersection Observer、Mutation Observer、Web Components 等主题，恰好与作业进阶/高级档选题重合——完成这份调研后，这些方向就是现成的下一步。

一句话总结：这份作业的价值不在于"再写一个功能"，而在于训练你以工程师的方式审视任何一个 DOM 接口——权威文档打底、真实站点取证、代码跑通验证、回到自己的项目里做对照迁移。仓库里 60 行的 solution/script.js 就是这套方法最贴近的练习场。