excel-vis 0.1.1

A lightweight web application for Excel data management and visualization, powered by FastAPI + Tailwind CSS + Alpine.js

Excel-Vis

一个让你用浏览器轻松管理 Excel 数据的工具。

Excel-Vis 是一个基于 Python 的轻量级 Web 应用，它把你电脑上的 Excel 文件变成一个可以在浏览器中查看、编辑、新增、删除数据的网页系统。你不需要安装任何数据库，Excel 文件本身就是你的"数据库"。

简单来说：安装 → 一行命令启动 → 打开浏览器就能管理你的 Excel 数据。

---

功能特性

• 浏览器查看 Excel 数据：以美观的网页表格展示 Excel 文件内容，支持手机访问
• 在线增删改查：直接在网页上新增、编辑、删除记录，修改会自动保存到 Excel 文件
• 单击查看详情：点击任意一行，弹窗展示该行所有字段的完整信息
• Excel 导入/导出：支持上传 Excel 文件导入数据（追加或覆盖），也可导出当前数据
• 支持任意结构：不限定 Excel 的列名和列数，系统自动识别表头
• 自定义列显示：可以选择显示哪些列、修改列的显示名称、拖拽调整列顺序
• 布局设置：支持紧凑/标准/宽松三种表格密度，可设置每页显示行数
• 双渠道编辑：网页端修改自动写入 Excel；你也可以直接编辑 Excel 文件，刷新网页即可看到最新内容
• 一键启动：安装后一条命令即可运行，自动打开浏览器
• 零配置：无需数据库，无需复杂配置，开箱即用

---

安装指南

环境要求

• Python 版本：3.9 或更高版本
• 操作系统：Windows、macOS、Linux 均可
• 浏览器：Chrome、Firefox、Edge、Safari 等现代浏览器

第一步：检查 Python 版本

打开你的终端（Windows 用户打开"命令提示符"或"PowerShell"），输入：

python --version

如果显示 Python 3.9.x 或更高版本，说明环境已就绪。如果版本过低或未安装，请前往 python.org 下载安装。

第二步：安装 excel-vis

pip install excel-vis

等待安装完成即可。这会自动安装所有需要的依赖包。

第三步：验证安装

excel-vis --help

如果看到帮助信息输出，说明安装成功。

---

使用教程

快速启动（最简单的方式）

在终端中进入你想存放 Excel 文件的目录，然后运行：

excel-vis

系统会自动：

1. 在当前目录创建一个带有示例数据的 data.xlsx 文件（如果不存在的话）
2. 启动 Web 服务
3. 自动打开浏览器展示数据

指定已有的 Excel 文件

如果你已经有一个 Excel 文件，可以直接指定它：

excel-vis --file /path/to/your/file.xlsx

Windows 示例：

excel-vis --file C:\Users\张三\Documents\员工信息.xlsx

macOS/Linux 示例：

excel-vis --file ~/Documents/员工信息.xlsx

更多启动参数

# 指定端口号（默认 8000）
excel-vis --port 8080

# 指定监听地址（让局域网内其他电脑也能访问）
excel-vis --host 0.0.0.0 --port 8080

# 不自动打开浏览器
excel-vis --no-browser

# 完整示例：指定文件、端口、不打开浏览器
excel-vis --file mydata.xlsx --port 9000 --no-browser

在 Python 代码中使用

如果你是开发者，也可以在 Python 代码中直接调用：

import excel_vis

# 最简单的方式：一行代码启动
excel_vis.run()

# 自定义参数启动
excel_vis.run(
    file="mydata.xlsx",   # Excel 文件路径
    host="0.0.0.0",       # 监听地址
    port=8080,            # 端口号
    open_browser=True     # 是否自动打开浏览器
)

# 只创建 FastAPI 应用实例（用于集成到自己的项目中）
app = excel_vis.create_app(file="mydata.xlsx")

通过模块方式运行

python -m excel_vis --file data.xlsx --port 8000

---

网页操作指南

启动后打开浏览器，你会看到一个数据管理界面。以下是各功能的使用方法：

查看数据

