$SIMULATION_NAME MicroSim 使用 P5.js 1.11.10

# P5.js 教育性 MicroSim 创建技能 ## 概述此技能指导使用 p5.js JavaScript 库创建教育 MicroSims。 MicroSims 是轻量级的交互式教育模拟，专为基于浏览器的学习而设计。 MicroSims 在**简单性**（集中范围、透明代码）、**可访问性**（浏览器原生、通用嵌入）和 **AI 生成**（标准化模式、提示兼容设计）的交叉点上占据着独特的地位。 ## 标准上下文此 MicroSim 技能旨在创建在您的网站上运行 MicroSim 所需的所有文件。该 microsim 技能设计为在 Claude 代码中运行。最佳实践是从命令行启动 Claude Code（位于 GitHub checkout 目录的根目录）。这比您运行 GitClone 的位置低一级。该目录应包含一个“.git”目录。如果您没有看到“.git”目录和“mkdocs.yml”文件，则警告用户自动安装过程可能会失败。我们假设该网站有一个名为“docs/sims”的文件夹，每个 MicroSim 将放置在其中。如果您没有看到此文件夹，则警告用户。 p5.js 文件还设计为可以通过将 JavaScript 直接粘贴到 p5.js 编辑器站点来进行测试。生成 JavaScript 文件后，指示用户现在可以测试 MicroSim。 ## 目的教育 MicroSims 将抽象概念转化为视觉交互、可操作的体验，使学生能够通过探索和实验进行学习。每个 MicroSim 都能解决特定的学习目标，同时保持教育部署所需的教学严谨性和技术质量。 MicroSims 旨在由现有网站上的 iframe 引用，或快速添加到使用 mkdocs 创建的网站或智能教科书中。由于 MicroSims 对控件有严格的规则，因此它们可以生成 xAPI (eXperience API IEEE 9274.1.1-2023) 调用，以便可以将 JSON 格式的交互事件添加到 LRS 学习记录存储 IEEE 1484.20-2024。 ## 开发流程 ### 第 1 步：教育要求规范在生成代码之前，阐明教育目的： 1. **学科领域和主题**：该模拟教授什么具体概念？ 2. **年级**：小学 (K-5)、初中 (6-8)、高中 (9-12) 或本科 3. **学习目标**：学生使用此模拟后应该了解什么？（与布鲁姆的分类法一致：记住、理解、应用、分析、评估、创造）。此步骤至关重要，因为生成的 p5 MicroSim 类型将取决于此分类。 4. **持续时间**：典型的参与时间（建议 5-15 分钟） 5. **先决条件**：使用此工具之前学生必须具备哪些知识？ 6. **评估机会**：教育工作者如何验证学习情况？用户可以在此版本上看到“测验模式”按钮吗？此信息将记录在index.md 文件的末尾，并存储在名为metadata.json 的文件中，该文件由JSON 架构验证，网址为 ### 步骤 2：使用 p5.js 实现 MicroSim 遵循标准化 MicroSim 架构生成独立的交互式 p5.js 模拟。该程序是宽度响应式的，我们创建的 p5.js javascript 文件应该使用 p5.js 编辑器无需更改即可运行，以便用户轻松测试。 #### 文件夹结构 MicroSims 有两个属性： 1. MICROSIM_TITLE：带有空格的标题大小写字符串 2. MICROSIM_NAME：带破折号的小写字符串（kebob 大小写）每个 MicroSim 都包含在 /docs/sims 目录中的一个文件夹中。文件夹名称为 $MICROSIM_NAME，包含以下内容： /docs/sims/$MICROSIM_NAME # MicroSim 的容器文件夹 /docs/sims/$MICROSIM_NAME/index.md # 每个包含 iframe 和文档的 MicroSim 的主索引降价 /docs/sims/$MICROSIM_NAME/main.html # 包含 p5.js CDN 链接并导入 p5.js JavaScript 的主 HTML5 文件 /docs/sims/$MICROSIM_NAME/$MICROSIM_NAME.js # 所有 p5.js JavaScript /docs/sims/$MICROSIM_NAME/metadata.json # 包含都柏林核心元数据和控件描述的 JSON 文件以下步骤是在使用 mkdocs 构建的已签出的智能教科书中生成新 MicroSim 的示例。该技能包含“index.md”、“main.html”、“metadata.json”和“bouncing-ball.js”的模板。 1. 将在 `/docs/sims` 区域内创建一个新文件夹。文件夹名称仅包含小写字母和破折号。这将是 MICROSIM_NAME，即 kebab 大小写字符串。 2. 将在描述 MicroSim 的文件夹中生成一个“index.md”文件，并在 iframe 中包含对“main.html”文件的引用 3. 一个小的“main.html”文件将包含标题、从 CDN 到 p5.js 库的链接并包含 MICROSIM_NAME.js 文件。 `main.html` 文件正文中必须包含一个 `main` HTML 元素。 4. 将创建一个名为“metadata.json”的文件，该文件符合 /src/microsim-schema/microsim-schema.json 中的架构。这将包含都柏林核心元素，例如标题、主题、作者、出版日期等。使用此文件以便分面搜索引擎可以找到此 MicroSim ## 技术架构标准 ### Iframe 结构（必需） MicroSims 设计为由 HTML“iframe”调用。它们在宽度可变的固定高度区域中运行。这是一项基本要求，它将影响您在生成 MicroSim 时所做的许多设计选择。尽管 main.html 文件可能在“

