本文介绍如何使用 PyScript 在网页中实现用户上传 CSV 文件、通过 Python 读取并解析为列表，重点解决 document 未定义、文件对象无法直接传入 pandas 等常见错误，并提供完整可运行的异步处理方案。
本文介绍如何使用 pyscript 在网页中实现用户上传 csv 文件、通过 python 读取并解析为列表，重点解决 `document` 未定义、文件对象无法直接传入 pandas 等常见错误，并提供完整可运行的异步处理方案。
在 PyScript 中直接操作浏览器文件需兼顾 JavaScript 与 Python 的交互边界：PyScript 运行于 WebAssembly 环境（Pyodide），不自动暴露全局 document 对象，且浏览器 File 对象并非 Python 原生支持的文件句柄。因此，必须显式导入 js.document，并通过异步方式将文件内容转为 Python 可读的字节流。
以下是一个结构清晰、生产可用的实现方案：
✅ 正确步骤概览
- 延迟执行：使用 @when('change', '#upload') 装饰器监听文件选择事件，避免页面加载时立即执行；
- 获取文件：通过 document.getElementById('upload').files.item(0) 获取首个选中文件（注意 .item(0)，非 [0]）；
- 异步读取内容：调用 await file.arrayBuffer() 获取 ArrayBuffer，再转为 bytes；
- 封装为文件类对象：用 io.BytesIO 包装原始字节，使 pandas.read_csv() 可识别；
- 解析与输出：加载为 DataFrame 后，通过 .values.tolist() 转为嵌套列表并打印。
? 完整可运行代码
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>PyScript CSV Analyzer</title>
<link rel="stylesheet" href="https://pyscript.net/releases/2023.05.1/pyscript.css"/>
<script defer src="https://pyscript.net/releases/2023.05.1/pyscript.js"></script>
</head>
<body>
<py-config>
packages = ["pandas"]
</py-config>
<div class="row overflow-hidden" id="content">
<div class="col mh-100 float-left" id="main">
<h3>Upload a CSV file:</h3>
<input type="file" name="upload" id="upload" accept=".csv">
<div id="output"></div>
</div>
</div>
<py-script>
from js import document
from io import BytesIO
import pandas as pd
from pyscript import when
@when('change', '#upload')
async def processFile(*args):
# 1. 获取用户选择的文件
file_input = document.getElementById('upload')
if not file_input.files.length:
print("⚠️ No file selected.")
return
csv_file = file_input.files.item(0)
# 2. 异步读取文件内容（必须 await）
array_buf = await csv_file.arrayBuffer()
file_bytes = array_buf.to_bytes()
# 3. 封装为 BytesIO，供 pandas 使用
csv_stream = BytesIO(file_bytes)
try:
# 4. 解析 CSV（支持中文列名、逗号分隔等常见格式）
df = pd.read_csv(csv_stream)
rows_array = df.values.tolist()
print("✅ Successfully loaded CSV:")
print(f" Shape: {df.shape}")
print(f" Columns: {list(df.columns)}")
print(f" First 3 rows: {rows_array[:3]}")
except Exception as e:
print(f"❌ Error parsing CSV: {e}")
</py-script>
</body>
</html>⚠️ 关键注意事项
- 版本兼容性：示例使用 2023.05.1 版本（稳定可靠），新版本 API 可能有调整，请以 PyScript 官方文档 为准；
- 编码问题：若 CSV 含中文，建议保存为 UTF-8 编码；必要时可在 pd.read_csv() 中添加 encoding='utf-8' 参数；
- 大文件限制：浏览器内存限制下，不建议上传 >50MB 文件；如需处理大文件，应结合分块读取或服务端解析；
- 安全提示：所有解析均在用户本地完成，无数据上传至服务器，保障隐私安全。
通过以上方案，你已构建出一个轻量、安全、可扩展的前端 CSV 分析工具基础框架——后续可轻松接入图表渲染（如 plotly）、统计计算或导出功能。
