Metadata-Version: 2.4
Name: excel-vis
Version: 0.1.2
Summary: A lightweight web application for Excel data management and visualization, powered by FastAPI + Tailwind CSS + Alpine.js
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: excel,fastapi,web,visualization,data-management
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.20.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: typer>=0.9.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: jinja2>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# 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"），输入：

```bash
python --version
```

如果显示 `Python 3.9.x` 或更高版本，说明环境已就绪。如果版本过低或未安装，请前往 [python.org](https://www.python.org/downloads/) 下载安装。

### 第二步：安装 excel-vis

```bash
pip install excel-vis
```

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

### 第三步：验证安装

```bash
excel-vis --help
```

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

---

## 使用教程

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

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

```bash
excel-vis
```

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

### 指定已有的 Excel 文件

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

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

**Windows 示例：**
```bash
excel-vis --file C:\Users\张三\Documents\员工信息.xlsx
```

**macOS/Linux 示例：**
```bash
excel-vis --file ~/Documents/员工信息.xlsx
```

### 更多启动参数

```bash
# 指定端口号（默认 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 代码中直接调用：

```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")
```

### 通过模块方式运行

```bash
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
```

**响应示例：**
```json
{
  "code": 200,
  "data": [
    {"id": 1, "姓名": "张三", "年龄": 28, "邮箱": "zh@ex.com", "部门": "技术部"},
    {"id": 2, "姓名": "李芳", "年龄": 32, "邮箱": "li@ex.com", "部门": "市场部"}
  ]
}
```

### 获取单条记录

```
GET /api/data/{id}
```

**示例：** `GET /api/data/1`

**响应：**
```json
{
  "code": 200,
  "data": {"id": 1, "姓名": "张三", "年龄": 28, "邮箱": "zh@ex.com", "部门": "技术部"}
}
```

### 新增记录

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

{"姓名": "王五", "年龄": 25, "邮箱": "wang@ex.com", "部门": "产品部"}
```

**响应：**
```json
{"code": 200, "message": "ok", "id": 3}
```

### 更新记录

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

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

**响应：**
```json
{"code": 200, "message": "ok"}
```

### 删除记录

```
DELETE /api/data/{id}
```

**响应：**
```json
{"code": 200, "message": "ok"}
```

### 获取列信息

```
GET /api/columns
```

**响应：**
```json
{"code": 200, "columns": ["id", "姓名", "年龄", "邮箱", "部门", "入职日期"]}
```

### 导入 Excel

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

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

**响应：**
```json
{"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: 提示端口被占用怎么办？

换一个端口号启动：

```bash
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`：

```bash
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

### 开发环境搭建

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

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

# 运行测试
pytest tests/ -v
```

---

## 许可证信息

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

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

详见 [LICENSE](./LICENSE) 文件。



