企业官网建设流程全解析

visual-json 是一款开源的可视化 JSON 编辑器组件库，其@visual-json/vue包让 Vue 3 开发者只需 3 行代码，就能把带树形导航、表单编辑、搜索、撤销重做的 JSON 编辑器嵌入自己的项目。它支持 Schema 感知、CSS 变量主题定制，还能一键对比两份 JSON 的差异，非常适合用来构建配置中心、接口调试、数据可视化等产品功能。

为什么要用可视化 JSON 编辑器？

让终端用户直接编辑 JSON 文本，体验往往很糟糕：

• 容易写错语法：少一个逗号、引号不配对，整段数据直接作废
• 结构不可见：几百行的 JSON，新人根本找不到想改的字段
• 改动没保障：改错了没有对比，上线前才发现删了关键配置

visual-json 的 Vue 组件把 JSON 拆成树形结构 + 表单字段两种视图，用户在树上定位节点、在表单里改值，编辑器负责保证结果始终是合法 JSON。配合内置的撤销/重做（undo/redo）、搜索定位和 Diff 视图，编辑体验接近 IDE。

安装步骤：一条命令完成

npm install @visual-json/vue @visual-json/core

⚠️ 环境要求：Vue3.3+；@visual-json/core提供底层树模型、操作与 Schema 类型，需与 UI 包一起安装。

各包分工可参考 packages/@visual-json/vue/README.md 和根目录的 README.md。

快速上手：3 行代码嵌入 JsonEditor

JsonEditor是"全家桶"组件——内置树形侧边栏、表单编辑器、搜索栏和键盘导航。在任意 Vue 组件里这样写即可：

<script setup> import { ref } from "vue"; import { JsonEditor } from "@visual-json/vue"; const value = ref({ hello: "world" }); </script> <template> <JsonEditor :value="value" @change="value = $event" /> </template>

仅 3 行核心代码，就得到一个双视图编辑器：左侧树可展开/折叠、拖拽排序、右键操作；右侧表单按字段类型渲染输入控件；窄屏（<500px）自动切换为 Tree / Form 标签页布局。响应式逻辑见 JsonEditor.vue。

常用 Props 速查表

数据变更时组件触发change事件并回传新的JsonValue，与value搭配即可实现完整的受控编辑。

Schema 感知：自动校验与表单提示

传入schema后，编辑器会按 Schema 渲染输入控件：

• enum字段自动变成下拉选择框
• 字段的description显示为表单提示文案
• 必填项、类型约束一目了然

visual-json 的 core 包还提供resolveSchema，可按文件名自动识别常见配置（如package.json、docker-compose.yml、.gitlab-ci.yml等）的 Schema。官方 Vue 示例就展示了这套用法——监听数据与文件名变化后异步解析 Schema 并传给编辑器：

resolveSchema(val as JsonValue, fname) .then((s) => { if (!cancelled) schema.value = s; });

完整示例代码见 use-json-document.ts，resolveSchema的实现位于 schema.ts。

DiffView：改动一目了然

修改前的原始数据与当前数据放在一起对比，新增、删除、修改的内容都会着色高亮：

<DiffView :original-json="original" :current-json="current" />

官方示例的编辑器工具栏就提供了 Tree / Raw / Diff 三种视图切换，用户随时能核对"改了什么"，实现参考 Editor.vue。

主题定制：用 CSS 变量适配你的产品风格

所有组件的颜色、字体、间距都通过--vj-*CSS 变量驱动，通过styleprop 传入即可换肤：

<JsonEditor :value="data" :style="{ '--vj-bg': '#ffffff', '--vj-text': '#111111', '--vj-accent': '#2563eb', '--vj-font': "'Fira Code', monospace", }" @change="data = $event" />

内置的深色主题默认值（背景、选中态、错误色、字符串/数字/布尔值的着色等）集中在 theme.ts，覆盖任意变量即可与你的产品风格保持一致。

进阶：用底层组件拼装自己的编辑器

如果JsonEditor的布局不合心意，可以用提供器VisualJson自由组合组件——它通过provide/inject统一管理树状态、选区、撤销历史和搜索：

<script setup> import { VisualJson, TreeView, FormView, SearchBar } from "@visual-json/vue"; </script> <template> <VisualJson :value="json" @change="onJsonChange"> <SearchBar /> <TreeView /> <FormView /> </VisualJson> </template>

可用组件包括TreeView（树形视图，支持拖拽与键盘导航）、FormView（Schema 感知表单）、DiffView、SearchBar（支持 Cmd/Ctrl+F）、Breadcrumbs（路径面包屑）、ContextMenu，组件清单与导出见 index.ts。

需要更细的控制时，useStudio()可以从任意子组件拿到完整状态与操作：

import { useStudio } from "@visual-json/vue"; const { state, actions } = useStudio(); // actions.undo() / actions.expandAll() / actions.nextSearchMatch() ...

例如用state.canUndo禁用撤销按钮，用actions.undo()触发作废——这是构建自定义工具栏的关键 API。

参考官方 Vue 示例项目

仓库内置了一个完整的 Vue 3 示例应用（Vite + UnoCSS + TypeScript），演示了文件拖拽导入、粘贴 JSON、原始文本视图、下载/复制等实战能力，建议直接阅读：

• 示例入口与编辑器工具栏：examples/vue/src/components/Editor.vue
• 数据管理与 Schema 解析：examples/vue/src/composables/use-json-document.ts
• 示例依赖配置：examples/vue/package.json

总结

visual-json 用"Schema 感知 + 可嵌入 + 可扩展"三个特性，把 JSON 编辑这件枯燥易错的事变成了一眼可见、随手可改的体验。对于 Vue 3 项目而言，3 行代码就能拥有一个专业级可视化 JSON 编辑器，值得加进你的技术工具箱。🚀