asai-vue-host 0.2.55 → 0.2.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +184 -116
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,116 +1,184 @@
1
- # asai-vue-host
2
-
3
- A simple vue host for asai development.
4
-
5
- ```
6
- npm i asai-vue-host -g
7
- ```
8
-
9
- ## LibInit.ts
10
-
11
- ```
12
- // 从vue中导入ref, reactive, toRaw, defineAsyncComponent函数，用于实现响应式数据和异步组件加载
13
- import { ref, reactive, toRaw, defineAsyncComponent } from 'vue';
14
-
15
- // 导出一个默认函数，用于初始化库
16
- // 此函数返回一个包含lib对象的对象，lib对象包含一些属性和方法，用于处理组件、指令和模块的加载
17
- // eager: 表示是否立即加载资源
18
- // ref, reactive, toRaw: Vue的响应式工具函数，用于创建和管理响应式数据
19
- // loadfn: 包含异步组件加载函数，用于异步加载Vue组件
20
- // vuecomps: 存储已加载的组件，避免重复加载
21
- // loadts: 加载TypeScript模块，并将其挂载到全局属性上
22
- // loadv: 加载Vue指令，并将其注册到应用中
23
- // loadvue: 加载Vue组件，并将其注册到应用中
24
- // 返回值: 包含lib对象的对象
25
- export default () => {
26
- // 定义库对象，包含一些属性和方法，用于处理组件、指令和模块的加载
27
- const lib: any = {
28
- eager: true,
29
- ref,
30
- reactive,
31
- toRaw,
32
- loadfn: {
33
- fnvue: defineAsyncComponent,
34
- },
35
- vuecomps: {},
36
- };
37
-
38
- // 加载TypeScript模块，并将其挂载到全局属性上
39
- lib.loadts = (params: any = {}) => {
40
- const ens: any = {};
41
- for (const i in params.files) {
42
- const nArr = i.split('/');
43
- ens[nArr[nArr.length - 1].slice(0, -3)] = params.files[i].default;
44
- }
45
- params.app.config.globalProperties[params.key] = ens;
46
- };
47
- // 加载Vue指令，并将其注册到应用中
48
- lib.loadv = (params: any = {}) => {
49
- for (const i in params.files) {
50
- const cname: string = i.split('/v-')[1].split('/')[0];
51
- if (cname && !lib.vuecomps[cname]) {
52
- lib.vuecomps[cname] = 1;
53
- params.app.directive(cname, params.files[i].default);
54
- }
55
- }
56
- };
57
- // 加载Vue组件，并将其注册到应用中
58
- lib.loadvue = (params: any = {}) => {
59
- for (const i in params.files) {
60
- if (params.eager) {
61
- const component = params.files[i].default;
62
- const cname = params?.fullname ? i : component.__name;
63
- if (cname && !lib.vuecomps[cname]) {
64
- lib.vuecomps[cname] = component;
65
- params.app.component(cname, component);
66
- } else {
67
- }
68
- } else {
69
- const cname = params?.fullname
70
- ? i
71
- : i.substring(0, i.lastIndexOf('.'))?.split('/').pop();
72
- if (cname && !lib.vuecomps[cname]) {
73
- lib.vuecomps[cname] = params.loadfn.fnvue(params.files[i]);
74
- params.app.component(cname, lib.vuecomps[cname]);
75
- } else {
76
- }
77
- }
78
- }
79
- };
80
-
81
- // 返回包含lib对象的对象，供外部使用
82
- return { lib };
83
- };
84
- ```
85
-
86
- ## AsInstall.ts
87
-
88
- ```
89
- import LibInit from './LibInit';
90
-
91
- // 导入asasai模块（前置必须的模块，先加载）
92
- import asasai from 'asai-vue-host';
93
- import '/node_modules/asai-vue-host/dist/asai-vue-host.css';
94
-
95
-
96
- export default {
97
- install(app: App) {
98
- const { lib } = LibInit();
99
- asasai.install(app, lib); // 挂载系统插件
100
-
101
- // 其他初始化操作
102
- },
103
- };
104
- ```
105
-
106
- ## main.ts中加载使用
107
-
108
- ```
109
- // 插件实现部分
110
- import AsInstall from './AsInstall';
111
-
112
- // 创建 Vue 应用实例
113
- const app = createApp(App);
114
- // 使用插件 AsInstall
115
- app.use(AsInstall);
116
- ```
1
+ # asai-vue-host — 应用宿主框架（核心）
2
+
3
+ ## 概述
4
+
5
+ `asai-vue-host` 是 AsaiWeb CMS 的**核心应用宿主框架**，提供应用加载、模块管理、路由分发、WebSocket 通信和数据库响应的能力。它是整个前端架构的运行容器。
6
+
7
+ ## 功能
8
+
9
+ - 🚀 **应用启动**：管理完整应用加载流程
10
+ - 📦 **模块管理**：动态加载和卸载功能模块
11
+ - 🧭 **路由分发**：基于 Hash 路由的页面分发
12
+ - 🔌 **WebSocket 通信**：WebSocket 连接管理与事件系统
13
+ - 💾 **数据库响应**：IndexedDB / 本地数据响应式提供
14
+ - 🎯 **功能注入**：通过 `provide` 提供全局数据和方法
15
+ - ⏳ **加载状态管理**：多种加载动画组件
16
+ - 🚨 **错误处理**：404 页面、加载错误页面
17
+
18
+ ## 文件结构
19
+
20
+ ```
21
+ asai-vue-host/
22
+ ├── src/
23
+ │ └── components/
24
+ │ ├── index.ts # 插件安装入口（install 方法）
25
+ │ ├── asengine/
26
+ │ │ └── provide/
27
+ │ │ ├── providedb.ts # 数据库响应式数据 Provide
28
+ │ │ ├── providedbwork.ts # 数据库工作线程 Provide
29
+ │ │ ├── providefn.ts # 功能函数 Provide
30
+ │ │ └── providews.ts # WebSocket 数据 Provide
31
+ │ └── asui/
32
+ │ ├── app/
33
+ │ │ ├── AsaiWebItemIndex.vue # 应用入口页面
34
+ │ │ ├── AsaiWebItemDefault.vue # 默认页面
35
+ │ │ ├── AsaiWebModule.vue # 模块容器
36
+ │ │ ├── AsaiWebModuleDefault.vue # 默认模块
37
+ │ │ ├── AsaiWebModuleIndex.vue # 模块索引页
38
+ │ │ ├── AsaiWebServer.vue # 服务器页面
39
+ │ │ └── AsaiComponent.vue # 通用组件容器
40
+ │ ├── common/
41
+ │ │ ├── AsPageBusy.vue # 页面繁忙状态
42
+ │ │ ├── AsPageBusyGif.vue # GIF 加载动画
43
+ │ │ ├── AsReset.vue # 重置组件
44
+ │ │ ├── MenuShowFix.vue # 菜单显示修复
45
+ │ │ ├── RouterMap.vue # 路由映射组件
46
+ │ │ ├── AsPageBusy/
47
+ │ │ │ ├── AsLoadingA3d.vue # 3D 加载动画
48
+ │ │ │ └── AsLoadingCircle.vue# 圆形加载动画
49
+ │ │ └── _comps/
50
+ │ │ └── Asai404.vue # 404 页面
51
+ │ └── page/
52
+ │ ├── PageErr.vue # 错误页面
53
+ │ ├── PageLoadErr.vue # 加载错误
54
+ │ ├── PageLoadServer.vue # 服务器加载
55
+ │ ├── PageLoadUserToken.vue # 用户 Token 加载
56
+ │ ├── PageLoadUserTokenOnline.vue # 在线 Token 加载
57
+ │ └── PageLoadWs.vue # WebSocket 加载
58
+ └── README.md
59
+ ```
60
+
61
+ ## 安装方式
62
+
63
+ ```typescript
64
+ import AsaiVueHost from 'asai-vue-host';
65
+
66
+ app.use(AsaiVueHost, {
67
+ loadts: (options) => { /* 加载 TypeScript 模块 */ },
68
+ loadvue: (options) => { /* 加载 Vue 组件 */ },
69
+ loadfn: (path) => { /* 加载函数 */ },
70
+ });
71
+ ```
72
+
73
+ ## Provide 系统
74
+
75
+ 插件通过 Vue 的 `provide/inject` 机制注入以下全局功能：
76
+
77
+ | Provide Key | 说明 |
78
+ |-------------|------|
79
+ | `$engineasai` | 主引擎上下文 |
80
+ | `providedb` | 数据库响应式数据 |
81
+ | `providews` | WebSocket 数据 |
82
+ | `providefn` | 功能函数 |
83
+ | `providedbwork` | 数据库工作线程 |
84
+
85
+ ## 核心组件
86
+
87
+ ### 应用组件
88
+
89
+ | 组件 | 说明 |
90
+ |------|------|
91
+ | `AsaiWebServer` | 服务器连接管理 |
92
+ | `AsaiWebModule` | 模块容器，管理子页面 |
93
+ | `AsaiWebModuleIndex` | 模块首页索引 |
94
+ | `AsaiWebModuleDefault` | 默认模块视图 |
95
+ | `AsaiWebItemIndex` | 应用主入口页面 |
96
+ | `AsaiWebItemDefault` | 应用默认页面 |
97
+ | `AsaiComponent` | 动态组件渲染容器 |
98
+
99
+ ### 公共组件
100
+
101
+ | 组件 | 说明 |
102
+ |------|------|
103
+ | `AsPageBusy` | 页面繁忙/加载中状态 |
104
+ | `AsPageBusyGif` | GIF 格式加载动画 |
105
+ | `AsLoadingA3d` | 3D 风格加载动画 |
106
+ | `AsLoadingCircle` | 圆形旋转加载动画 |
107
+ | `AsReset` | 数据重置组件 |
108
+ | `MenuShowFix` | 菜单显示修正 |
109
+ | `RouterMap` | Hash 路由映射 |
110
+ | `Asai404` | 404 页面 |
111
+
112
+ ### 页面组件
113
+
114
+ | 组件 | 说明 |
115
+ |------|------|
116
+ | `PageErr` | 通用错误页面 |
117
+ | `PageLoadErr` | 加载失败页面 |
118
+ | `PageLoadServer` | 服务器加载页面 |
119
+ | `PageLoadUserToken` | 用户认证 Token 加载 |
120
+ | `PageLoadUserTokenOnline` | 在线用户 Token 加载 |
121
+ | `PageLoadWs` | WebSocket 连接加载 |
122
+
123
+ ## 技术细节
124
+
125
+ - **插件安装模式**：通过 Vue 插件系统集成，使用 `install(app, opt)` 模式
126
+ - **自动扫描加载**：使用 `import.meta.glob` 自动发现并注册组件
127
+ - **模块化注入**：通过 `$engineasai` 注入点集中管理
128
+ - **异步加载**：组件使用动态导入，按需加载减少首屏体积
129
+ - **加载动画**：提供 CSS3 动画和 GIF 动画两种方案
130
+
131
+ ## 代码优化分析
132
+
133
+ ### 已做优化
134
+ - ✅ 插件化架构：使用 Vue 插件 `install(app, opt)` 模式，可组合安装
135
+ - ✅ 自动扫描加载：`import.meta.glob` 自动发现注册组件
136
+ - ✅ 模块化注入：不同功能使用独立 key（`$engineasai`），避免命名冲突
137
+ - ✅ Provide/Inject 模式：全局数据解耦，组件按需注入
138
+ - ✅ 提供多种加载动画（CSS3 动画 + GIF），降级方案
139
+
140
+ ### 可优化点
141
+
142
+ #### 1. Provide 数据为简单 reactive 对象
143
+ ```typescript
144
+ // providedb.ts
145
+ export default reactive({
146
+ providedb: { data: {} }
147
+ });
148
+ // providews.ts
149
+ export default reactive({
150
+ providews: { data: { rooms: {}, wssys: {} } }
151
+ });
152
+ ```
153
+ **问题**：三个 provide 都使用 `reactive` 包裹但在对象中嵌套对象。Vue3 的 `reactive` 是深度的，嵌套对象的属性变更也会触发更新。但数据变更后，如果 inject 方直接替换内部对象（如 `providedb.data = newData`），可能会丢失响应性。
154
+
155
+ **建议**：使用 `readonly` 包装 inject 数据，或明确提供数据修改方法。
156
+
157
+ #### 2. 组件扫描使用 eager: false（lazy 模式）
158
+ ```typescript
159
+ files: (import.meta as any).glob(['./asui/*/*.vue'])
160
+ ```
161
+ **问题**：lazy 模式（非 eager）意味着组件只在首次渲染时异步加载。对于核心宿主组件（如 `AsaiWebModule`、`AsaiWebItemIndex`），它们是首屏必需组件，懒加载可能导致白屏闪烁。
162
+
163
+ **建议**：对核心组件使用 eager 加载，次要组件使用 lazy。
164
+
165
+ #### 3. PageLoadUserToken 等页面组件未定义Props
166
+ 一些页面加载组件（如 `PageLoadWs`、`PageLoadErr`）没有明确的 Props 定义。建议添加 Props 接口，至少支持错误信息、重试函数等。
167
+
168
+ #### 4. 错误页面没有重试机制
169
+ `PageErr` 和 `PageLoadErr` 只显示错误信息，没有"重试"按钮。建议添加 `retry` 属性和 `@retry` 事件。
170
+
171
+ #### 5. "asany" 类型过多
172
+ 整个插件的 TypeScript 大量使用 `any` 类型，失去类型检查的意义。建议：
173
+ - 定义核心类型接口（如 `AsaiContext`、`ModuleConfig`、`AppRoute`）
174
+ - 将 `$fn`、`$global`、`$model` 等全局对象的类型定义为接口
175
+
176
+ #### 6. Index.ts 中的 `opt.loadts` 和 `opt.loadvue` 缺少类型定义
177
+ `install(app, opt)` 的 `opt` 参数没有 TypeScript 接口，调用方不知需传入哪些方法。建议：
178
+ ```typescript
179
+ interface HostPluginOptions {
180
+ loadts: (opts: { app: any; key: string; eager: boolean; files: Record<string, any> }) => void;
181
+ loadvue: (opts: { loadfn: any; app: any; eager: boolean; files: Record<string, any> }) => void;
182
+ loadfn: (path: string) => any;
183
+ }
184
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "asai-vue-host",
3
- "version": "0.2.55",
3
+ "version": "0.2.56",
4
4
  "description": "asai for you",
5
5
  "author": "Asai",
6
6
  "license": "ISC",