yx-web-sdk 0.0.4

package/README.md

@@ -0,0 +1,424 @@
+# yx-web-sdk
+
+一个基于 Vue 3 + TypeScript 的轻量级组件库
+
+## ✨ 特性
+
+- 🚀 基于 Vue 3 + TypeScript 构建
+- 📦 支持 ES Module 和 UMD 格式
+- 🌲 支持按需加载（Tree Shaking）
+- 💪 完整的 TypeScript 类型定义
+- 🎨 支持自动导入组件和样式
+- 📖 提供 VitePress 文档
+
+## 📦 安装
+
+```bash
+# 使用 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` 入口直接引用源码：
+```js
+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')
+```
+
+### 正式环境（使用打包产物）
+
+在生产环境或正式项目中，使用主入口引用打包后的代码：
+
+```js
+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')
+```
+
+## 📖 使用方式
+
+### 方式一：完整引入
+
+适合快速开发和原型设计，一次性引入所有组件：
+
+```js
+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')
+```
+
+**开发环境完整引入：**
+
+```js
+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）
+
+```js
+// 正式环境：从主入口引入，支持 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>` 中使用：
+
+```vue
+<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>
+```
+
+#### 直接引入单个组件
+
+```js
+// 正式环境：直接引入单个组件
+import Input from 'yx-web-sdk/input'
+// 引入全局样式
+import 'yx-web-sdk/global.css'
+// 引入组件样式
+import 'yx-web-sdk/input/style.css'
+```
+
+**开发环境按需引入：**
+
+```js
+// 开发环境：使用 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 一样，无需手动导入组件和样式！
+
+#### 安装依赖
+
+```bash
+npm install -D unplugin-vue-components
+```
+
+#### 配置 Vite
+
+```ts
+// 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'
+        }),
+      ],
+    }),
+  ],
+})
+```
+
+#### 使用方式
+
+配置完成后，可以直接在模板中使用组件，无需任何导入语句！
+
+```vue
+<template>
+  <!-- 组件和样式会自动导入 -->
+  <YxInput placeholder="请输入内容" />
+</template>
+
+<!-- 无需 script setup，组件和样式会自动导入 -->
+```
+
+#### 高级配置
+
+```ts
+YxWebSDKResolver({
+  importStyle: true, // 是否自动导入样式，默认: true
+  prefix: 'Yx', // 组件前缀，默认: 'Yx'
+  lib: 'yx-web-sdk', // 库名，默认: 'yx-web-sdk'
+})
+```
+
+## 📋 组件列表
+
+- **Input** - 输入框组件
+
+更多组件正在开发中...
+
+## 🛠️ 开发
+
+### 环境要求
+
+- Node.js >= 18
+- npm / pnpm / yarn
+
+### 开发命令
+
+```bash
+# 安装依赖
+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：
+
+```js
+// 方式1: 从主入口导入（推荐用于多个组件）
+import { Input } from 'yx-web-sdk'
+
+// 方式2: 按需导入单个组件（推荐用于少量组件）
+import Input from 'yx-web-sdk/input'
+
+// 方式3: 自动导入（最优雅，无需手动导入）
+<YxInput /> <!-- 自动导入组件和样式 -->
+```
+
+打包工具（Vite/Webpack）会通过 **Tree Shaking** 自动移除未使用的代码，只打包你使用的组件。
+
+### 样式按需加载
+
+每个组件都有独立的样式文件：
+
+```js
+// 按需引入：先加载全局样式（包含 CSS 变量，不包含组件样式）
+import 'yx-web-sdk/global.css'
+// 再加载使用的组件样式
+import 'yx-web-sdk/input/style.css'
+
+// 或者使用全量样式（包含所有组件样式，适合完整引入）
+import 'yx-web-sdk/style.css'
+```
+
+## ✨ 最佳实践
+
+### 🚀 推荐：自动导入（最优雅）
+
+对于新项目，强烈推荐使用自动导入方案：
+
+```bash
+# 安装依赖
+npm install -D unplugin-vue-components
+
+# 配置 vite.config.ts
+import { YxWebSDKResolver } from 'yx-web-sdk'
+```
+
+然后直接在模板中使用，无需任何导入！
+
+### 手动导入方案（备选）
+
+**小项目（使用 1-2 个组件，按需引入）：**
+
+```js
+// 正式环境
+import Input from 'yx-web-sdk/input'
+import 'yx-web-sdk/global.css'
+import 'yx-web-sdk/input/style.css'
+```
+
+**中型项目（使用 3-5 个组件）：**
+
+```js
+// 正式环境
+import { Input } from 'yx-web-sdk'
+import 'yx-web-sdk/global.css'
+// 或使用全量样式
+import 'yx-web-sdk/style.css'
+```
+
+**大型项目（使用多个组件，完整引入）：**
+
+```js
+// 正式环境
+import yxWebSdk from 'yx-web-sdk'
+import 'yx-web-sdk/style.css'
+```
+
+### 核心优势
+
+- ✅ **零配置导入** - 像 Element Plus 一样优雅
+- ✅ **自动样式导入** - 无需手动管理 CSS
+- ✅ **Tree Shaking** - 只打包使用的组件
+- ✅ **TypeScript 支持** - 完整的类型提示
+- ✅ **热重载友好** - 开发体验极佳
+- ✅ **打包体积最小** - 按需加载，无冗余代码
+
+## 🔧 环境区分
+
+### 开发环境
+
+在开发组件库或本地调试时，使用 `development` 入口：
+
+```js
+// 开发环境：直接使用源码，支持热更新
+import yxWebSdk from 'yx-web-sdk/development'
+import 'yx-web-sdk/global.css'
+```
+
+**特点：**
+- ✅ 直接使用源码，无需构建
+- ✅ 支持热更新
+- ✅ 便于调试和开发
+
+### 正式环境
+
+在生产环境或正式项目中，使用主入口：
+
+```js
+// 正式环境：使用打包后的代码
+import yxWebSdk from 'yx-web-sdk'
+import 'yx-web-sdk/style.css'
+```
+
+**特点：**
+- ✅ 使用优化后的打包产物
+- ✅ 体积更小，性能更好
+- ✅ 适合生产环境
+
+## 📄 License
+
+MIT