252 lines
9.1 KiB
Markdown
252 lines
9.1 KiB
Markdown
# JSON Viewer 桌面版 JSON 阅读器（Tauri + Vue 3 + TypeScript）
|
||
|
||
一个跨平台桌面端 JSON 阅读 / 编辑工具，基于 **Tauri 2 + Vue 3 + TypeScript** 实现，专注于「**一眼看懂 JSON 结构，快速定位并编辑需要的字段**」。
|
||
|
||
### 界面预览
|
||
|
||
|
||
|
||
- 左侧：树形结构视图，按对象 / 数组分层展示，并显示子节点数量
|
||
- 中间：原始文本视图，支持格式化 / 压缩、缩进风格切换（2 空格 / 4 空格 / Tab）
|
||
- 右侧：节点详情区（选中树节点后展示更多信息）
|
||
- 顶部工具栏：保存、格式化、压缩、缩进、主题切换、搜索（支持 Ctrl+F）
|
||
- 底部状态栏：当前文件状态（未打开 / 已修改）与 JSON 是否有效
|
||
|
||
### 主要特性
|
||
|
||
- 加载本地 JSON 文件（文件对话框 / 拖拽到窗口 / 右键“打开方式”）
|
||
- 树形结构查看 JSON，支持折叠/展开、子项计数提示，自动滚动到当前选中节点
|
||
- JSON 格式化 / 压缩，一键切换缩进风格（2 空格 / 4 空格 / Tab），并记住用户偏好
|
||
- 节点值编辑（字符串、数字、布尔、null），实时校验并给出报错位置
|
||
- 原始 JSON 文本同步编辑与实时校验（错误行列直接高亮）
|
||
- 关键字搜索（键名/值），支持大小写敏感、上一条 / 下一条结果导航
|
||
- 支持保存 / 另存为 JSON 文件，避免破坏原始数据
|
||
|
||
### 快速上手（作为使用者）
|
||
|
||
1. 启动应用后，点击窗口左上方的 **“打开”** 按钮，或直接将 `.json` 文件拖拽进窗口
|
||
2. 在左侧树中展开需要关注的节点，或按 `Ctrl+F` 搜索键名 / 值快速定位
|
||
3. 双击节点值即可就地编辑；右侧原始文本和底部状态栏会实时反馈 JSON 是否有效
|
||
4. 编辑完成后，点击工具栏的 **“保存”** 或 **“另存为”** 持久化到本地文件
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- Node.js ≥ 18
|
||
- Rust 工具链（stable，支持 Tauri 2）
|
||
- 平台支持：
|
||
- Windows 10 及以上
|
||
- macOS 10.15 及以上
|
||
- 主流 Linux（如 Ubuntu、Fedora）
|
||
|
||
> 如首次使用 Tauri，可参考官方文档安装系统依赖（如 Windows 上的 MSVC、WebView2 等）。
|
||
|
||
---
|
||
|
||
## 安装依赖
|
||
|
||
在项目根目录（`E:\Workspace\jsonview` 或你的克隆目录）执行：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
这会安装前端依赖（Vue / Vite / Pinia / Tauri CLI 等）。
|
||
|
||
---
|
||
|
||
## 开发模式运行（本地调试）
|
||
|
||
开发模式会同时启动：
|
||
|
||
- Vite 前端开发服务器（热更新）
|
||
- Tauri 桌面应用（加载 Vite 开发页面）
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
npm run tauri:dev
|
||
```
|
||
|
||
运行成功后会自动弹出桌面应用窗口，你可以：
|
||
|
||
- 点击顶部工具栏的 **“打开”** 选择本地 `.json` 文件
|
||
- 或直接将 `.json` 文件从资源管理器 / Finder 中拖拽到窗口中
|
||
|
||
> **重要**：必须用 `npm run tauri:dev` 或打包后的 exe 运行，**不要**用 `npm run dev`（仅 Web 预览，无“打开方式”、拖放、快捷键等桌面功能）。工具栏右侧 **“诊断”** 按钮可查看启动参数，用于排查“打开方式”是否传入路径。
|
||
|
||
### 开发时常用操作
|
||
|
||
- 修改 `src/` 下的前端代码会自动热更新（Tauri 窗口会自动刷新内容）
|
||
- 修改 `src-tauri/` 下的 Rust 代码后，Tauri 会重新编译并重启应用
|
||
|
||
---
|
||
|
||
## 打包构建（生成安装包 / 可执行文件）
|
||
|
||
项目已经在 `src-tauri/tauri.conf.json` 中配置了应用名称、窗口大小和打包目标。
|
||
|
||
### 1. 仅构建前端（生成静态资源）
|
||
|
||
如果你只想构建 Web 端静态资源（调试用），可以执行：
|
||
|
||
```bash
|
||
npm run build:web
|
||
```
|
||
|
||
这会在 `dist/` 目录下生成前端打包产物。
|
||
|
||
### 2. 构建桌面应用安装包（推荐）
|
||
|
||
标准的 Tauri 打包流程为：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
该命令会执行：
|
||
|
||
1. `vite build`：构建前端，输出到 `dist/`
|
||
2. `tauri build`：使用 `dist/` 中的前端资源，打包为桌面应用
|
||
|
||
打包完成后，生成的可执行文件 / 安装包会出现在：
|
||
|
||
- **Windows**：`src-tauri/target/release/jsonview.exe`（可直接运行），以及 **NSIS 安装包** `src-tauri/target/release/bundle/nsis/JSON Viewer_0.1.0_x64-setup.exe`
|
||
- macOS：`src-tauri/target/release/bundle/dmg/` 或 `.app`
|
||
- Linux：`src-tauri/target/release/bundle/deb/`、`AppImage` 等
|
||
|
||
> **Windows 安装包说明**：构建时会先运行 `scripts/ensure-nsis-windows.ps1`，在 `src-tauri/target/.tauri/` 下预下载 NSIS 工具（含重试与较长超时），避免 Tauri 内置下载超时。安装包会生成在 `bundle/nsis/` 目录下。
|
||
|
||
> 如果你只想单独运行 Tauri 构建（已经手动执行过 `vite build`），也可以：
|
||
>
|
||
> ```bash
|
||
> npm run tauri:build
|
||
> ```
|
||
|
||
---
|
||
|
||
## 功能一览与使用说明
|
||
|
||
- **打开 JSON 文件**
|
||
- 点击工具栏“打开”按钮，选择 `.json` 文件
|
||
- 或将 `.json` 文件拖拽到窗口，即可自动加载
|
||
- **树形浏览与折叠**
|
||
- 左侧树视图展示 JSON 对象/数组结构
|
||
- 点击 `+/-` 折叠/展开节点，折叠时会显示子节点数量 `(X 项)`
|
||
- **编辑节点值**
|
||
- 对字符串/数字/布尔/null 节点：双击值进入编辑模式
|
||
- 输入合法 JSON 片段（如 `"hello"`、`123`、`true`、`null`），回车或失焦保存
|
||
- 非法输入会提示错误并回退
|
||
- **原始文本编辑与验证**
|
||
- 右侧“原始文本视图”可以直接编辑完整 JSON 文本
|
||
- 实时使用 JSON 解析校验，错误信息会显示在编辑器头部与状态栏
|
||
- **缩进设置**
|
||
- 工具栏提供：`2 空格 / 4 空格 / Tab`
|
||
- 切换后会即时重新格式化当前 JSON 显示
|
||
- 用户选择会保存在本地，下一次启动沿用
|
||
- **搜索与导航**
|
||
- 工具栏右侧输入搜索词并回车，可在键名和字符串值中匹配
|
||
- “上一条 / 下一条”在所有匹配项之间循环跳转
|
||
- 每次跳转会自动展开相关节点并滚动到可视区域
|
||
|
||
---
|
||
|
||
## 目录结构（简要）
|
||
|
||
```text
|
||
jsonview/
|
||
package.json # 项目配置与脚本
|
||
tsconfig.json # TypeScript 配置
|
||
vite.config.ts # Vite 配置
|
||
index.html # 前端入口 HTML
|
||
|
||
src/
|
||
main.ts # Vue 入口
|
||
App.vue # 页面布局与 Tauri 拖拽处理
|
||
styles.css # 全局样式
|
||
|
||
types/json.ts # JsonValue / JsonNode 等类型定义
|
||
services/
|
||
jsonParser.ts # JSON 解析与验证、树构建
|
||
formatter.ts # 缩进与格式化
|
||
searchService.ts # 搜索逻辑
|
||
fileService.ts # 调用 Tauri 命令操作文件
|
||
store/
|
||
useJsonStore.ts # Pinia Store：文件状态、缩进、验证、搜索等
|
||
components/
|
||
Toolbar.vue
|
||
SearchPanel.vue
|
||
JsonTreeView.vue
|
||
JsonNode.vue
|
||
JsonEditorPanel.vue
|
||
StatusBar.vue
|
||
|
||
src-tauri/
|
||
Cargo.toml # Rust / Tauri 依赖配置
|
||
build.rs # Tauri 构建脚本
|
||
tauri.conf.json # Tauri 应用配置（窗口、打包等）
|
||
src/
|
||
main.rs # Tauri 入口，open/save JSON 命令实现
|
||
```
|
||
|
||
---
|
||
|
||
## 创建 GitHub 仓库并启用自动构建
|
||
|
||
### 1. 初始化 Git（若尚未初始化）
|
||
|
||
```bash
|
||
git init
|
||
git add .
|
||
git commit -m "Initial commit"
|
||
```
|
||
|
||
### 2. 用 GitHub CLI 创建仓库并推送（推荐）
|
||
|
||
1. 安装 [GitHub CLI](https://cli.github.com/) 并登录：`gh auth login`
|
||
2. 在项目根目录执行（仓库会创建在当前登录的 GitHub 账号下）：
|
||
|
||
```powershell
|
||
# Windows PowerShell（公开仓库，仓库名 jsonview）
|
||
.\scripts\create-github-repo.ps1 -RepoName jsonview -IsPrivate $false
|
||
|
||
# 或私有仓库
|
||
.\scripts\create-github-repo.ps1 -RepoName jsonview -IsPrivate $true
|
||
```
|
||
|
||
Linux/macOS 可用：
|
||
|
||
```bash
|
||
chmod +x scripts/create-github-repo.sh
|
||
./scripts/create-github-repo.sh jsonview # 公开
|
||
./scripts/create-github-repo.sh jsonview private # 私有
|
||
```
|
||
|
||
若不用脚本，可手动执行：
|
||
|
||
```bash
|
||
gh repo create jsonview --public --source . --remote origin --push --description "JSON Viewer - 跨平台 JSON 桌面阅读/编辑工具 (Tauri + Vue 3)"
|
||
```
|
||
|
||
### 3. 启用自动构建（GitHub Actions）
|
||
|
||
- 仓库已包含 `.github/workflows/build.yml`，会在以下情况自动构建并生成 **Draft Release**：
|
||
- 推送到 `main` 或 `release` 分支
|
||
- 或在 Actions 页手动触发（workflow_dispatch）
|
||
- 构建产物：Windows (x64)、macOS (Intel + Apple Silicon)、Linux (x64) 的安装包/可执行文件，会上传到该次运行的 Release 草稿中。
|
||
- 若提示权限不足：在仓库 **Settings → Actions → General** 中，将 **Workflow permissions** 设为 **Read and write permissions**。
|
||
|
||
### 4. 发布版本
|
||
|
||
- 每次自动构建会创建带版本号的 Tag（如 `v0.1.0`）和 Draft Release。
|
||
- 在 **Releases** 页打开对应草稿，检查附件后点击 **Publish release** 即可对外发布。
|
||
|
||
---
|
||
|
||
## 开发建议
|
||
|
||
- 如果你要扩展功能（如：添加/删除节点、虚拟滚动、大文件优化等），推荐从 `src/store/useJsonStore.ts` 和 `src/components/JsonNode.vue` 入手。
|
||
- 如要调整 UI 风格，可以在 `styles.css` 中统一修改样式，或引入你熟悉的 Vue UI 组件库（如 Naive UI、Element Plus 等）。
|
||
|