json-ui

用途

json-ui 是一个 JSON 到 HTML 的报告渲染器，支持 React 组件、双语 i18n 以及命令行工具。它适合用于根据 JSON 报告定义生成 HTML 报告，也支持在 React 中嵌入使用。

主要能力

组件目录：提供约 38 种组件类型，分为以下几类：
- 布局：Report、Section、Grid、Card
- 论文信息：PaperHeader、AuthorList、Abstract、TagList
- 内容：ContributionList、MethodOverview、Highlight、KeyPoint、CodeBlock、Prose、Callout
- 富内容：Image、Figure、Formula、DefinitionList、Theorem、Algorithm、ResultsTable
- 数据展示：Metric、MetricsGrid、Table
- 交互：LinkButton、LinkGroup
- 品牌：BrandHeader、BrandFooter
三层渲染：Zod Schemas（类型定义与校验）、HTML Renderer（静态 HTML 字符串，用于 CLI 渲染）、React Components（React 元素，用于嵌入）。
i18n 系统：I18nString 类型同时接受纯字符串和 { en, zh } 双语对象，向后兼容。HTML 输出使用双 span 并通过 CSS 控制显示；React 使用 I18nText 组件或 resolveI18nStr()。提供固定右上角的语言切换按钮（EN | 中文），通过 localStorage 持久化选择。
CLI 工具：可将 JSON 报告渲染为 HTML 文件。

使用方式

报告以节点树形式描述，例如：

{
  "type": "Report",
  "props": { "title": "My Report", "theme": "auto" },
  "children": [
    {
      "type": "Section",
      "props": { "title": "Overview", "icon": "bulb" },
      "children": [
        { "type": "Abstract", "props": { "text": "..." } }
      ]
    }
  ]
}

数据流：JSON 文件 → CLI 解析 → renderNode() 递归 → HTML 字符串 → 写入文件 → 打开浏览器。

构建与 CLI 命令：

# 构建（通过 tsup 输出 ESM + DTS）
cd packages/json-ui && pnpm build

# 将报告渲染为 HTML
node dist/cli.js render example-report-rich.json

# 带选项
node dist/cli.js render report.json -o output.html --no-open

添加新组件需同时更新三层：catalog.ts（Zod schema）、cli.ts（renderNode() switch 分支）、components/index.tsx（React 组件）。

适用场景

根据 JSON 定义生成 HTML 报告
在 React 应用中嵌入报告组件
需要中英双语展示的报告
论文信息、方法概览、结果表格等结构化内容展示

限制与注意事项

图片处理：不要在 <img> 标签上使用 crossorigin="anonymous"，因为 arxiv.org 等站点不发送 CORS 头，会导致图片被阻止加载；应保留 referrerpolicy="no-referrer"。
常见错误：将 i18n 对象直接传给 JSX 会报类型错误，需用 <I18nText value={...} /> 包裹；对 i18n 值调用字符串方法需先做类型守卫。
修改 schema 后需同步更新 catalog、cli、components 三个文件，否则构建可能因类型错误失败。
文档完整性：使用前建议阅读本地源文件（catalog.ts、cli.ts、components/index.tsx），若读取失败则本地文档不完整。
版本：1.0.0，最后更新 2026-01-29。

（注：关于收费、价格、平台支持等具体信息，资料中暂未提供。）

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项