本文详细介绍了如何在Pyodide环境中集成并使用Basthon修改版的Python Turtle模块，以实现在网页上动态渲染SVG图形。教程涵盖了自定义Turtle模块的打包、Pyodide的加载与包管理，以及通过JavaScript DOM操作将Turtle生成的SVG内容嵌入网页的关键步骤，最终实现浏览器内的可视化绘图。
在Web浏览器环境中直接运行Python的turtle模块面临挑战，因为它通常依赖于桌面GUI库（如Tkinter），而这些库在WebAssembly（WASM）环境中不可用。Pyodide使得在浏览器中运行Python成为可能，但标准的turtle模块仍需特殊处理。Basthon项目提供了一个兼容浏览器的turtle模块实现，它能够生成SVG格式的图形。本教程将指导您如何在Pyodide中使用Basthon的turtle模块，并在网页上展示动态的SVG绘图。
1. 构建Basthon Turtle自定义包
首先，我们需要获取Basthon的turtle模块源代码并将其打包成Pyodide可加载的wheel文件。
1.1 准备文件结构
创建一个项目目录，并将Basthon turtle模块的__init__.py和svg.py文件放置在指定位置。
pyodide/
turtle/
src/
turtle/
__init__.py # 从Basthon获取
svg.py # 从Basthon获取
pyproject.toml您可以在Basthon的Git仓库中找到这些文件： __init__.py: https://framagit.org/basthon/basthon-kernel/-/blob/master/packages/kernel-python3/src/modules/turtle/turtle/__init__.pysvg.py: https://framagit.org/basthon/basthon-kernel/-/blob/master/packages/kernel-python3/src/modules/turtle/turtle/svg.py
1.2 配置 pyproject.toml
在pyodide/turtle目录下创建pyproject.toml文件，用于定义包的构建信息：
# pyodide/turtle/pyproject.toml [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [project] name = "turtle" version = "0.0.1"
1.3 构建Wheel文件
使用以下脚本来构建自定义的turtle模块wheel文件。确保您的环境中安装了python3和pip。
#!/bin/bash # build.sh pushd pyodide/turtle python3 -m pip install --upgrade build python3 -m build popd
运行此脚本后，您将在pyodide/turtle/dist/目录下找到一个.whl文件，例如turtle-0.0.1-py2.py3-none-any.whl。这个文件就是我们将要在Pyodide中加载的自定义turtle模块。
2. Pyodide环境配置与模块加载
接下来，我们需要创建一个HTML页面来加载Pyodide，并引入我们刚刚构建的turtle模块。
2.1 HTML骨架
创建一个index.html文件，包含Pyodide的加载逻辑和一个用于显示SVG的div元素。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Pyodide Turtle SVG</title>
<script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js"></script>
<style>
body { font-family: sans-serif; margin: 20px; }
textarea { width: 90%; max-width: 800px; margin-bottom: 10px; }
button { padding: 10px 20px; cursor: pointer; }
#visual { border: 1px solid #ccc; min-height: 300px; width: 90%; max-width: 800px; margin-top: 20px; }
</style>
</head>
<body>
<h1>Pyodide Basthon Turtle SVG 渲染</h1>
<p>在下方输入Python Turtle代码，点击“运行”即可在页面上查看SVG绘图。</p>
<textarea id="input" cols="80" rows="15">
import turtle
t = turtle.Turtle()
t.forward(100)
</textarea>
<br/>
<button id="run" onclick="run()" disabled>运行</button>
<p id="status">正在加载 Pyodide...</p>
<div id="visual"></div>
<script type="text/javascript">
const runButton = document.getElementById("run");
const input = document.getElementById("input");
const visualDiv = document.getElementById("visual");
const statusParagraph = document.getElementById("status");
let pyodide;
const main = async () => {
pyodide = await loadPyodide({
// stdout: (text) => console.log(text), // 可选：用于调试Python的print输出
// stderr: (text) => console.error(text), // 可选：用于调试Python的错误输出
});
runButton.disabled = false;
statusParagraph.textContent = "Pyodide 加载完成。";
console.log("Pyodide loaded.");
};
main();
const run = async () => {
visualDiv.innerHTML = ""; // 清除之前的绘图
statusParagraph.textContent = "正在执行 Python 代码...";
try {
// 加载自定义的turtle wheel文件
// 确保 .whl 文件位于 `./turtle/dist/` 路径下，相对于 index.html
await pyodide.loadPackage("./turtle/dist/turtle-0.0.1-py2.py3-none-any.whl");
// 确保输入代码中的所有导入都被加载
await pyodide.loadPackagesFromImports(input.value);
// 执行Python代码
await pyodide.runPython(input.value);
statusParagraph.textContent = "Python 代码执行完毕，SVG 已渲染。";
} catch (error) {
console.error("执行 Python 发生错误:", error);
statusParagraph.textContent = `执行错误: ${error.message || error}`;
}
};
</script>
</body>
</html>2.2 运行环境说明
由于浏览器安全策略（CORS），直接通过file://协议打开index.html将无法加载.whl文件。您需要通过一个本地HTTP服务器来运行此HTML文件。最简单的方法是在包含index.html和pyodide目录的父目录中运行Python的简单HTTP服务器：
python -m http.server
然后，在浏览器中访问http://localhost:8000。
3. 实现SVG动态渲染
现在我们已经成功加载了Pyodide和自定义的turtle模块，关键在于如何将turtle生成的图形呈现在网页上。Basthon turtle模块的设计使得它能够生成SVG字符串，并通过Pyodide的js模块与JavaScript DOM进行交互。
3.1 核心Python代码
在HTML页面的<textarea id="input">中，输入以下Python代码。这段代码展示了如何利用js模块获取DOM元素，并将turtle生成的SVG注入其中。
import turtle
from js import document # 导入js模块，用于访问浏览器DOM
# 获取绘图屏幕并确保场景可见
# 这一步对于Basthon turtle的内部状态管理很重要
screen = turtle.Screen()
screen.show_scene()
# 创建画笔
t = turtle.Turtle()
t.speed(0) # 设置最快速度，方便观察结果
# 绘制一个简单的图形，例如一个正方形
for i in range(4):
t.forward(100)
t.left(90)
# 获取Basthon turtle生成的SVG字符串
# turtle.svg() 方法返回当前绘图的完整SVG XML字符串
svg_content = turtle.svg()
# 通过js.document访问HTML DOM，并将SVG内容注入到id为"visual"的div元素中
document.getElementById("visual").innerHTML = svg_content
# 您可以继续添加更多绘图逻辑，每次更新DOM即可看到变化
# t.penup()
# t.goto(50, 50)
# t.pendown()
# t.circle(30)
# document.getElementById("visual").innerHTML = turtle.svg() # 再次更新SVG3.2 解释
- from js import document: Pyodide提供了一个特殊的js模块，允许Python代码直接访问全局的JavaScript对象，如document、window等。这使得Python能够与浏览器DOM进行交互。
- turtle.Screen().show_scene(): 这行代码对于Basthon turtle模块的正常运行至关重要，它确保了绘图场景被初始化并准备好接收绘图指令。
- turtle.svg(): 这是Basthon turtle模块提供的一个方法，它返回当前绘图屏幕内容的SVG XML字符串表示。
- document.getElementById("visual").innerHTML = svg_content: 通过js.document获取HTML中ID为visual的div元素，然后将其innerHTML属性设置为turtle.svg()返回的SVG字符串。这样，SVG图形就会被动态地渲染到网页上。
4. 完整示例与注意事项
将上述HTML文件和Python代码结合，您将拥有一个完整的、可在浏览器中运行的Pyodide Basthon Turtle SVG绘图环境。
4.1 完整文件结构
.
├── index.html
└── pyodide/
├── turtle/
│ ├── src/
│ │ └── turtle/
│ │ ├── __init__.py
│ │ └── svg.py
│ └── pyproject.toml
└── turtle/
└── dist/
└── turtle-0.0.1-py2.py3-none-any.whl # 由 build.sh 生成4.2 注意事项
- CORS限制： 再次强调，为避免跨域资源共享（CORS）问题，您必须通过HTTP服务器（如python -m http.server）运行index.html，而不是直接在浏览器中打开本地文件。
- 动画机制： Basthon Turtle通过生成SVG字符串并将其注入DOM来实现“动画”效果。这意味着每次绘图状态发生变化并需要显示时，您都需要重新调用turtle.svg()并更新DOM。对于复杂的连续动画，频繁更新innerHTML可能会有性能开销。更高级的动画可能需要结合JavaScript的requestAnimationFrame，或者在Python端设计更精细的更新逻辑。
- 性能考量： 绘制非常复杂或包含大量元素的图形时，生成的SVG字符串可能会很大，频繁地解析和渲染这些SVG可能会影响浏览器性能。
- 错误处理： 在Pyodide中执行Python代码时，务必在JavaScript侧添加错误捕获机制，以便调试Python代码中可能出现的错误。
总结
通过本教程，我们成功地将Basthon修改版的Python turtle模块集成到Pyodide环境中，并实现了在网页上动态渲染SVG图形。关键步骤包括：构建自定义的turtle wheel包、配置Pyodide加载该包，以及利用Pyodide的js模块将turtle生成的SVG内容注入到HTML DOM中。这种方法为在Web浏览器中实现Python驱动的图形绘制提供了一个强大而灵活的解决方案，为教育、可视化和交互式应用开辟了新的可能性。
