gd-web-core

Vue 3 基座能力封装库，提供通用组件和工具函数。

安装

pnpm add gd-web-core

快速开始

全量引入

import { createApp } from 'vue'
import YourOrgCore from 'gd-web-core'
import 'gd-web-core/style.css'
import App from './App.vue'

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

按需引入（推荐）

本库完全支持 Tree-shaking，可以按需引入组件和工具函数，减小打包体积。

方式 1: 从主入口导入（推荐）

import { Echarts, STable, formatDate } from 'gd-web-core'
import 'gd-web-core/style.css'

方式 2: 从子路径导入（更语义化）

// 仅导入组件
import { Echarts, STable } from 'gd-web-core/components'

// 仅导入工具函数
import { formatDate, formatNumber } from 'gd-web-core/utils'

// 导入样式
import 'gd-web-core/style.css'

Tree-shaking 原理

现代打包工具（Vite、Webpack 5+、Rollup）会自动移除未使用的代码：

// 只会打包 formatDate 相关代码，其他工具函数不会被打包
import { formatDate } from 'gd-web-core'

工作条件：

• ✅ 使用 ES Module (import/export)
• ✅ 打包工具开启生产模式
• ✅ 使用命名导入（不是 import *）

打包体积对比

| 导入方式 | 打包后体积（估算） | |---------|-----------------| | 全量导入 | ~200KB (gzip ~60KB) | | 按需导入单个组件 | ~20KB (gzip ~6KB) | | 按需导入单个工具函数 | ~2KB (gzip <1KB) |

验证 Tree-shaking 效果

使用 Rollup Plugin Visualizer

# 安装可视化插件
pnpm add -D rollup-plugin-visualizer

# 在 vite.config.ts 中添加
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  plugins: [
    visualizer({ open: true })
  ]
})

# 构建后会自动打开分析报告
pnpm build

使用 Vite Build Analyzer

# 开发时查看导入分析
pnpm dev

# 在浏览器控制台查看
import { formatDate } from 'gd-web-core'
// 只会加载 formatDate 相关模块

检查打包产物

# 构建生产版本
pnpm build

# 查看产物大小
ls -lh dist/

# 输出示例
# index.js        150KB  (ES Module, 支持 tree-shaking)
# index.umd.cjs   180KB  (UMD, 不支持 tree-shaking)
# index.d.ts       50KB  (TypeScript 类型定义)
# style.css        20KB  (所有组件样式)

组件

Echarts 图表

需要安装 echarts 依赖。

<template>
  <Echarts :options="chartOptions" height="400px" @click="handleClick" />
</template>

<script setup lang="ts">
import { Echarts } from 'gd-web-core'

const chartOptions = {
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
  yAxis: { type: 'value' },
  series: [{ data: [120, 200, 150], type: 'bar' }]
}
</script>

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | options | EChartsOption | 必填 | ECharts 配置项 | | width | string | '100%' | 宽度 | | height | string | '300px' | 高度 | | theme | string | '' | 主题 |

ScrollContainer 滚动容器

自定义滚动条组件。

<template>
  <ScrollContainer height="300px" direction="y">
    <div>滚动内容...</div>
  </ScrollContainer>
</template>

<script setup lang="ts">
import { ScrollContainer } from 'gd-web-core'
</script>

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | height | string \| number | '100%' | 高度 | | maxHeight | string \| number | - | 最大高度 | | direction | 'x' \| 'y' \| 'both' | 'y' | 滚动方向 |

STable 表格

需要安装 @surely-vue/table 和 ant-design-vue 依赖。

<template>
  <STable :columns="columns" :data="loadData" />
</template>

<script setup lang="ts">
import { STable } from 'gd-web-core'

const columns = [
  { title: '姓名', dataIndex: 'name' },
  { title: '年龄', dataIndex: 'age' }
]

const loadData = async (params) => {
  const res = await fetchData(params)
  return { data: res.list, total: res.total }
}
</script>

工具函数

日期格式化

import { formatDate, dateFormat } from 'gd-web-core'

formatDate(new Date())                      // '2026-02-02 10:30:00'
formatDate('2026-01-01', 'YYYY/MM/DD')      // '2026/01/01'
dateFormat('YY-mm-dd HH:MM:SS', new Date()) // '2026-02-02 10:30:00'

数字处理

import { formatNumber, formatFileSize, toFixed, round } from 'gd-web-core'

formatNumber(1234567.89)     // '1,234,567.89'
formatFileSize(1048576)      // '1 MB'
toFixed(3.1415926, 2)        // 3.14 (不四舍五入)
round(0.7 * 3, 2)            // 2.1 (四舍五入，精度安全)

Storage 封装

