@lemon30_npm/csit-vue3 0.0.19 → 0.0.20

package/README.md

@@ -18,7 +18,7 @@ pnpm add csit-vue3
 
 ```
 
-#### ⚠️ 注意：该组件库依赖以下环境，请确保你的项目已安装(如果你使用Vue 3项目脚手架，请忽略)
+⚠️ 注意：该组件库依赖以下环境，请确保你的项目已安装(如果你使用Vue 3项目脚手架，请忽略)
 
 > 版本可自行升级，无影响
 
@@ -121,8 +121,6 @@ import  CiBlueLineTitle  from 'csit-vue3/ci-blue-line-title'
 </style>
 ```
 
-
-
 #### 按需导入规则和建议
 
 相信细心的小伙伴们会有疑问了❓ 按需导入时 import xxx from 'csit-vue3/yyy'; 后面的yyy是什么值呢❓
@@ -165,6 +163,144 @@ import "csit-vue3/dist/index.css";
 | snake_case | ci_blue_line_title | Python变量、文件名、数据库字段           |
 | kebab-case | ci-blue-line-title | 文件/文件夹、HTML/CSS 类名、自定义组件名 |
 
+### "优雅的"按需导入(自动导入)【！！！推荐】
+
+> 为你使用的 csit-vue3 组件库提供一个 unplugin-vue-components 的 Resolver，就像 ElementPlusResolver 一样，支持按名称自动引入组件。
+
+#### 背景介绍
+
+`Element Plus`按需导入之自动导入写法（点击查看[官方文档🔗](https://element-plus.org/zh-CN/guide/quickstart.html#%E6%8C%89%E9%9C%80%E5%AF%BC%E5%85%A5)）
+
+```ts
+// 官网中有这么一句, 但是我们项目中不能 从 unplugin-vue-components 插件中导出 csit-vue3 的解析器
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+```
+
+##### 为什么ElementPlusResolver能直接用？
+
+因为：
+
+- `unplugin-vue-components` 官方内置了 **对主流 UI 框架（如 `Element Plus`、`Ant Design Vue`、`Vuetify`）的解析器**
+- 这些内置的 resolver 都在 `unplugin-vue-components/resolvers` 中暴露了出来
+- `Element Plus` 官方团队也专门配合封装了 ElementPlusResolver
+
+🔗 官方文档：<https://github.com/antfu/unplugin-vue-components#resolvers>
+
+##### 如何让你自己使用的 csit-vue3 组件库也能像ElementPlusResolver那样？
+
+- 很简单，你只需要自己手动写一个 Resolver
+
+#### 实战代码示例
+
+完成如下步骤即可：
+
+1. 你需要使用额外的插件来导入要使用的组件，你需要安装`unplugin-vue-components` 这款插件。
+2. 你需要手写一个 Resolver。
+3. 把`unplugin-vue-components`插件配置到 `Vite`  的配置文件中
+
+##### 1. 安装插件
+
+```bash
+npm install -D unplugin-vue-components
+```
+
+##### 2. 在你的项目中手写 Resolver
+
+```ts
+/**
+ * 自定义组件库解析器：CsitComponentResolver
+ * 用于配合 unplugin-vue-components 实现按名称自动导入
+ * 比如：使用 <CiUpload /> 会自动解析为 csit-vue3/ci-upload
+ */
+export function CsitComponentResolver() {
+  return {
+    type: 'component',
+
+    /**
+     * name 是你在模板中写的组件名，比如 <CiUpload />，这里接收到的是 "CiUpload"
+     */
+    resolve(name: string) {
+      // 判断组件名是否符合 ci- 开头的组件，比如：CiUpload -> ci-upload
+      if (!/^Ci[A-Z]/.test(name)) return
+
+      // 将 PascalCase 转为 kebab-case（CiUpload → ci-upload）
+      const kebabName = name
+        .replace(/^Ci/, 'ci-')               // 去掉首字母 Ci
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2') // 大写转短横线
+        .toLowerCase()
+
+      // 返回路径：配合 exports 字段实现自动导入
+      return {
+        name, // 保持原组件名
+        from: `csit-vue3/${kebabName}`, // 自动解析导入路径
+      }
+    },
+  }
+}
+```
+
+##### 3. 把`unplugin-vue-components`插件配置到 `Vite`  的配置文件中
+
+```ts
+import { defineConfig } from 'vite'
+import Components from 'unplugin-vue-components/vite'
+import { CsitComponentResolver } from './path/to/your-resolver' // 你定义的 Resolver 放在哪里了就从哪里导入
+
+export default defineConfig({
+  plugins: [
+    Components({
+      resolvers: [CsitComponentResolver()],
+    }),
+  ],
+})
+```
+
+⚠️ 注意：样式文件我们就不支持按需导入了，我们建议：在 main.ts 中全量引入所有组件样式
+
+```ts
+// 样式不建议按需导入, 建议 main.ts 中直接全量导入, 清晰且不易出现问题
+
+// main.ts
+import "csit-vue3/dist/index.css";
+```
+
+至此结束，你应该在某个页面写下：
+
+```vue
+<template>
+  <CiUpload />
+  <CiBlueLineTitle />
+</template>
+```
+
+> ❗注意：
+>
+> 不要在当前vue页面手动 import，不要在当前vue页面手动注册。
+>
+> 不要在main.ts中全量注册组件，按需注册组件。
+>
+> 运行后应该不报错且能渲染。至此 验证结束 大功告成✅。
+
+**当然，我们会把解析器内置到 `csit-vue3`中，开发者无需关心解析器实现，因为解析器实现要遵循一定的组件库设计规则，开发者只需从 `csit-vue3`中导出使用即可。**
+
+如果使用`csit-vue3`内置解析器，实战第二步不需要你做，第三步参考如下。
+
+```ts
+import { defineConfig } from 'vite'
+import Components from 'unplugin-vue-components/vite'
+
+// 导出 csit-vue3 解析器
+import { CsitComponentResolver } from 'csit-vue3/resolvers'
+
+export default defineConfig({
+  plugins: [
+    Components({
+      resolvers: [CsitComponentResolver()],
+    }),
+  ],
+})
+```
+
 ## 🧩 示例组件使用
 
 ```html

package/dist/csit-vue3.js

@@ -2863,6 +2863,24 @@ const f0 = {
 h1.install = (e) => {
   e.component(h1.name, h1);
 };
+function z0() {
+  return {
+    type: "component",
+    /**
+     * name 是你在模板中写的组件名，比如 <CiUpload />，这里接收到的是 "CiUpload"
+     */
+    resolve(e) {
+      if (!/^Ci[A-Z]/.test(e)) return;
+      const t = e.replace(/^Ci/, "ci-").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+      return {
+        name: e,
+        // 保持原组件名
+        from: `@lemon30_npm/csit-vue3/${t}`
+        // 自动解析导入路径
+      };
+    }
+  };
+}
 const I0 = [
   // 蓝色竖线、标题组件
   s1,
@@ -2898,7 +2916,7 @@ const I0 = [
   I0.forEach((t) => {
     e.component(t.name, t);
   });
-}, z0 = { install: D0 };
+}, q0 = { install: D0 };
 export {
   s1 as CiBlueLineTitle,
   p1 as CiCommonListLayout,
@@ -2915,6 +2933,7 @@ export {
   i1 as CiSvgIcon,
   n1 as CiTimelineList,
   h1 as CiUpload,
-  z0 as default,
+  z0 as CsitComponentResolver,
+  q0 as default,
   D0 as install
 };

package/dist/lib/components/index.js

@@ -1,4 +1,4 @@
-import { CiBlueLineTitle as m } from "../ci-blue-line-title/index.js";
+import { CiBlueLineTitle as t } from "../ci-blue-line-title/index.js";
 import "../ci-svg-icon/index.js";
 import "../ci-echarts/ci-echart-pie/index.js";
 import "../ci-echarts/ci-echart-bar/index.js";
@@ -13,15 +13,16 @@ import "../ci-common-list/ci-common-list-pagination/index.js";
 import "../ci-common-list/ci-common-list-start-end-datepicker/index.js";
 import "../ci-page-header/index.js";
 import "../ci-upload/index.js";
-import t from "../ci-svg-icon/index.vue.js";
+import { CsitComponentResolver as Y } from "./resolvers/index.js";
+import m from "../ci-svg-icon/index.vue.js";
 import r from "../ci-echarts/ci-echart-pie/index.vue.js";
 import p from "../ci-echarts/ci-echart-bar/index.vue.js";
 import a from "../ci-echarts/ci-echart-ChinaMap/index.vue.js";
-import n from "../ci-element-plus/ci-el-date-picker-daterange/index.vue.js";
-import e from "../ci-time-line-list/index.vue.js";
+import e from "../ci-element-plus/ci-el-date-picker-daterange/index.vue.js";
+import n from "../ci-time-line-list/index.vue.js";
 import C from "../ci-no-data-status/index.vue.js";
-import f from "../ci-dictionary-select/index.vue.js";
-import s from "../ci-common-list/ci-common-list-layout/index.vue.js";
+import s from "../ci-dictionary-select/index.vue.js";
+import f from "../ci-common-list/ci-common-list-layout/index.vue.js";
 import c from "../ci-common-list/ci-common-list-query/index.vue.js";
 import l from "../ci-common-list/ci-common-list-pagination/index.vue.js";
 import u from "../ci-common-list/ci-common-list-start-end-datepicker/index.vue.js";
@@ -29,9 +30,9 @@ import L from "../ci-page-header/index.vue.js";
 import E from "../ci-upload/index.vue.js";
 const _ = [
   // 蓝色竖线、标题组件
-  m,
-  // svg图标组件
   t,
+  // svg图标组件
+  m,
   // echarts 饼图组件
   r,
   // echarts 柱状图组件
@@ -39,15 +40,15 @@ const _ = [
   // echarts 中国地图组件
   a,
   // elementPlus 日期:选择一段时间 ​组件
-  n,
-  // 时间线组件
   e,
+  // 时间线组件
+  n,
   // 没有数据状态时展示效果组件
   C,
   // 字典项组件
-  f,
-  // 公共列表布局组件
   s,
+  // 公共列表布局组件
+  f,
   // 公共列表布局组件 - 查询条件
   c,
   // 公共列表布局组件 - 分页
@@ -64,21 +65,22 @@ const _ = [
   });
 }, V = { install: d };
 export {
-  m as CiBlueLineTitle,
-  s as CiCommonListLayout,
+  t as CiBlueLineTitle,
+  f as CiCommonListLayout,
   l as CiCommonListPagination,
   c as CiCommonListQuery,
   u as CiCommonListStartEndDatePicker,
-  f as CiDictionarySelect,
+  s as CiDictionarySelect,
   p as CiEchartBar,
   a as CiEchartChinaMap,
   r as CiEchartPie,
-  n as CiElDatePickerDaterange,
+  e as CiElDatePickerDaterange,
   C as CiNoDataStatus,
   L as CiPageHeader,
-  t as CiSvgIcon,
-  e as CiTimelineList,
+  m as CiSvgIcon,
+  n as CiTimelineList,
   E as CiUpload,
+  Y as CsitComponentResolver,
   V as default,
   d as install
 };

package/dist/lib/components/resolvers/index.js

@@ -0,0 +1,21 @@
+function o() {
+  return {
+    type: "component",
+    /**
+     * name 是你在模板中写的组件名，比如 <CiUpload />，这里接收到的是 "CiUpload"
+     */
+    resolve(e) {
+      if (!/^Ci[A-Z]/.test(e)) return;
+      const t = e.replace(/^Ci/, "ci-").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+      return {
+        name: e,
+        // 保持原组件名
+        from: `@lemon30_npm/csit-vue3/${t}`
+        // 自动解析导入路径
+      };
+    }
+  };
+}
+export {
+  o as CsitComponentResolver
+};

package/dist/types/src/components/index.d.ts

@@ -16,6 +16,7 @@ import { default as CiPageHeader } from './components-project/ci-page-header/ind
 import { default as CiUpload } from './components-project/ci-upload/index';
 declare const install: (app: App) => void;
 export { install, CiBlueLineTitle, CiSvgIcon, CiEchartPie, CiEchartBar, CiEchartChinaMap, CiElDatePickerDaterange, CiTimelineList, CiNoDataStatus, CiDictionarySelect, CiCommonListLayout, CiCommonListQuery, CiCommonListPagination, CiCommonListStartEndDatePicker, CiPageHeader, CiUpload, };
+export * from './resolvers/index';
 declare const _default: {
     install: (app: App) => void;
 };

package/dist/types/src/components/resolvers/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 自定义组件库解析器：CsitComponentResolver
+ * 用于配合 unplugin-vue-components 实现按名称自动导入
+ * 比如：使用 <CiUpload /> 会自动解析为 csit-vue3/ci-upload
+ */
+export declare function CsitComponentResolver(): {
+    type: string;
+    /**
+     * name 是你在模板中写的组件名，比如 <CiUpload />，这里接收到的是 "CiUpload"
+     */
+    resolve(name: string): {
+        name: string;
+        from: string;
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemon30_npm/csit-vue3",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "type": "module",
   "author": "cuiwq",
   "license": "MIT",
@@ -120,6 +120,10 @@
     },
     "./ci-upload/style/index.css": {
       "default": "./dist/lib/ci-upload/index.css"
+    },
+    "./resolvers": {
+      "import": "./dist/src/components/resolvers/index.js",
+      "types": "./dist/types/src/components/resolvers/index.d.ts"
     }
   },
   "scripts": {