• 页面加载后自动显示 Excel 中的所有数据
• 表格支持分页浏览，底部可切换页码
• 在手机上访问时，表格可左右滑动

查看某行详情

• 单击表格中的任意一行，会弹出一个窗口，展示该行所有字段的名称和值
• 在详情窗口中可以直接点击"编辑"进入编辑模式

新增记录

1. 点击顶部工具栏的 "新增" 按钮
2. 在弹出的表单中填写各字段（ID 会自动生成，不需要手动填）
3. 点击 "保存"，数据将写入 Excel 文件并刷新表格

编辑记录

1. 点击某行右侧的 编辑图标（笔形图标）
2. 修改需要更改的字段
3. 点击 "保存"，修改将同步到 Excel 文件

删除记录

1. 点击某行右侧的 删除图标（垃圾桶图标）
2. 系统会弹出确认对话框，防止误操作
3. 确认后该行将从 Excel 文件中永久删除

导入 Excel 文件

1. 点击顶部工具栏的 "导入" 按钮
2. 选择一个 .xlsx 或 .xls 文件
3. 选择导入模式：
   • 追加模式：保留原有数据，把新文件中的数据添加到末尾
   • 覆盖模式：删除所有原有数据，完全用新文件替换
4. 点击 "开始导入"

导出 Excel 文件

• 点击顶部工具栏的 "导出" 按钮
• 浏览器会自动下载一个 Excel 文件，文件名格式为 数据导出_日期_时间.xlsx

刷新数据

• 如果你在外部直接编辑了 Excel 文件，点击 "刷新" 按钮即可加载最新数据

自定义列设置

1. 点击顶部工具栏的 "列设置" 按钮
2. 在右侧弹出的面板中可以：
   • 勾选/取消勾选：控制哪些列在表格中显示
   • 修改显示名称：把英文列名改成中文等自定义名称
   • 拖拽排序：按住左侧拖拽图标调整列的显示顺序
   • 切换表格密度：紧凑/标准/宽松
   • 设置每页行数：10/20/50/100
3. 点击 "应用" 保存设置
4. 这些设置保存在浏览器中，下次打开页面会自动恢复

---

API 接口说明

Excel-Vis 提供标准的 RESTful API，可以被其他程序调用。启动服务后，API 基础地址为 http://localhost:8000（端口号取决于你的设置）。

获取所有数据

GET /api/data

响应示例：

{
  "code": 200,
  "data": [
    {"id": 1, "姓名": "张三", "年龄": 28, "邮箱": "[e-mail]", "部门": "技术部"},
    {"id": 2, "姓名": "李芳", "年龄": 32, "邮箱": "[e-mail]", "部门": "市场部"}
  ]
}

获取单条记录

GET /api/data/{id}

示例： GET /api/data/1

响应：

{
  "code": 200,
  "data": {"id": 1, "姓名": "张三", "年龄": 28, "邮箱": "[e-mail]", "部门": "技术部"}
}

新增记录

POST /api/data
Content-Type: application/json

{"姓名": "王五", "年龄": 25, "邮箱": "[e-mail]", "部门": "产品部"}

响应：

{"code": 200, "message": "ok", "id": 3}

更新记录

PUT /api/data/{id}
Content-Type: application/json

{"姓名": "王五改", "年龄": 26}

响应：

{"code": 200, "message": "ok"}

删除记录

DELETE /api/data/{id}

响应：

{"code": 200, "message": "ok"}

获取列信息

GET /api/columns

响应：

{"code": 200, "columns": ["id", "姓名", "年龄", "邮箱", "部门", "入职日期"]}

导入 Excel

POST /api/import
Content-Type: multipart/form-data

file: <Excel 文件>
mode: append 或 overwrite

响应：

{"code": 200, "message": "追加导入成功，共导入 5 条记录"}

导出 Excel

GET /api/export

返回 .xlsx 文件下载。

---

依赖项清单

