json-viewer-element

<json-viewer> Element

简体中文 | English

一个轻量、现代的 JSON 可视化与交互 Web 组件

功能特性

• Web 组件：原生，无框架依赖
• 主题：支持明暗模式
• 盒装：可选边框与内边距
• 可复制：一键复制 JSON
• 排序：支持键排序
• 展开深度：可控初始展开层级
• 自定义复制按钮：slot 插槽支持
• 类型高亮：多种类型高亮
• 自定义事件：支持 copy/toggle 事件监听

使用方法

安装

npm install json-viewer-element

引入

作为模块

import 'json-viewer-element'

UMD (CDN)

<script src="https://unpkg.com/json-viewer-element/dist/json-viewer-element.umd.js"></script>

基本用法

手动绑定 value：

<json-viewer id="viewer" boxed copyable sort expand-depth="2" theme="dark"></json-viewer>
<script>
  document.getElementById('viewer').value = { hello: "world", arr: [1,2,3] };
</script>

直接在标签上绑定 value：

<json-viewer value='{"hello":"world","arr":[1,2,3]}' boxed copyable sort expand-depth="2" theme="dark"></json-viewer>

在 Vue 框架中使用：

Vue 2/3 选项式 API：

<template>
  <json-viewer :value="JSON.stringify(json)" boxed copyable sort expand-depth="2" theme="dark"></json-viewer>
</template>

<script>
export default {
  data() {
    return {
      json: { hello: "world", arr: [1,2,3] },
    }
  },
}
</script>

Vue 3 组合式 API：

<script lang="ts" setup>
import { ref } from 'vue'
const json = ref({ hello: "world", arr: [1,2,3] })
</script>

<template>
  <json-viewer :value="JSON.stringify(json)" boxed copyable sort expand-depth="2" theme="dark"></json-viewer>
</template>

跳过组件解析

为了让 Vue 知道某些元素应被视为自定义元素并跳过组件解析，我们可以指定 compilerOptions.isCustomElement 选项。

// vite.config.js
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 将所有带短横线的标签名都视为自定义元素
          isCustomElement: tag => tag.includes('-')
        }
      }
    }),
    vueJsx({
      // 将所有带短横线的标签名都视为自定义元素
      isCustomElement: tag => tag.includes('-')
    }),
  ]
}

如果你在 Vue 中使用 ESLint，可能需要配置忽略自定义元素：

// eslint.config.js
export default {
  rules: {
    'vue/component-name-in-template-casing': [
      'warn',
      'PascalCase',
      {
        registeredComponentsOnly: false,
        ignores: ['/^icon-/', 'json-viewer'],
      },
    ],
  },
}

属性

在 Vue 等框架中使用时，value 和 copyable 属性的值需要转成字符串传入。

属性	类型	默认值	说明
value	object / array / string / number / boolean	null	JSON 数据
expand-depth	number	1	初始展开层级
copyable	boolean / CopyableOptions	false	启用复制按钮或自定义复制按钮配置（见下表）
sort	boolean	false	是否对对象键排序
boxed	boolean	false	是否显示边框和内边距
theme	'light' / 'dark'	'light'	主题
parse	boolean	true	字符串值是否自动解析为 JSON

CopyableOptions

属性	类型	默认值	说明
copyText	string	Copy	复制按钮显示的文本
copiedText	string	Copied	复制成功后显示的文本
timeout	number	2000	显示 copiedText 的时长 (ms)
align	'left' / 'right'	right	复制按钮对齐方式

事件

事件	说明
copy-success	复制成功后触发
copy-error	复制失败后触发
toggle	节点折叠/展开时触发

插槽

自定义复制按钮：

<json-viewer copyable>
  <button slot="copy-button">复制 JSON</button>
</json-viewer>

License

MIT

Copyright (c) 2025-present Lruihao