@cldemo/ui-kit 1.0.11 → 1.0.12

package/README.md

@@ -2,43 +2,43 @@
 
 Vue 3 + TypeScript 组件库，提供 PC 端和移动端的通用 UI 组件及工具函数。
 
-## 技术栈
-
-- **Vue 3.5** — Composition API + `<script setup>`
-- **TypeScript 5.6** — 类型安全
-- **Vite 6** — 构建与开发
-- **Vue Router 4** — 路由管理
-- **Pinia 3** — 状态管理
-
-## 快速开始
+## 安装
 
 ```bash
-# 安装依赖
 npm install
+```
 
-# 启动开发服务器（localhost:6001）
-npm run dev
+## 构建组件库
 
-# 构建组件库
+```bash
 npm run lib:build
-
-# 构建项目
-npm run build
 ```
 
+## 按需使用与全局注入
+
+组件库支持 **按需引入**（推荐）与 **全量 install** 两种方式，需注意以下几点：
+
+- **按需引入组件**（三种路径任选，均自带组件样式与 TS 类型）：
+  - `unplugin-vue-components` + `clResolver`（见 `buildLibs/resolver`），组件列表自动从 `clComponentMap` 解析；
+  - 小驼峰入口：`import ClButton from '@cldemo/ui-kit/button'`（`./*` 通配，类型完备）；
+  - 精确组件路径：`import ClButton from '@cldemo/ui-kit/utils/Element/ClButton'`（按端区分 `utils/Element|Web|Mobile`）。
+  - 每个组件入口均已自带其样式（如 `import '.../styles/Element/ClButton.css'`），按需用即可获得完整样式，无需手动引全量 CSS。
+- **全量 CSS**：如需一次性引入所有样式，用 `import '@cldemo/ui-kit/ui-kit.css'`（唯一官方样式入口，勿用 `buildLibs/...` 深层路径——不在 exports 暴露，会被打包器拦截）。按端全量样式也可用 `@cldemo/ui-kit/styles` 下的组件样式。
+- **use\* 工厂（推荐）与 `$ClGlobals` 是两套入口**：
+  - `useNotify` / `useClipboard` / `useAlert` 等独立工厂：随组件按需可用，自身 mount，**不依赖 `app.use(install)`**，推荐业务侧统一使用。
+  - `$ClGlobals.*`：依赖全量 `app.use(install)` 的 `provide`，只在全量安装场景可用，按需模式下拿不到。
+  - **请二选一使用，勿在同一项目混用**，否则同一功能行为可能不一致。
+- **类型提示**：`install` 签名与 `$ClGlobals` 结构可从 `import { ClGlobals, ClGlobalOptions } from '@cldemo/ui-kit'` 获取。
+
 ## 目录结构
 
 ```
 src/
-├── libs/
-│   ├── Element/          # 通用组件（PC / Mobile 共用）
-│   ├── Web/              # Web 端专用组件
-│   ├── Mobile/           # Mobile 端专用组件
-│   └── Common/           # 公共工具（base、day、echart、axios 等）
-├── service/              # API 接口、业务逻辑
-└── web/
-    ├── views/Demo/       # 组件示例页面
-    └── router/           # 路由配置
+└── libs/
+    ├── Element/          # 通用组件（PC / Mobile 共用）
+    ├── Web/              # Web 端专用组件
+    ├── Mobile/           # Mobile 端专用组件
+    └── Common/           # 公共工具（base、day、echart、axios 等）
 ```
 
 ## 组件列表
@@ -91,15 +91,6 @@ src/
 | `v-cl-tooltip` | 工具提示 |
 | `v-cl-lazy-image` | 图片懒加载 |
 
-## 路径别名
-
-| 别名 | 路径 |
-|------|------|
-| `@` | `src/` |
-| `@c.Libs` | `src/libs/` |
-| `@c.Common` | `src/libs/Common/` |
-| `@c.Biz` | `src/service/biz/` |
-
 ## 组件命名规范
 
 - 文件夹名：PascalCase（如 `InputNumberStepper`）