import { storage, createStorage } from 'gd-web-core'

storage.set('token', 'xxx', 3600000)  // 1小时后过期
storage.get('token')

const myStorage = createStorage('session', { prefix: 'myapp' })

防抖节流

import { debounce, throttle, createDebounce } from 'gd-web-core'

// Promise 防抖
await debounce('search', 300)

// 节流函数
const throttledFn = throttle(fn, 100)

// 创建防抖函数
const debouncedFn = createDebounce(fn, 300)

URL 参数

import { useUrlParams, updateUrlParams } from 'gd-web-core'

const params = useUrlParams()
updateUrlParams({ page: '2' })

DOM 操作

import { scrollView, setHtmlTitle, print } from 'gd-web-core'

scrollView('element-id')
setHtmlTitle('新标题')
await print('#print-area')

加密

import { useRsa, useAes, disuseAes } from 'gd-web-core'

const encrypted = await useRsa('data', publicKey)
const aesEncrypted = await useAes('data', key)
const decrypted = await disuseAes(aesEncrypted, key)

页面可见性

import { onVisibilityChange } from 'gd-web-core'

const unsubscribe = onVisibilityChange((hidden) => {
  console.log('页面隐藏:', hidden)
})

Excel 导入导出

import { importExcel, importExcelAll, exportJsonToExcel } from 'gd-web-core'

// 导入
const data = await importExcel(file)
const allSheets = await importExcelAll(file)

// 导出
await exportJsonToExcel(['姓名', '年龄'], [['张三', 25]], '用户列表')

后端数据解析

import { rowSet, pageRowSet } from 'gd-web-core'

const { colKey, data } = rowSet(result)
const { colKey, data, total } = pageRowSet(pageResult)

常见问题

为什么按需引入后打包体积还是很大？

1. 检查样式文件：CSS 是全量加载的，确保只在入口文件导入一次
2. 检查导入方式：避免使用 import * as Core from 'gd-web-core'
3. 检查生产模式：确保打包工具运行在生产模式 (NODE_ENV=production)
4. 检查打包配置：确认 Tree-shaking 已启用

组件依赖的第三方库会被打包吗？

不会。以下依赖被标记为 external，不会打包进库中：

• vue (必需)
• vue-router (可选)
• echarts (按需)
• ant-design-vue (按需)
• @surely-vue/table (按需)

用户需要在自己的项目中安装这些依赖。

可以只安装部分依赖吗？

可以。例如，如果不使用 Echarts 组件，无需安装 echarts：

# 最小安装
pnpm add gd-web-core vue

# 使用 Echarts 组件
pnpm add echarts

# 使用 STable 组件
pnpm add ant-design-vue @surely-vue/table

TypeScript 类型定义支持按需引用吗？

完全支持。所有类型定义都会正确推导：

import { formatDate } from 'gd-web-core'
// formatDate 函数会有完整的类型提示

import type { EchartsProps } from 'gd-web-core'
// 可以单独导入类型

目录结构

src/
├── components/
│   ├── Echarts/
│   ├── ScrollContainer/
│   └── STable/
├── utils/
│   ├── format.ts
│   ├── storage.ts
│   ├── loadRemote.ts
│   ├── dom.ts
│   ├── url.ts
│   ├── number.ts
│   ├── async.ts
│   ├── crypto.ts
│   ├── visibility.ts
│   ├── rowSet.ts
│   └── xlsx.ts
├── assets/
└── index.ts

📚 文档

完整文档请查看 docs/ 目录：

• 快速开始

  • 安装指南
  • 快速上手

• 进阶指南

  • 按需引用 - Tree-shaking 优化
  • TypeScript 支持
  • 最佳实践

• 发布和部署 ⭐

  • 发布流程完整指南
  • 版本管理规范
  • 发布检查清单
  • CI/CD 集成

• 开发指南

  • 开发环境搭建
  • 贡献指南

🚀 开发

快速开始

# 安装依赖
pnpm install

# 启动开发服务器（带 playground 预览）
pnpm dev

# 构建库
pnpm build

# 发布到 npm
pnpm release:patch  # 或 minor、major

发布流程

详细的发布指南请查看 发布流程文档

快速发布：

# 1. 构建
pnpm build

# 2. 发布（自动更新版本号）
pnpm release:patch   # Bug 修复 (0.0.1 -> 0.0.2)
pnpm release:minor   # 新功能 (0.0.2 -> 0.1.0)
pnpm release:major   # 破坏性变更 (0.1.0 -> 1.0.0)

# 3. 推送 tag
git push origin main --tags

目录说明

• src/ - 库源代码
• playground/ - 开发预览应用
• dist/ - 构建输出

License

MIT