依赖包	最低版本	用途
fastapi	0.100.0	Web 框架，提供 API 服务
uvicorn[standard]	0.20.0	ASGI 服务器，运行 FastAPI 应用
openpyxl	3.1.0	读写 Excel (.xlsx) 文件
typer	0.9.0	命令行界面（CLI）框架
python-multipart	0.0.6	处理文件上传
jinja2	3.1.0	HTML 模板渲染

开发依赖（可选）：

依赖包	用途
pytest	运行测试
httpx	API 测试客户端
pytest-asyncio	异步测试支持

---

常见问题

Q: 启动后浏览器没有自动打开怎么办？

手动打开浏览器，访问终端中显示的地址（默认为 http://127.0.0.1:8000）。

Q: 提示端口被占用怎么办？

换一个端口号启动：

excel-vis --port 9000

Q: 我的 Excel 文件没有 id 列怎么办？

没有关系！系统会自动添加 id 列并为每行生成唯一编号，不会影响你原有的数据。

Q: 我直接用 Excel 软件修改了文件，网页上怎么看到新数据？

点击网页上的 "刷新" 按钮，即可重新加载 Excel 文件中的最新内容。

Q: 可以多人同时使用吗？

本工具设计为单用户或小团队轻量使用。由于 Excel 文件不支持并发写入，建议同一时间只有一个人进行编辑操作。多人同时查看数据是没有问题的。

Q: 支持哪些格式的 Excel 文件？

支持 .xlsx（推荐）和 .xls 格式。导出时统一使用 .xlsx 格式。

Q: 数据量有限制吗？

建议 Excel 文件不超过 10,000 行 × 30 列。超过此规模可能会导致加载变慢。

Q: 如何让局域网内其他电脑访问？

启动时指定 host 为 0.0.0.0：

excel-vis --host 0.0.0.0 --port 8000

然后其他电脑在浏览器中输入 http://你的IP地址:8000 即可访问。

Q: 上传文件有大小限制吗？

默认限制为 10MB。如果需要导入更大的文件，建议先精简数据或分批导入。

---

免责声明

使用风险

1. 数据安全：本软件直接读写 Excel 文件，操作不可撤销。删除或覆盖导入等操作会永久修改你的 Excel 文件。强烈建议在使用前备份重要数据。

2. 非生产环境工具：本软件为轻量级数据管理工具，适用于个人使用、小团队内部管理、数据演示等场景。不建议用于生产环境、金融交易、医疗记录等对数据安全性和可靠性有严格要求的场景。

3. 并发限制：本软件使用 Excel 文件作为数据存储，不具备数据库级别的并发控制能力。多人同时写入可能导致数据冲突或丢失。

4. 网络安全：本软件默认不包含用户认证和权限控制。如果部署在公网环境中，任何能够访问该地址的人都可以查看和修改你的数据。请勿在不受信任的网络环境中使用，或自行配置防火墙和访问控制。

5. 文件完整性：如果 Excel 文件在使用过程中被外部程序（如 Excel 软件）同时打开并编辑，可能导致文件损坏或数据不一致。

责任归属

• 本软件按"现状"提供，作者不对因使用本软件而导致的任何数据丢失、损坏、泄露或其他损失承担责任。
• 用户应自行评估使用本软件的风险，并采取必要的数据备份和安全防护措施。
• 用户应确保其使用本软件的方式符合所在地区的法律法规。

使用建议

• 使用前务必备份 Excel 文件
• 定期通过"导出"功能下载数据备份
• 避免在公网环境中不加防护地部署
• 避免多人同时进行写入操作
• 重要数据请使用专业数据库系统管理

---

贡献指南

欢迎贡献代码、报告问题或提出建议！

1. Fork 本项目
2. 创建你的功能分支：git checkout -b feature/my-feature
3. 提交更改：git commit -m "Add my feature"
4. 推送到分支：git push origin feature/my-feature
5. 创建 Pull Request

开发环境搭建

# 克隆项目
git clone https://github.com/your-repo/excel-vis.git
cd excel-vis

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

---

许可证信息

本项目采用 MIT 许可证 开源。

你可以自由地使用、复制、修改、合并、发布、分发本软件，但需要在软件的所有副本中包含版权声明和许可证声明。

详见 LICENSE 文件。