jtxxzx-web-components-library

基于 Vue 3 + Vite 的 Web 组件库，提供高质量、易用的基础组件。

📦 安装

npm install jtxxzx-web-components-library

⚠️ 重要依赖要求

必须安装 Ant Design Vue v3！

npm install ant-design-vue@^3.2.20 @ant-design/icons-vue@^7.0.0

不兼容 v4：本组件库基于 Ant Design Vue v3 开发，v4 的 CSS-in-JS 机制会导致样式失效。

✨ 特性

• 🚀 开箱即用 - 高质量基础组件
• 🎨 基于 Ant Design Vue v3 - 样式统一美观
• 🔧 按需引入 - Tree Shaking 支持
• 🌐 TypeScript - 完整类型定义
• 📱 响应式 - 适配各种屏幕

📚 组件列表

基础组件

| 组件名 | 说明 | 版本 | | -------------- | ----------------- | ---- | | ToolTipView | 工具提示组件 | ✅ | | UploadBatch | 批量上传组件 | ✅ | | MarkdownViewer | Markdown 渲染组件 | ✅ | | CodeBlock | 代码块组件 | ✅ | | Html2pdfRender | HTML 转 PDF 组件 | ✅ |

🔨 使用方式

1. 全局注册

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import WebComponentsLibrary from 'jtxxzx-web-components-library'
import 'jtxxzx-web-components-library/style.css'

// ⚠️ 必须引入 Ant Design Vue v3 样式
import 'ant-design-vue/dist/antd.css'

const app = createApp(App)
app.use(WebComponentsLibrary)
app.mount('#app')

2. 按需引入

<template>
  <ToolTipView content="提示信息">
    <a-button>Hover Me</a-button>
  </ToolTipView>

  <UploadBatch v-model:file-list="fileList" :upload-api-method="uploadApi" />
</template>

<script setup>
import { ToolTipView, UploadBatch } from 'jtxxzx-web-components-library'
import { ref } from 'vue'

const fileList = ref([])
const uploadApi = async ({ file }) => {
  // 实现上传逻辑
  return { data: { url: '...' } }
}
</script>

🎨 核心组件

ToolTipView - 工具提示

<template>
  <ToolTipView content="提示信息" placement="top" trigger="hover">
    <a-button>悬停显示提示</a-button>
  </ToolTipView>
</template>

API： content (string) | placement (top/bottom/left/right) | trigger (hover/click)

UploadBatch - 批量上传

支持拖拽、粘贴截图的批量上传组件。

<template>
  <UploadBatch
    v-model:file-list="fileList"
    :upload-api-method="uploadApi"
    allow-file-type="image"
  />
</template>

<script setup>
import { ref } from 'vue'
const fileList = ref([])

const uploadApi = async ({ file }) => {
  const formData = new FormData()
  formData.append('file', file)
  const res = await fetch('/api/upload', { method: 'POST', body: formData })
  return await res.json()
}
</script>

API： file-list (array) | upload-api-method (function) | allow-file-type (image/all/custom)

MarkdownViewer - Markdown 渲染

<template>
  <MarkdownViewer :source="markdownContent" />
</template>

<script setup>
const markdownContent = ref('# Hello World\n\n内容...')
</script>

CodeBlock - 代码块

支持语法高亮和复制。

<template>
  <CodeBlock language="javascript" :code="codeString" show-copy />
</template>

<script setup>
const codeString = `function hello() {\n  console.log('Hello')\n}`
</script>

Html2pdfRender - HTML 转 PDF

<template>
  <div ref="contentRef">
    <h1>要转换的内容</h1>
  </div>
  <a-button @click="downloadPdf">下载 PDF</a-button>
</template>

<script setup>
import { ref } from 'vue'
import { Html2pdfRender } from 'jtxxzx-web-components-library'

const contentRef = ref(null)
const pdfRender = new Html2pdfRender()

const downloadPdf = async () => {
  await pdfRender.download({
    element: contentRef.value,
    filename: 'document.pdf',
  })
}
</script>

⚙️ API 文档

详细文档请参考：docs 目录。

🎯 兼容性

浏览器支持

• ✅ Chrome / Firefox / Safari / Edge (最新版)

依赖版本

• Vue >= 3.2.0
• Ant Design Vue = ^3.2.20 (必须 v3，不兼容 v4)
• @ant-design/icons-vue >= 6.0.0

⚠️ 注意事项

1. 样式引入顺序

// ✅ 正确：先引入 antd v3 样式
import 'ant-design-vue/dist/antd.css'
import 'jtxxzx-web-components-library/style.css'

// ❌ 错误：使用 v4 的 reset.css
// import 'ant-design-vue/dist/reset.css'  // 会导致样式失效！

2. 版本锁定

建议在 package.json 中锁定版本：

{
  "dependencies": {
    "jtxxzx-web-components-library": "^1.0.4",
    "ant-design-vue": "^3.2.20"
  }
}

3. TypeScript 支持

库已包含完整类型声明，可直接使用。

4. 关键 API 变更

UploadBatch 组件已适配 v3/v4 兼容写法：

• ✅ 使用 <Upload.Dragger> (推荐)
• ❌ 废弃 <UploadDragger> (v4 不支持)

🐛 问题反馈

如遇问题或有改进建议，欢迎：

• 📝 提交 Issue
• 💬 发起 Discussion
• 📧 联系作者

📄 License

MIT License

版本：1.0.4
作者：xiao weiming
最后更新：2026-03-13