”元素之外有一些文本，例如返回文档的链接，但这些文本很小，因此教科书中“iframe”占用的区域也最小化。将标题放在“

”上方会影响在许多教育环境中重用 microsim 的能力，在这些环境中，屏幕空间的管理至关重要。以下是如何将 MicroSim 集成到任何课程网页中的示例：文档页面（index.md）将提供此 iframe 语句的示例，以便用户轻松复制。所有包含 MicroSim 的 iframe 都设计为在其容器的整个宽度上运行并且不滚动。这防止用户将看到的滚动区域与网页的滚动区域混淆。每个 MicroSim 必须有两个不同的“iframe”画布区域： 1. 顶部“绘图”区域，具有固定高度，称为“drawHeight”。绘图区域中未放置任何用户界面控件。 2. 绘图区域下方的用户界面“控制”区域，其中包含具有固定高度（称为“controlHeight”）的按钮和滑块。画布的**宽度**根据容器调整大小。它最初被设置，但当容器更改时在绘制循环中重置。每次调整 Web 浏览器窗口大小时都会调用此调整大小函数。我们使用这种布局模式： // 画布尺寸 - 所需结构让画布宽度= 400； // 初始宽度（响应式）让绘制高度 = 400; // 绘图/模拟区域高度让控制高度= 50； // 控制区域高度让画布高度 = 绘制高度 + 控制高度；令保证金 = 25； // 视觉元素的边距让滑块LeftMargin = 105； // 滑块定位的左边距。这是最大标签和值的水平尺寸之和。让defaultTextSize = 16; // 基本文本大小函数设置() { updateCanvasSize(); // 这获取我们正在运行的容器的宽度 const canvas = createCanvas(canvasWidth, canvasHeight); canvas.parent(document.querySelector('main')); // 在这里创建滑块和控件 // 相对于drawHeight的位置控件描述（'屏幕阅读器的教育描述'，LABEL）； } 函数绘制（）{ updateCanvasSize(); // 绘图区域（浅蓝色背景）填充（'爱丽丝蓝'）；矩形(0, 0, 宽度, 绘制高度); // 控制区域（白色背景）填充（'白色'）；矩形（0，绘制高度，宽度，控制高度）； // 将标题放置在画布的顶部中央填充（'黑色'）；文本大小（36）； // 标题字体变大文本对齐（居中，顶部）；没有中风（）； text('MicroSim 的标题', canvasWidth/2, margin); // 返回默认设置以避免主绘图代码中出现错误中风（）；文本对齐（左，中）；文本大小（默认文本大小）； // 主要绘图代码在这里 // 在控件区域中绘制控件标签和值 } 请注意，每个 MicroSim 都应该有一个位于顶部居中的标题。 ### 响应式设计（必需）实现嵌入各种平台的水平响应能力：函数窗口调整大小（）{ updateCanvasSize(); 调整画布大小（画布宽度，画布高度）； } 函数 updateCanvasSize() { const 容器 = document.querySelector('main'); 如果（容器）{ canvasWidth = 容器.offsetWidth; // 重新定位所有控件以匹配新宽度 // 当容器大小改变时，所有水平滑块都会调整大小 if (typeof speedSlider !== '未定义') { // 更新滑块的大小 speedSlider.size(canvasWidth - sliderLeftMargin - margin); } } } ### 视觉设计标准 **配色方案**： * 绘图区域背景：`'aliceblue'` * 控制区域背景：`'白色'` * 边框：“银色”，1px 宽度 * 互动元素：使用高对比度、色盲安全的颜色 **版式**：尽量避免使用任何小于 16pt 的文本。我们希望在教室后面也能阅读 MicroSim 文本。 * 默认标题大小：36px * 默认文字大小：16px * 控制标签：粗体，在控制区域中一致定位 * 数值显示：显示当前参数值 ### 控制模式 **控制区域中的水平滑块**（对于连续参数）：滑块是使用最小、最大、默认和步长参数创建的。然后将它们放置在drawHeight下方，并将X放置在sliderLeftMargin上方。滑块的宽度由 size 方法控制，跨越画布的宽度减去 sliderLeftMargin - 15； #### 滑块初始化滑块是在“setup()”函数中创建的。所有滑块都是水平滑块。速度滑块 = createSlider(0, 20, 3, 0.1); speedSlider.position（sliderLeftMargin，drawHeight + 15）； speedSlider.size(canvasWidth - sliderLeftMargin - 15); speedSlider.input(resetSimulation); 不要使用“style”方法来更改滑块的宽度。仅使用“大小”方法。 ### 滑块宽度响应行为如果容器宽度发生变化，所有水平滑块都必须使用“大小”重新计算其宽度。 ### 滑块标签值放置在“draw()”函数结束时，必须更新滑块的标签和值。它们应该以 10 左右的固定 x 偏移值放置。标签和值使用 JavaScript“+”运算符连接在一起。每行标签/值/滑块控件应放置在前一行下方 30 处。 text('速度：'+速度，10，drawHeight+20); text('角度：' + 角度，10，drawHeight+50); ### 用于启动和暂停模拟的按钮例如，如果模拟有一个状态全局变量“isRunning”，则可以像这样创建按钮： **按钮**（用于离散操作）： startButton = createButton(isRunning ? '暂停' : '开始'); startButton.position(10,drawHeight + 15); startButton.mousePressed(toggleSimulation); ### 使用复选框显示附加可选信息 **复选框**（用于切换选项）： showGridCheckbox = createCheckbox('显示网格', false); showGridCheckbox.position(10,drawHeight + 15); ## main.html 我们的目标是保持与 p5.js 编辑器的完全兼容性。生成的 JavaScript 代码应始终直接粘贴到 p5.js 编辑工具中。该工具使用标准的 main.html 文件，其中包含保存画布的 '` 元素。这是我们建议使用的 main.html 模板： <头> <元字符集=“UTF-8”> $SIMULATION_NAME MicroSim 使用 P5.js 1.11.10 <脚本src =“https://cdn.jsdelivr.net/npm/p5@1.11.10/lib/p5.js”> <风格> 身体{ 边距：0 像素；内边距：0px；字体系列：Arial、Helvetica、sans-serif； } <正文> <主>
返回文档 ### 自定义 main.html 文件每个 main.html 文件中必须修改以下项目： 1. JavaScript 文件的路径名应修改为使用 MicroSim 目录中 JavaScript 文件的名称。 2. 正文中的标题元素必须针对每个 MicroSim 进行修改。 3. 仅当代码运行出现问题时才应更改 CDN 路径中的版本号。请注意，对于控制区域中的标签放置，我们将边距和填充都设置为 0。我们不使用单独的 CSS 文件。这使我们的代码更加简单。 ### P5.js 版本更新请注意，此模板使用 jsdelivr.net CDN 来获取主 p5.js 库。版本号硬编码在此路径中。如果发现错误，一个建议是验证该库是否是 p5.js 编辑器中当前使用的库。以下Python代码将返回最新版本的p5.js。请注意，到 2026 年 8 月，p5.js 的默认版本将为 2.x。 ## Index.md 生成必须为每个 MicroSim 生成一个模板文件“index.md”。该文件在 header 1 标题之前包含 yml 格式的元数据 ### Index.md 元数据 --- 作品名称：弹跳球描述：一个在绘图区域内弹跳的球的 MicroSim，带有用于更改速度的控件。图片：/sims/bouncing-ball/bouncing-ball.png og：图像：/sims/bouncing-ball/bouncing-ball.png 推特：图片：/sims/bouncing-ball/bouncing-ball.png 社会：卡：假 --- 这是index.md文件内容的示例 # 弹跳球对于高度，它应该是drawHeight和controlHeight之和加2。 ### 学习管理系统集成 MicroSim 的设计应能够轻松地与任何支持 HTML“iframe”元素的网站集成。 * 兼容 Canvas、Blackboard、Moodle、Google Classroom * 无服务器端要求 * 在受限网络环境中工作 * 适合平板电脑和智能手机的移动设备 ### xAPI 集成（可选）对于学习分析，MicroSims 可以发出 xAPI 语句： * 按钮点击、滑块调整 * 完成任务所花费的时间 * 参数探索模式 * 嵌入式评估的表现 ## 教学环境 ### 研究基金会教育模拟展示了一致的优势： * 概念理解提高 15-25% * 掌握时间缩短 30-40% * 学生参与度提高 25-35% ### 有效的使用策略 * **引导探索**：提供 2-3 个开放式问题来重点调查 * **预测-测试-观察**：让学生在操作之前进行预测 * **协作学习**：结对/小组讨论观察结果 * **脚手架挑战**：从简单到复杂的参数空间的进展 ### 要避免的常见陷阱 * ❌ 太多控制（认知超载） * ❌ 因果关系不明确 * ❌ 没有交互性的动画 * ❌ 过于简单化会造成误解 * ❌ 无法访问的界面（对比度差，不支持键盘） ## MicroSim 示例：弹跳球（物理） ### 教育目的展示重力和弹性对抛射运动的影响，说明能量守恒和损失。 ### 学习目标 * 了解重力加速度与轨迹之间的关系 * 观察非弹性碰撞中的能量损失 * 应用物理概念来预测行为 ### 实施亮点 // 核心物理模型速度.y += 重力； // 重力加速度位置.add(速度); // 碰撞检测和响应 if (position.y >= 高度 - 半径) { 位置.y = 高度 - 半径；速度.y *= -弹性； // 反弹时的能量损失 } ### 提供的控件 * 重力滑块（0-2 m/s²，默认：0.5） * 弹性滑块（0-1，默认：0.7） * 开始/暂停按钮 * 重置按钮此示例演示了所有核心 MicroSim 原则：聚焦范围、透明物理、即时反馈和简洁界面。 ## 持续改进 ### 基于使用的迭代 * 收集教育工作者和学生的反馈 * 观察学生探索最多的参数 * 识别互动中揭示的常见误解 * 根据实际课堂使用情况进行细化 ### AI 辅助细化初始生成后，通过以下提示迭代改进： *“添加滑块控制[参数]” *“显示当前速度值” *“包括显示能量随时间变化的图表” *“添加网格以帮助学生测量距离” ## 包含在 mkdocs 导航系统中创建文件后，下一步是将 MicroSim 包含在 mkdocs 导航系统中。这是通过向 GitHub 存储库主目录中的“mkdocs.yml”文件添加一行来完成的。 mkdocs.yml 文件包含一个“nav”元素。其中将有一个用于所有 MicroSims 的部分。导航： [文字省略...] - 微模拟： - MicroSims 列表：sims/index.md - MicroSim 名称 1：sims/name-1/index.md - MicroSim 名称 2：sims/name-2/index.md [文字省略...] 最佳实践是将您刚刚创建的新 MicroSim 添加到 MicroSims 的末尾，如下所示：导航： [文字省略...] - 微模拟： - MicroSims 列表：sims/index.md - MicroSim 名称 1：sims/name-1/index.md - MicroSim 名称 2：sims/name-2/index.md - NEW_MICROSIM_NAME_HERE：sims/name-in-kebab-case/index.md [文字省略...] ## 拉链包装（可选）默认情况下，除非用户请求，否则不会创建 zip 包。如果用户请求“创建包”或“创建 zip 包”，则在生成包含所需文件的 MicroSim 后，创建用户可以下载的 zip 文件。然后返回如下指令：恭喜！您的 MicroSim zip 文件已生成并可供测试。安装它的最佳方法是使用 bouncing-ball 示例运行以下命令： cd /doc/模拟人生解压弹跳球.zip ## 测试部署如果您要在 mkdocs 站点中测试 MicroSim，您还可以执行以下操作： # 将 zip 文件移开，这样它就不会被复制到网站上 mv bouncing-ball.zip /tmp # 编辑 mkdocs.yml 文件打开../../mkdocs.yml # 在本地测试你的代码 mkdocs 服务 # 转到正确的链接：http://localhost:8000/[GITHUB_DIR_NAME]/sims/[sim-name]/ # 使用 git 检查你的代码 # 将新的 microsim 部署到生产环境！ mkdocs gh 部署然后确保站点导航 (mkdocs.yml) 文件包含指向此新 MicroSim 的链接。 ## 结论教育 MicroSims 代表了教学有效性、技术可访问性和人工智能生成能力的强大融合。通过遵循这些标准，任何受益于交互式探索的教育理念都可以转化为高质量、可嵌入、可重复使用的学习工具。关键是保持专注：一个概念、清晰的互动、即时反馈、透明的实施。每个 MicroSim 都应该是精心制作的、在教学上合理的，并且准备好在真实的教育环境中部署。 ** ** **对于 Anthropic Claude 代码**：创建 MicroSims 时，请始终引用“.cursor/rules/microsims.mdc”中的综合规则，并遵循“src/microsim-schema.json”中的元数据架构。每个 MicroSim 都应该像是一个由在各自领域处于领先地位的专业教学设计师和开发人员开发的精美教育工具。

微SIM P5

包含技能