gd-web-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Organization Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,500 @@
+# @gdxx/web-core
+
+Vue 3 基座能力封装库，提供通用组件和工具函数。
+
+## 安装
+
+```bash
+pnpm add @gdxx/web-core
+```
+
+## 快速开始
+
+### 全量引入
+
+```ts
+import { createApp } from 'vue'
+import YourOrgCore from '@gdxx/web-core'
+import '@gdxx/web-core/style.css'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(YourOrgCore)
+app.mount('#app')
+```
+
+### 按需引入（推荐）
+
+本库完全支持 Tree-shaking，可以按需引入组件和工具函数，减小打包体积。
+
+#### 方式 1: 从主入口导入（推荐）
+
+```ts
+import { Echarts, STable, formatDate, useLoading } from '@gdxx/web-core'
+import '@gdxx/web-core/style.css'
+```
+
+#### 方式 2: 从子路径导入（更语义化）
+
+```ts
+// 仅导入组件
+import { Echarts, STable } from '@gdxx/web-core/components'
+
+// 仅导入工具函数
+import { formatDate, formatNumber } from '@gdxx/web-core/utils'
+
+// 仅导入 Hooks
+import { useLoading, useToggle } from '@gdxx/web-core/hooks'
+
+// 导入样式
+import '@gdxx/web-core/style.css'
+```
+
+#### Tree-shaking 原理
+
+现代打包工具（Vite、Webpack 5+、Rollup）会自动移除未使用的代码：
+
+```ts
+// 只会打包 formatDate 相关代码，其他工具函数不会被打包
+import { formatDate } from '@gdxx/web-core'
+```
+
+**工作条件**：
+- ✅ 使用 ES Module (`import`/`export`)
+- ✅ 打包工具开启生产模式
+- ✅ 使用命名导入（不是 `import *`）
+
+#### 打包体积对比
+
+| 导入方式 | 打包后体积（估算） |
+|---------|-----------------|
+| 全量导入 | ~200KB (gzip ~60KB) |
+| 按需导入单个组件 | ~20KB (gzip ~6KB) |
+| 按需导入单个工具函数 | ~2KB (gzip <1KB) |
+
+## 验证 Tree-shaking 效果
+
+### 使用 Rollup Plugin Visualizer
+
+```bash
+# 安装可视化插件
+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
+
+```bash
+# 开发时查看导入分析
+pnpm dev
+
+# 在浏览器控制台查看
+import { formatDate } from '@gdxx/web-core'
+// 只会加载 formatDate 相关模块
+```
+
+### 检查打包产物
+
+```bash
+# 构建生产版本
+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  (所有组件样式)
+```
+
+## 组件
+
+### Button 按钮
+
+```vue
+<template>
+  <Button type="primary" size="medium" @click="handleClick">
+    点击按钮
+  </Button>
+</template>
+
+<script setup lang="ts">
+import { Button } from '@gdxx/web-core'
+</script>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| type | `'primary' \| 'secondary' \| 'danger'` | `'primary'` | 按钮类型 |
+| size | `'small' \| 'medium' \| 'large'` | `'medium'` | 按钮尺寸 |
+| disabled | `boolean` | `false` | 是否禁用 |
+| loading | `boolean` | `false` | 是否加载中 |
+
+### Echarts 图表
+
+需要安装 `echarts` 依赖。
+
+```vue
+<template>
+  <Echarts :options="chartOptions" height="400px" @click="handleClick" />
+</template>
+
+<script setup lang="ts">
+import { Echarts } from '@gdxx/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 滚动容器
+
+自定义滚动条组件。
+
+```vue
+<template>
+  <ScrollContainer height="300px" direction="y">
+    <div>滚动内容...</div>
+  </ScrollContainer>
+</template>
+
+<script setup lang="ts">
+import { ScrollContainer } from '@gdxx/web-core'
+</script>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| height | `string \| number` | `'100%'` | 高度 |
+| maxHeight | `string \| number` | - | 最大高度 |
+| direction | `'x' \| 'y' \| 'both'` | `'y'` | 滚动方向 |
+
+### STable 表格
+
+需要安装 `@surely-vue/table` 和 `ant-design-vue` 依赖。
+
+```vue
+<template>
+  <STable :columns="columns" :data="loadData" />
+</template>
+
+<script setup lang="ts">
+import { STable } from '@gdxx/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>
+```
+
+## Hooks
+
+### useLoading
+
+```ts
+import { useLoading } from '@gdxx/web-core'
+
+const { loading, startLoading, stopLoading, withLoading } = useLoading()
+
+await withLoading(async () => {
+  await fetchData()
+})
+```
+
+### useToggle
+
+```ts
+import { useToggle } from '@gdxx/web-core'
+
+const { value, toggle, setTrue, setFalse } = useToggle(false)
+```
+
+## 工具函数
+
+### 日期格式化
+
+```ts
+import { formatDate, dateFormat } from '@gdxx/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'
+```
+
+### 数字处理
+
+```ts
+import { formatNumber, formatFileSize, toFixed, round } from '@gdxx/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 封装
+
+```ts
+import { storage, createStorage } from '@gdxx/web-core'
+
+storage.set('token', 'xxx', 3600000)  // 1小时后过期
+storage.get('token')
+
+const myStorage = createStorage('session', { prefix: 'myapp' })
+```
+
+### 防抖节流
+
+```ts
+import { debounce, throttle, createDebounce } from '@gdxx/web-core'
+
+// Promise 防抖
+await debounce('search', 300)
+
+// 节流函数
+const throttledFn = throttle(fn, 100)
+
+// 创建防抖函数
+const debouncedFn = createDebounce(fn, 300)
+```
+
+### URL 参数
+
+```ts
+import { useUrlParams, updateUrlParams } from '@gdxx/web-core'
+
+const params = useUrlParams()
+updateUrlParams({ page: '2' })
+```
+
+### DOM 操作
+
+```ts
+import { scrollView, setHtmlTitle, print } from '@gdxx/web-core'
+
+scrollView('element-id')
+setHtmlTitle('新标题')
+await print('#print-area')
+```
+
+### 加密
+
+```ts
+import { useRsa, useAes, disuseAes } from '@gdxx/web-core'
+
+const encrypted = await useRsa('data', publicKey)
+const aesEncrypted = await useAes('data', key)
+const decrypted = await disuseAes(aesEncrypted, key)
+```
+
+### 页面可见性
+
+```ts
+import { onVisibilityChange } from '@gdxx/web-core'
+
+const unsubscribe = onVisibilityChange((hidden) => {
+  console.log('页面隐藏:', hidden)
+})
+```
+
+### Excel 导入导出
+
+```ts
+import { importExcel, importExcelAll, exportJsonToExcel } from '@gdxx/web-core'
+
+// 导入
+const data = await importExcel(file)
+const allSheets = await importExcelAll(file)
+
+// 导出
+await exportJsonToExcel(['姓名', '年龄'], [['张三', 25]], '用户列表')
+```
+
+### 后端数据解析
+
+```ts
+import { rowSet, pageRowSet } from '@gdxx/web-core'
+
+const { colKey, data } = rowSet(result)
+const { colKey, data, total } = pageRowSet(pageResult)
+```
+
+## 常见问题
+
+### 为什么按需引入后打包体积还是很大？
+
+1. **检查样式文件**：CSS 是全量加载的，确保只在入口文件导入一次
+2. **检查导入方式**：避免使用 `import * as Core from '@gdxx/web-core'`
+3. **检查生产模式**：确保打包工具运行在生产模式 (`NODE_ENV=production`)
+4. **检查打包配置**：确认 Tree-shaking 已启用
+
+### 组件依赖的第三方库会被打包吗？
+
+不会。以下依赖被标记为 `external`，不会打包进库中：
+- `vue` (必需)
+- `vue-router` (可选)
+- `echarts` (按需)
+- `ant-design-vue` (按需)
+- `@surely-vue/table` (按需)
+
+用户需要在自己的项目中安装这些依赖。
+
+### 可以只安装部分依赖吗？
+
+可以。例如，如果不使用 `Echarts` 组件，无需安装 `echarts`：
+
+```bash
+# 最小安装
+pnpm add @gdxx/web-core vue
+
+# 使用 Echarts 组件
+pnpm add echarts
+
+# 使用 STable 组件
+pnpm add ant-design-vue @surely-vue/table
+```
+
+### TypeScript 类型定义支持按需引用吗？
+
+完全支持。所有类型定义都会正确推导：
+
+```ts
+import { formatDate } from '@gdxx/web-core'
+// formatDate 函数会有完整的类型提示
+
+import type { EchartsProps } from '@gdxx/web-core'
+// 可以单独导入类型
+```
+
+## 目录结构
+
+```
+src/
+├── components/
+│   ├── Button/
+│   ├── Echarts/
+│   ├── ScrollContainer/
+│   └── STable/
+├── hooks/
+│   ├── useLoading.ts
+│   └── useToggle.ts
+├── 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/](./docs/) 目录：
+
+- **快速开始**
+  - [安装指南](./docs/getting-started/installation.md)
+  - [快速上手](./docs/getting-started/quick-start.md)
+
+- **进阶指南**
+  - [按需引用](./docs/guides/tree-shaking.md) - Tree-shaking 优化
+  - [TypeScript 支持](./docs/guides/typescript.md)
+  - [最佳实践](./docs/guides/best-practices.md)
+
+- **发布和部署** ⭐
+  - [发布流程完整指南](./docs/deployment/publishing.md)
+  - [版本管理规范](./docs/deployment/versioning.md)
+  - [发布检查清单](./docs/deployment/checklist.md)
+  - [CI/CD 集成](./docs/deployment/ci-cd.md)
+
+- **开发指南**
+  - [开发环境搭建](./docs/development/setup.md)
+  - [贡献指南](./docs/development/contributing.md)
+
+## 🚀 开发
+
+### 快速开始
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动开发服务器（带 playground 预览）
+pnpm dev
+
+# 运行测试
+pnpm test
+
+# 构建库
+pnpm build
+
+# 发布到 npm
+pnpm release:patch  # 或 minor、major
+```
+
+### 发布流程
+
+详细的发布指南请查看 [发布流程文档](./docs/deployment/publishing.md)
+
+**快速发布**：
+```bash
+# 1. 确保测试通过
+pnpm test:run
+
+# 2. 构建
+pnpm build
+
+# 3. 发布（自动更新版本号）
+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)
+
+# 4. 推送 tag
+git push origin main --tags
+```
+
+### 目录说明
+
+- `src/` - 库源代码
+- `playground/` - 开发预览应用
+- `test/` - 测试文件
+- `dist/` - 构建输出
+
+## License
+
+MIT

package/dist/components/Echarts/Echarts.vue.d.ts

@@ -0,0 +1,23 @@
+import { ECharts, EChartsOption } from 'echarts';
+export interface EchartsProps {
+    options: EChartsOption;
+    width?: string;
+    height?: string;
+    theme?: string;
+}
+declare const _default: import('vue').DefineComponent<EchartsProps, {
+    chartInstance: import('vue').ShallowRef<ECharts | null, ECharts | null>;
+    resize: () => void;
+    setOption: (option: EChartsOption) => void;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    click: (params: unknown) => any;
+}, string, import('vue').PublicProps, Readonly<EchartsProps> & Readonly<{
+    onClick?: ((params: unknown) => any) | undefined;
+}>, {
+    width: string;
+    height: string;
+    theme: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    chartRef: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/components/Echarts/index.d.ts

@@ -0,0 +1,3 @@
+import { default as Echarts } from './Echarts.vue';
+export { Echarts };
+export type { EchartsProps } from './Echarts.vue';

package/dist/components/STable/STable.vue.d.ts

@@ -0,0 +1,102 @@
+export interface ColumnItem {
+    title?: string;
+    dataIndex?: string;
+    key?: string;
+    align?: string;
+    width?: number;
+    wch?: number;
+    children?: ColumnItem[];
+    noExp?: boolean;
+    autoHeight?: boolean;
+    expRender?: (params: RenderParams) => unknown;
+    customRender?: (params: RenderParams) => unknown;
+    customRenderExport?: (params: RenderParams) => unknown;
+}
+export interface RenderParams {
+    column: ColumnItem;
+    index: number;
+    record: Record<string, unknown>;
+    text: unknown;
+    value: unknown;
+}
+export interface STableProps {
+    columns: ColumnItem[];
+    data: (params: DataParams) => Promise<DataResult>;
+    pageNum?: number;
+    pageSize?: number;
+    showPagination?: string | boolean;
+    pageSizeOptions?: string[];
+    rowAutoHeight?: boolean;
+    exportName?: string | number;
+    showIndex?: boolean;
+    enableContextExport?: boolean;
+    rowKey?: string | ((record: Record<string, unknown>) => string);
+}
+export interface DataParams {
+    pageNo: number;
+    pageSize: number;
+    export?: boolean;
+    sortField?: string;
+    sortOrder?: string;
+    [key: string]: unknown;
+}
+export interface DataResult {
+    data?: Record<string, unknown>[];
+    rows?: Record<string, unknown>[];
+    total?: number;
+    totalCount?: number;
+}
+interface Pagination {
+    current: number;
+    pageSize: number;
+}
+interface Sorter {
+    field?: string;
+    order?: string;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: any;
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<STableProps, {
+    _columns: ColumnItem[];
+    getEl: () => Promise<HTMLElement>;
+    getData: () => Record<string, unknown>[];
+    getPageData: (num?: number) => Record<string, unknown>[];
+    refresh: (bool?: boolean) => void;
+    loadData: (pagination?: Partial<Pagination & {
+        export?: boolean;
+    }>, filters?: Record<string, unknown>, sorter?: Sorter) => Promise<DataResult | undefined>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    change: (pagination: Pagination, filters: unknown, sorter: Sorter, ...rest: unknown[]) => any;
+    "update:pageNum": (value: number) => any;
+    "update:pageSize": (value: number) => any;
+    "export-page": () => any;
+    "export-all": () => any;
+}, string, import('vue').PublicProps, Readonly<STableProps> & Readonly<{
+    onChange?: ((pagination: Pagination, filters: unknown, sorter: Sorter, ...rest: unknown[]) => any) | undefined;
+    "onUpdate:pageNum"?: ((value: number) => any) | undefined;
+    "onUpdate:pageSize"?: ((value: number) => any) | undefined;
+    "onExport-page"?: (() => any) | undefined;
+    "onExport-all"?: (() => any) | undefined;
+}>, {
+    pageSize: number;
+    rowKey: string | ((record: Record<string, unknown>) => string);
+    pageNum: number;
+    showPagination: string | boolean;
+    pageSizeOptions: string[];
+    rowAutoHeight: boolean;
+    exportName: string | number;
+    showIndex: boolean;
+    enableContextExport: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/STable/index.d.ts

@@ -0,0 +1,3 @@
+import { default as STable } from './STable.vue';
+export { STable };
+export type { STableProps, ColumnItem, DataParams, DataResult } from './STable.vue';

package/dist/components/ScrollContainer/ScrollContainer.vue.d.ts

@@ -0,0 +1,42 @@
+export interface ScrollContainerProps {
+    height?: string | number;
+    maxHeight?: string | number;
+    direction?: 'x' | 'y' | 'both';
+    wrapClass?: string;
+    viewClass?: string;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {
+        wrapRef: HTMLDivElement;
+        viewRef: HTMLDivElement;
+    };
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<ScrollContainerProps, {
+    update: () => void;
+    scrollTo: (options: ScrollToOptions) => void;
+    setScrollTop: (top: number) => void;
+    setScrollLeft: (left: number) => void;
+    getScrollWrap: () => HTMLDivElement | null;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<ScrollContainerProps> & Readonly<{}>, {
+    height: string | number;
+    maxHeight: string | number;
+    direction: "x" | "y" | "both";
+    wrapClass: string;
+    viewClass: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    wrapRef: HTMLDivElement;
+    viewRef: HTMLDivElement;
+}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/ScrollContainer/index.d.ts

@@ -0,0 +1,3 @@
+import { default as ScrollContainer } from './ScrollContainer.vue';
+export { ScrollContainer };
+export type { ScrollContainerProps } from './ScrollContainer.vue';

package/dist/components/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Echarts';
+export * from './ScrollContainer';
+export * from './STable';