ethanfly/php-manager-website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5cba471932
php-manager-website/README-jsonview.md

9.1 KiB
Raw Blame History

JSON Viewer 桌面版 JSON 阅读器（Tauri + Vue 3 + TypeScript）

一个跨平台桌面端 JSON 阅读 / 编辑工具，基于 Tauri 2 + Vue 3 + TypeScript 实现，专注于「一眼看懂 JSON 结构，快速定位并编辑需要的字段」。

界面预览

JSON Viewer 界面预览

  • 左侧：树形结构视图，按对象 / 数组分层展示，并显示子节点数量
  • 中间：原始文本视图，支持格式化 / 压缩、缩进风格切换（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 或你的克隆目录）执行：

npm install

这会安装前端依赖（Vue / Vite / Pinia / Tauri CLI 等）。

开发模式运行（本地调试）

开发模式会同时启动：

  • Vite 前端开发服务器（热更新）
  • Tauri 桌面应用（加载 Vite 开发页面）

在项目根目录执行：

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 端静态资源（调试用），可以执行：

npm run build:web

这会在 dist/ 目录下生成前端打包产物。

2. 构建桌面应用安装包（推荐）

标准的 Tauri 打包流程为：

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），也可以：

npm run tauri:build

功能一览与使用说明

  • 打开 JSON 文件
    • 点击工具栏“打开”按钮，选择 .json 文件
    • 或将 .json 文件拖拽到窗口，即可自动加载
  • 树形浏览与折叠
    • 左侧树视图展示 JSON 对象/数组结构
    • 点击 +/- 折叠/展开节点，折叠时会显示子节点数量 (X 项)
  • 编辑节点值
    • 对字符串/数字/布尔/null 节点：双击值进入编辑模式
    • 输入合法 JSON 片段（如 "hello"、123、true、null），回车或失焦保存
    • 非法输入会提示错误并回退
  • 原始文本编辑与验证
    • 右侧“原始文本视图”可以直接编辑完整 JSON 文本
    • 实时使用 JSON 解析校验，错误信息会显示在编辑器头部与状态栏
  • 缩进设置
    • 工具栏提供：2 空格 / 4 空格 / Tab
    • 切换后会即时重新格式化当前 JSON 显示
    • 用户选择会保存在本地，下一次启动沿用
  • 搜索与导航
    • 工具栏右侧输入搜索词并回车，可在键名和字符串值中匹配
    • “上一条 / 下一条”在所有匹配项之间循环跳转
    • 每次跳转会自动展开相关节点并滚动到可视区域

目录结构（简要）

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（若尚未初始化）

git init
git add .
git commit -m "Initial commit"

2. 用 GitHub CLI 创建仓库并推送（推荐）

  1. 安装 GitHub CLI 并登录：gh auth login
  2. 在项目根目录执行（仓库会创建在当前登录的 GitHub 账号下）：
# Windows PowerShell（公开仓库，仓库名 jsonview）
.\scripts\create-github-repo.ps1 -RepoName jsonview -IsPrivate $false

# 或私有仓库
.\scripts\create-github-repo.ps1 -RepoName jsonview -IsPrivate $true

Linux/macOS 可用：

chmod +x scripts/create-github-repo.sh
./scripts/create-github-repo.sh jsonview        # 公开
./scripts/create-github-repo.sh jsonview private  # 私有

若不用脚本，可手动执行：

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 等）。