yx-web-sdk

一个基于 Vue 3 + TypeScript 的轻量级组件库

✨ 特性

• 🚀 基于 Vue 3 + TypeScript 构建
• 📦 支持 ES Module 和 UMD 格式
• 🌲 支持按需加载（Tree Shaking）
• 💪 完整的 TypeScript 类型定义
• 🎨 支持自动导入组件和样式
• 📖 提供 VitePress 文档

📦 安装

# 使用 npm 安装
npm install yx-web-sdk

# 或使用 pnpm
pnpm add yx-web-sdk

# 或使用 yarn
yarn add yx-web-sdk

🚀 快速开始

开发环境（使用源码）

1. 在yx-web-sdk项目中使用 npm link，创建一个符号链接
2. 在你的项目使用 npm link yx-web-sdk

在开发组件库或本地调试时，使用 development 入口直接引用源码：

import { createApp } from 'vue'
// 开发环境：直接使用源码，支持热更新
import yxWebSdk from 'yx-web-sdk/development'
import App from './App.vue'

const app = createApp(App)
// 注册组件库
app.use(yxWebSdk)
app.mount('#app')

正式环境（使用打包产物）

在生产环境或正式项目中，使用主入口引用打包后的代码：

import { createApp } from 'vue'
// 正式环境：使用打包后的代码
import yxWebSdk from 'yx-web-sdk'
// 引入全量样式
import 'yx-web-sdk/style.css'
import App from './App.vue'

const app = createApp(App)
// 注册组件库
app.use(yxWebSdk)
app.mount('#app')

📖 使用方式

方式一：完整引入

适合快速开发和原型设计，一次性引入所有组件：

import { createApp } from 'vue'
// 正式环境使用打包产物
import yxWebSdk from 'yx-web-sdk'
// 引入全量样式（包含所有组件样式）
import 'yx-web-sdk/style.css'
import App from './App.vue'

const app = createApp(App)
// 注册所有组件
app.use(yxWebSdk)
app.mount('#app')

开发环境完整引入：

import { createApp } from 'vue'
// 开发环境使用源码
import yxWebSdk from 'yx-web-sdk/development'
// 引入全局样式
import 'yx-web-sdk/global.css'
import App from './App.vue'

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

方式二：按需引入（推荐）✨

按需引入可以减少打包体积，只引入使用的组件：

从主入口按需引入（支持 Tree Shaking）

// 正式环境：从主入口引入，支持 Tree Shaking
import { Input } from 'yx-web-sdk'
// 引入全局样式（包含 CSS 变量等基础样式）
import 'yx-web-sdk/global.css'
// 引入组件样式
import 'yx-web-sdk/input/style.css'

在 Vue 3 的 <script setup> 中使用：

<script setup>
// 正式环境：按需引入组件
import { Input } from 'yx-web-sdk'
// 引入全局样式
import 'yx-web-sdk/global.css'
// 引入组件样式
import 'yx-web-sdk/input/style.css'
</script>

<template>
  <Input placeholder="请输入内容" />
</template>

直接引入单个组件

// 正式环境：直接引入单个组件
import Input from 'yx-web-sdk/input'
// 引入全局样式
import 'yx-web-sdk/global.css'
// 引入组件样式
import 'yx-web-sdk/input/style.css'

开发环境按需引入：

// 开发环境：使用 development 入口
import yxWebSdk from 'yx-web-sdk/development'
import 'yx-web-sdk/global.css'

💡 提示：

• 按需引入时，使用 'yx-web-sdk/global.css' 引入全局样式（包含 CSS 变量等基础样式）
• 使用 'yx-web-sdk/style.css' 引入全量样式（包含所有组件样式）
• 按需引入时推荐使用 global.css，避免样式重复

方式三：自动按需引入（最优雅）🎯

这是最推荐的方式，像 Element Plus 一样，无需手动导入组件和样式！

安装依赖

npm install -D unplugin-vue-components

配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { YxWebSDKResolver } from 'yx-web-sdk'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [
        YxWebSDKResolver({
          importStyle: true, // 自动导入样式
          prefix: 'Yx', // 组件前缀，默认为 'Yx'
        }),
      ],
    }),
  ],
})

使用方式

配置完成后，可以直接在模板中使用组件，无需任何导入语句！

<template>
  <!-- 组件和样式会自动导入 -->
  <YxInput placeholder="请输入内容" />
</template>

<!-- 无需 script setup，组件和样式会自动导入 -->

高级配置

YxWebSDKResolver({
  importStyle: true, // 是否自动导入样式，默认: true
  prefix: 'Yx', // 组件前缀，默认: 'Yx'
  lib: 'yx-web-sdk', // 库名，默认: 'yx-web-sdk'
})

📋 组件列表

• Input - 输入框组件

更多组件正在开发中...

🛠️ 开发

环境要求

• Node.js >= 18
• npm / pnpm / yarn

开发命令

# 安装依赖
npm install

# 启动开发环境（使用本地源码，端口 3000）
npm run dev

