jsoncrack-embed

将 JSONCrack 的 React 组件打包为一个自包含的 IIFE 脚本，无需任何构建工具或框架依赖，只需引入一个 JS 文件和一个 CSS 文件，即可在任意网页中嵌入交互式 JSON 树形/图可视化查看器。

特性

• 零依赖嵌入 — 产出一个 ~4 MB 的 jsoncrack-embed.js（IIFE）+ 一个 CSS 文件，<script> 标签即可使用
• 交互式可视化 — 基于 reaflow 的节点图渲染，支持缩放、平移、节点展开/折叠
• 多主题 — 内置深色 / 浅色主题，运行时一键切换
• 多方向布局 — 支持 LEFT / RIGHT / DOWN / UP 四种布局方向
• 命令式 API — 通过 createEmbed 返回的实例对象动态更新数据、主题、视口等
• JSONC 支持 — 底层使用 jsonc-parser，支持带注释的 JSON

快速开始

使用构建产物

将 dist/ 下的两个文件引入你的 HTML：

<link rel="stylesheet" href="jsoncrack-embed.css" />
<script src="jsoncrack-embed.js"></script>

<div id="viewer" style="width: 100%; height: 500px;"></div>

<script>
  const viewer = JSONCrackEmbed.createEmbed(document.getElementById('viewer'), {
    data: JSON.stringify({ hello: "world", items: [1, 2, 3] }, null, 2),
    theme: "dark",
    direction: "RIGHT",
    showControls: false,
    showGrid: false,
  });
</script>

开发 / 构建

前置条件： 本项目通过路径别名引用外部 jsoncrack-react 源码（见 vite.config.ts 和 tsconfig.json 中的 paths 配置）。构建前需确保该源码目录可用，并按需调整路径。

# 安装依赖
npm install

# 启动开发服务器（热更新 demo 页面）
npm run dev

# 生产构建 → 输出到 dist/
npm run build

# 预览生产构建
npm run preview

API

JSONCrackEmbed.createEmbed(container, options?)

在指定 DOM 容器中创建 JSON 查看器实例，返回 EmbedAPI 对象。

options

字段	类型	默认值	说明
data	string	"{}"	JSON 字符串
theme	"dark" | "light"	"dark"	主题
direction	"LEFT" | "RIGHT" | "DOWN" | "UP"	"RIGHT"	布局方向
showControls	boolean	false	是否显示内置工具栏
showGrid	boolean	false	是否显示背景网格

实例方法

interface EmbedAPI {
  setData(data: string): void;              // 更新 JSON 数据
  setTheme(theme: "dark" | "light"): void;  // 切换主题
  setDirection(dir: "LEFT" | "RIGHT" | "DOWN" | "UP"): void;  // 切换布局方向
  zoomIn(): void;          // 放大
  zoomOut(): void;         // 缩小
  centerView(): void;      // 居中视图
  focusFirstNode(): void;  // 聚焦根节点
  destroy(): void;         // 卸载并销毁实例
}

示例：

viewer.setData(JSON.stringify({ updated: true }));
viewer.setTheme("light");
viewer.zoomIn();
viewer.centerView();
viewer.destroy(); // 清理

项目结构

jsoncrack-embed/
├── src/
│   ├── main.ts              # SDK 核心：createEmbed 实现
│   └── declarations.d.ts    # 外部模块类型声明
├── dist/
│   ├── jsoncrack-embed.js   # 构建产物（IIFE，~4 MB）
│   └── jsoncrack-embed.css  # 构建产物 CSS
├── index.html               # Demo 页面
├── vite.config.ts           # Vite 构建配置（library 模式）
├── tsconfig.json            # TypeScript 配置
└── package.json

技术栈

• React 19 + TypeScript
• reaflow — 节点图渲染引擎
• react-zoomable-ui — 缩放与平移
• jsonc-parser — 支持注释的 JSON 解析
• Vite 6 — 构建工具（library 模式，IIFE 输出）

License

MIT