# 启动 Demo 应用（使用打包产物，端口 4000）
npm run dev:examples

# 构建组件库
npm run build

# 构建组件库 + 预览 Demo 应用
npm run preview

# 启动文档
npm run docs:dev

# 运行测试
npm test

# 代码检查
npm run lint

# 代码格式化
npm run format

项目结构

yx-web-sdk/
├── src/                    # 组件库源码
│   ├── components/         # 组件目录
│   │   ├── input/         # Input 组件
│   │   └── index.ts       # 组件导出
│   ├── resolver/          # 自动导入解析器
│   ├── plugin/            # Vite 插件
│   ├── styles/            # 全局样式
│   ├── stores/            # 状态管理
│   ├── utils/             # 工具函数
│   └── index.ts           # 主入口
├── test/                  # 开发环境测试
│   ├── App.vue            # 测试应用
│   └── vite.config.ts     # 开发环境配置
├── examples/              # Demo 应用
│   ├── App.vue            # Demo 应用
│   └── vite.config.ts     # Demo 应用配置
├── dist/                  # 构建产物
└── docs/                  # 文档

开发环境说明

• npm run dev - 开发环境，端口 3000，使用 test/ 文件夹，引用本地源码（yx-web-sdk/development），支持热更新
• npm run dev:examples - Demo 应用，端口 4000，使用 examples/ 文件夹，引用打包产物（yx-web-sdk）
• npm run preview - 先构建再启动 Demo 应用，模拟真实使用场景

📦 构建产物结构

dist/
├── style.css                    # 全量样式
├── global.css                   # 全局样式（CSS 变量等）
├── yx-web-sdk.es.js             # ES Module 主入口
├── yx-web-sdk.umd.js            # UMD 主入口
├── index.d.ts                   # 主入口类型定义
├── input/                       # Input 组件独立目录
│   ├── index.es.js              # Input 组件 JS
│   └── style.css                # Input 组件样式
└── components/                  # TypeScript 类型定义
    └── input/
        └── index.d.ts           # Input 类型定义

🌲 按需加载原理

Tree Shaking（JS 按需加载）

组件库支持多种导入方式，都支持 Tree Shaking：

// 方式1: 从主入口导入（推荐用于多个组件）
import { Input } from 'yx-web-sdk'

// 方式2: 按需导入单个组件（推荐用于少量组件）
import Input from 'yx-web-sdk/input'

// 方式3: 自动导入（最优雅，无需手动导入）
<YxInput /> <!-- 自动导入组件和样式 -->

打包工具（Vite/Webpack）会通过 Tree Shaking 自动移除未使用的代码，只打包你使用的组件。

样式按需加载

每个组件都有独立的样式文件：

// 按需引入：先加载全局样式（包含 CSS 变量，不包含组件样式）
import 'yx-web-sdk/global.css'
// 再加载使用的组件样式
import 'yx-web-sdk/input/style.css'

// 或者使用全量样式（包含所有组件样式，适合完整引入）
import 'yx-web-sdk/style.css'

✨ 最佳实践

🚀 推荐：自动导入（最优雅）

对于新项目，强烈推荐使用自动导入方案：

# 安装依赖
npm install -D unplugin-vue-components

# 配置 vite.config.ts
import { YxWebSDKResolver } from 'yx-web-sdk'

然后直接在模板中使用，无需任何导入！

手动导入方案（备选）

小项目（使用 1-2 个组件，按需引入）：

// 正式环境
import Input from 'yx-web-sdk/input'
import 'yx-web-sdk/global.css'
import 'yx-web-sdk/input/style.css'

中型项目（使用 3-5 个组件）：

// 正式环境
import { Input } from 'yx-web-sdk'
import 'yx-web-sdk/global.css'
// 或使用全量样式
import 'yx-web-sdk/style.css'

大型项目（使用多个组件，完整引入）：

// 正式环境
import yxWebSdk from 'yx-web-sdk'
import 'yx-web-sdk/style.css'

核心优势

• ✅ 零配置导入 - 像 Element Plus 一样优雅
• ✅ 自动样式导入 - 无需手动管理 CSS
• ✅ Tree Shaking - 只打包使用的组件
• ✅ TypeScript 支持 - 完整的类型提示
• ✅ 热重载友好 - 开发体验极佳
• ✅ 打包体积最小 - 按需加载，无冗余代码

🔧 环境区分

开发环境

在开发组件库或本地调试时，使用 development 入口：

// 开发环境：直接使用源码，支持热更新
import yxWebSdk from 'yx-web-sdk/development'
import 'yx-web-sdk/global.css'

特点：

• ✅ 直接使用源码，无需构建
• ✅ 支持热更新
• ✅ 便于调试和开发

正式环境

在生产环境或正式项目中，使用主入口：

// 正式环境：使用打包后的代码
import yxWebSdk from 'yx-web-sdk'
import 'yx-web-sdk/style.css'

特点：

• ✅ 使用优化后的打包产物
• ✅ 体积更小，性能更好
• ✅ 适合生产环境

📄 License

MIT