solely 0.0.22 → 0.0.28
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.
- package/LICENSE +21 -21
- package/README.md +457 -275
- package/dist/base/base-element.d.ts +48 -6
- package/dist/base/decorators.d.ts +15 -3
- package/dist/base/router-view.d.ts +25 -2
- package/dist/solely.js +695 -322
- package/dist/solely.umd.cjs +3 -1
- package/dist/utils/html-parse.d.ts +22 -1
- package/dist/utils/observe.d.ts +57 -5
- package/package.json +17 -4
- package/dist/utils/functions copy 2.d.ts +0 -2
- package/dist/utils/functions copy.d.ts +0 -2
package/README.md
CHANGED
|
@@ -1,275 +1,457 @@
|
|
|
1
|
-
# Solely
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
<
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
<
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
<
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
<
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
1.
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
1
|
+
# Solely
|
|
2
|
+
|
|
3
|
+
基于 Web Components 的轻量级响应式框架
|
|
4
|
+
< 10 kB(gzip)· 零依赖 · TypeScript 友好 · 单文件即可跑
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 项目简介
|
|
9
|
+
|
|
10
|
+
Solely 是一款基于 Web Components 标准的轻量级前端框架,专为简化小型项目开发而设计。它保留了与原生 JavaScript/TypeScript 的高兼容性,同时提供了现代前端框架的核心功能:响应式数据绑定、虚拟 DOM 渲染、组件化开发、简单路由。
|
|
11
|
+
|
|
12
|
+
核心优势
|
|
13
|
+
|
|
14
|
+
1. 简化复杂性:设计简洁,与原生 JS/TS 语法保持一致
|
|
15
|
+
2. 响应式系统:基于 Proxy 的深度响应式
|
|
16
|
+
3. 虚拟 DOM:轻量级 diff,批量更新
|
|
17
|
+
4. 组件化:继承 `BaseElement` + `@CustomElement` 装饰器
|
|
18
|
+
5. 完整 TypeScript 泛型支持
|
|
19
|
+
6. 内置 hash 路由,单页应用开箱即用
|
|
20
|
+
|
|
21
|
+
适用于快速原型、嵌入式小部件、不愿引入大型框架的场景。
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 安装
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm i solely
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 快速开始(最小可跑示例)
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { BaseElement, CustomElement } from 'solely'
|
|
37
|
+
|
|
38
|
+
@CustomElement({
|
|
39
|
+
tagName: 'hello-world',
|
|
40
|
+
template: `
|
|
41
|
+
<div class="box">
|
|
42
|
+
<h1>{{ $data.title }}</h1>
|
|
43
|
+
<button onclick="this.$data.count++">Count: {{ $data.count }}</button>
|
|
44
|
+
</div>`,
|
|
45
|
+
styles: `
|
|
46
|
+
.box { padding: 12px; border: 1px solid #ddd; border-radius: 6px; }
|
|
47
|
+
button { margin-top: 8px; }`,
|
|
48
|
+
shadowDOM: { use: true }
|
|
49
|
+
})
|
|
50
|
+
class HelloWorld extends BaseElement<{ title: string; count: number }> {
|
|
51
|
+
onInit() {
|
|
52
|
+
this.$data = { title: 'Hello Solely', count: 0 }
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```html
|
|
58
|
+
<body>
|
|
59
|
+
<hello-world></hello-world>
|
|
60
|
+
<script type="module" src="/src/main.ts"></script>
|
|
61
|
+
</body>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
本地克隆体验
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git clone <repo>
|
|
68
|
+
cd solely
|
|
69
|
+
npm i
|
|
70
|
+
npm run dev # http://localhost:5173/ 查看 examples/
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 模板语法速查
|
|
76
|
+
|
|
77
|
+
> 所有模板必须是**合法 HTML**;框架会提前编译成高效更新函数,无运行时解析开销。
|
|
78
|
+
|
|
79
|
+
| 功能 | 语法格式 | 完整示例 |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| **文本插值** | `{{ 表达式 }}` | `<span>{{ $data.msg }}</span>` |
|
|
82
|
+
| **属性绑定** | `s-属性名="表达式"` | `<img s-src="$data.url" s-alt="$data.name">` |
|
|
83
|
+
| **布尔属性** | `s-属性名="表达式"`(真值才输出) | `<button s-disabled="$data.loading">提交</button>` |
|
|
84
|
+
| **双向绑定** | `s-model="字段路径"` | `<input s-model="$data.username">` |
|
|
85
|
+
| **原始事件** | `on事件名="语句"`(可直读 `$data`) | `<button onclick="$data.count++">+</button>` |
|
|
86
|
+
| **条件渲染** | `<If condition="表达式">...</If>`<br>`<ElseIf condition="...">...</ElseIf>`<br>`<Else>..</Else>` | `<If condition="$data.ok"><p>成功</p></If>` |
|
|
87
|
+
| **列表渲染** | `<For each="数组" item="项变量" index="下标变量">...</For>` | `<For each="$data.list" item="it">{{ it }}</For>` |
|
|
88
|
+
| **动态类** | `s-class="对象/数组/字符串"` | `<div s-class="{ active: $data.isActive }">` |
|
|
89
|
+
| **动态样式** | `s-style="对象"` | `<div s-style="{ color: $data.c }">` |
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
### 1. 文本插值
|
|
94
|
+
|
|
95
|
+
```html
|
|
96
|
+
<!-- 基本 -->
|
|
97
|
+
<p>{{ $data.message }}</p>
|
|
98
|
+
|
|
99
|
+
<!-- 表达式 -->
|
|
100
|
+
<p>总价:{{ $data.price * $data.quantity }}</p>
|
|
101
|
+
|
|
102
|
+
<!-- 三元 -->
|
|
103
|
+
<span>{{ $data.online ? '在线' : '离线' }}</span>
|
|
104
|
+
|
|
105
|
+
<!-- 函数调用 -->
|
|
106
|
+
<div>{{ this.formatDate($data.date) }}</div>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
### 2. 属性绑定
|
|
112
|
+
|
|
113
|
+
```html
|
|
114
|
+
<!-- 普通属性 -->
|
|
115
|
+
<img s-src="$data.avatar" s-alt="$data.name">
|
|
116
|
+
<a s-href="$data.link">跳转</a>
|
|
117
|
+
|
|
118
|
+
<!-- data-* 属性 -->
|
|
119
|
+
<div s-data-user-id="$data.uid"></div>
|
|
120
|
+
|
|
121
|
+
<!-- class 拼接 -->
|
|
122
|
+
<div class="btn" s-class="$data.variant"></div>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
### 3. 布尔属性
|
|
128
|
+
|
|
129
|
+
```html
|
|
130
|
+
<button s-disabled="$data.isSubmitting">提交中…</button>
|
|
131
|
+
<input type="checkbox" s-checked="$data.selected">
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
### 4. 双向绑定 `s-model`
|
|
137
|
+
|
|
138
|
+
```html
|
|
139
|
+
<!-- 文本 -->
|
|
140
|
+
<input type="text" s-model="$data.username">
|
|
141
|
+
|
|
142
|
+
<!-- 多行 -->
|
|
143
|
+
<textarea s-model="$data.desc"></textarea>
|
|
144
|
+
|
|
145
|
+
<!-- 单选按钮组 -->
|
|
146
|
+
<label><input type="radio" name="sex" value="m" s-model="$data.sex"> 男</label>
|
|
147
|
+
<label><input type="radio" name="sex" value="f" s-model="$data.sex"> 女</label>
|
|
148
|
+
|
|
149
|
+
<!-- 单个复选框 -->
|
|
150
|
+
<input type="checkbox" s-model="$data.agree"> 同意协议
|
|
151
|
+
|
|
152
|
+
<!-- 单选下拉框 -->
|
|
153
|
+
<select s-model="$data.city">
|
|
154
|
+
<option value="">请选择</option>
|
|
155
|
+
<option value="beijing">北京</option>
|
|
156
|
+
<option value="shanghai">上海</option>
|
|
157
|
+
<option value="guangzhou">广州</option>
|
|
158
|
+
</select>
|
|
159
|
+
|
|
160
|
+
<!-- 多选下拉框(重要:绑定值建议是数组类型) -->
|
|
161
|
+
<select multiple s-model="$data.selectedCities">
|
|
162
|
+
<option value="beijing">北京</option>
|
|
163
|
+
<option value="shanghai">上海</option>
|
|
164
|
+
<option value="guangzhou">广州</option>
|
|
165
|
+
<option value="shenzhen">深圳</option>
|
|
166
|
+
</select>
|
|
167
|
+
|
|
168
|
+
<!-- 初始化示例 -->
|
|
169
|
+
<!-- this.$data = {
|
|
170
|
+
selectedCities: ['beijing', 'shanghai']
|
|
171
|
+
} -->
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
### 5. 条件渲染
|
|
177
|
+
|
|
178
|
+
```html
|
|
179
|
+
<If condition="$data.isLoggedIn">
|
|
180
|
+
<p>欢迎,{{ $data.name }}!</p>
|
|
181
|
+
</If>
|
|
182
|
+
<Else>
|
|
183
|
+
<p>请先登录</p>
|
|
184
|
+
</Else>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
### 6. 列表渲染
|
|
190
|
+
|
|
191
|
+
```html
|
|
192
|
+
<!-- 基本 -->
|
|
193
|
+
<ul>
|
|
194
|
+
<For each="$data.users" item="user" index="i">
|
|
195
|
+
<li>{{ i + 1 }}. {{ user.name }}</li>
|
|
196
|
+
</For>
|
|
197
|
+
</ul>
|
|
198
|
+
|
|
199
|
+
<!-- 带唯一 key(推荐) -->
|
|
200
|
+
<For each="$data.products" item="p">
|
|
201
|
+
<div class="item" s-data-id="p.id">{{ p.name }}</div>
|
|
202
|
+
</For>
|
|
203
|
+
|
|
204
|
+
<!-- 嵌套循环 -->
|
|
205
|
+
<For each="$data.categories" item="cat">
|
|
206
|
+
<h3>{{ cat.name }}</h3>
|
|
207
|
+
<ul>
|
|
208
|
+
<For each="cat.items" item="it">
|
|
209
|
+
<li>{{ it }}</li>
|
|
210
|
+
</For>
|
|
211
|
+
</ul>
|
|
212
|
+
</For>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
### 7. 动态类
|
|
218
|
+
|
|
219
|
+
```html
|
|
220
|
+
<!-- 对象 -->
|
|
221
|
+
<div s-class="{ active: $data.isActive, error: $data.err }"></div>
|
|
222
|
+
|
|
223
|
+
<!-- 数组 -->
|
|
224
|
+
<div s-class="[$data.base, $data.isActive ? 'on' : 'off']"></div>
|
|
225
|
+
|
|
226
|
+
<!-- 字符串 -->
|
|
227
|
+
<div s-class="$data.statusClass"></div>
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
### 8. 动态样式
|
|
233
|
+
|
|
234
|
+
```html
|
|
235
|
+
<!-- 基本 -->
|
|
236
|
+
<div s-style="{ color: $data.c, fontSize: $data.fs + 'px' }"></div>
|
|
237
|
+
|
|
238
|
+
<!-- 条件 -->
|
|
239
|
+
<div s-style="{ backgroundColor: $data.ok ? '#0f0' : '#f00' }"></div>
|
|
240
|
+
|
|
241
|
+
<!-- 直接绑对象 -->
|
|
242
|
+
<div s-style="$data.styleObj"></div>
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
### 9. 表达式限制
|
|
248
|
+
|
|
249
|
+
- 支持任意**纯 JS 表达式**;
|
|
250
|
+
- 禁止 `eval`、`Function`、`setTimeout`、`setInterval` 等副作用代码;
|
|
251
|
+
- 绑定函数在每次渲染都会执行,请保持**纯函数**以保证性能。
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 响应式数据
|
|
256
|
+
|
|
257
|
+
框架通过 `this.$data` 提供深度响应式代理。
|
|
258
|
+
|
|
259
|
+
```ts
|
|
260
|
+
// 推荐:构造函数一次性注入,首帧无闪烁
|
|
261
|
+
class MyComponent extends BaseElement<{ count: number; user: { name: string } }> {
|
|
262
|
+
constructor() {
|
|
263
|
+
super({ count: 0, user: { name: 'John' } })
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
// 兼容:生命周期里赋值
|
|
268
|
+
created() { this.$data = { ... } }
|
|
269
|
+
async onInit() {
|
|
270
|
+
const user = await fetch('/api/user').then(r => r.json())
|
|
271
|
+
this.$data = { count: 0, user }
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
特性
|
|
276
|
+
|
|
277
|
+
- 嵌套对象/数组全部递归代理
|
|
278
|
+
- 批量异步更新,避免频繁渲染
|
|
279
|
+
- 支持路径过滤(`filter`):可监听特定数据路径变化
|
|
280
|
+
- 支持深度比较(`deepCompare`):避免不必要的重复触发
|
|
281
|
+
- 支持节流控制(`throttle`):自定义更新频率
|
|
282
|
+
- 提供变更路径信息:精确追踪数据变化位置
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
## 自定义元素
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
import { BaseElement, CustomElement } from 'solely'
|
|
290
|
+
|
|
291
|
+
// 最简单组件
|
|
292
|
+
@CustomElement({ tagName: 'my-card', template: `<p>{{ $data.txt }}</p>` })
|
|
293
|
+
class MyCard extends BaseElement<{ txt: string }> {
|
|
294
|
+
constructor() { super({ txt: 'hi' }) }
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
// 影子 DOM + 内联样式
|
|
298
|
+
@CustomElement({
|
|
299
|
+
tagName: 'styled-card',
|
|
300
|
+
template: `<div class="box">{{ $data.txt }}</div>`,
|
|
301
|
+
styles: `.box{ color: red; }`,
|
|
302
|
+
shadowDOM: { use: true }
|
|
303
|
+
})
|
|
304
|
+
class StyledCard extends BaseElement<{ txt: string }> {
|
|
305
|
+
onInit() { this.$data = { txt: 'shadow' } }
|
|
306
|
+
}
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
使用
|
|
310
|
+
|
|
311
|
+
```html
|
|
312
|
+
<my-card></my-card>
|
|
313
|
+
<styled-card></styled-card>
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## 组件通信
|
|
319
|
+
|
|
320
|
+
| 方式 | 示例 |
|
|
321
|
+
|---|---|
|
|
322
|
+
| 属性下行 | `<child s-$data="$data.message"></child>` |
|
|
323
|
+
| 事件上行 | 子 `this.dispatchEvent(new CustomEvent('update', {detail, bubbles:true}))` <br> 父 `<child on-update="this.handleUpdate(event)">` |
|
|
324
|
+
| 全局 Store | 任意单例 class / Context 均可,框架无侵入 |
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
## 生命周期(按顺序)
|
|
329
|
+
|
|
330
|
+
| 钩子 | 触发时机 | 用途 |
|
|
331
|
+
|---|---|---|
|
|
332
|
+
| `constructor()` | 实例创建 | 通过 `super(data)` 一次性注入响应式状态(推荐) |
|
|
333
|
+
| `created()` | 构造函数结束后微任务 | 同步初始化,首帧前执行 |
|
|
334
|
+
| `connectedCallback()` | 元素连接到 DOM | **内部使用**,负责样式注入和首次渲染,请勿重写 |
|
|
335
|
+
| `beforeUpdate()` | 每次数据变更 → DOM 更新前 | 可读取新数据,准备更新 |
|
|
336
|
+
| `mounted()` | 首次 DOM 更新完成后 | 访问真实 DOM |
|
|
337
|
+
| `onInit()` | 首次 `mounted()` 后立即调用 | 兼容旧组件的初始化钩子,可用于依赖 DOM 或异步接口的操作 |
|
|
338
|
+
| `updated()` | 后续每次 DOM 更新完成后 | 依赖 DOM 的后处理 |
|
|
339
|
+
| `disconnectedCallback()` | 元素从 DOM 移除 | **内部使用**,负责清理和调用 `unmounted()`,请勿重写 |
|
|
340
|
+
| `unmounted()` | 组件卸载时 | 清理定时器 / 事件监听器,防止内存泄漏 |
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## 路由(hash 模式)
|
|
345
|
+
|
|
346
|
+
```ts
|
|
347
|
+
const routes = [
|
|
348
|
+
{ path: 'home', tagName: 'home-page' },
|
|
349
|
+
{ path: 'user/:id', tagName: 'user-page' },
|
|
350
|
+
{
|
|
351
|
+
path: 'dashboard',
|
|
352
|
+
tagName: 'dashboard-layout',
|
|
353
|
+
children: [
|
|
354
|
+
{ path: 'profile', tagName: 'profile-page' },
|
|
355
|
+
{ path: 'settings', tagName: 'settings-page' }
|
|
356
|
+
]
|
|
357
|
+
}
|
|
358
|
+
]
|
|
359
|
+
|
|
360
|
+
class App extends BaseElement {
|
|
361
|
+
constructor() {
|
|
362
|
+
super({ routes })
|
|
363
|
+
}
|
|
364
|
+
}
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
```html
|
|
368
|
+
<nav>
|
|
369
|
+
<a href="#/home">首页</a>
|
|
370
|
+
<a href="#/user/123">用户</a>
|
|
371
|
+
</nav>
|
|
372
|
+
<router-view s-$routes="$data.routes"></router-view>
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
在组件内通过 `this.params.id` 获取动态段。
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## 性能与最佳实践
|
|
380
|
+
|
|
381
|
+
- 避免在模板里做重计算 / 副作用函数
|
|
382
|
+
- 高频事件(scroll / input)自行节流
|
|
383
|
+
- 批量更新已内置,无需手动 `$nextTick`
|
|
384
|
+
- 自定义元素名称 **必须含连字符**
|
|
385
|
+
- 元素被移除时请在 `unmounted()` 内解绑事件 / 清定时器
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## 目录结构
|
|
390
|
+
|
|
391
|
+
```
|
|
392
|
+
src/ 核心源码(base/、utils/、solely.ts)
|
|
393
|
+
dist/ 构建产物(ESM、UMD、*.d.ts)
|
|
394
|
+
examples/ 官方示例(组件、路由、模板标签等)
|
|
395
|
+
tests/ 单元测试(Vitest + JSDOM)
|
|
396
|
+
public/ 静态资源
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## 脚本命令
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
npm run dev # Vite 开发服务器,热更新
|
|
405
|
+
npm run build # 编译 TypeScript & 打包到 dist/
|
|
406
|
+
npm run preview # 本地预览构建结果
|
|
407
|
+
npm run test # 单元测试
|
|
408
|
+
npm run test:ui # Vitest UI 交互模式
|
|
409
|
+
npm run test:coverage # 生成覆盖率报告
|
|
410
|
+
npm run link # 全局 link,供其他项目本地引用
|
|
411
|
+
npm run pack:local # 生成 solely-<ver>.tgz,file: 引用
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## 浏览器支持
|
|
417
|
+
|
|
418
|
+
- **ES2020 + 原生 Web Components**
|
|
419
|
+
- 最近 2 个主版本的 Chrome / Edge / Firefox / Safari
|
|
420
|
+
- **不支持 IE**;旧环境请自行加 polyfill 并降级编译
|
|
421
|
+
|
|
422
|
+
---
|
|
423
|
+
|
|
424
|
+
## 常见问题(FAQ)
|
|
425
|
+
|
|
426
|
+
| 问题 | 答复 |
|
|
427
|
+
|---|---|
|
|
428
|
+
| 必须先写 `this.` 吗? | 模板中可省略,直接写 `$data.xxx` |
|
|
429
|
+
| 什么时候用 Shadow DOM? | 需要样式/结构隔离时,在 `@CustomElement({shadowDOM: { use: true }})` 开启 |
|
|
430
|
+
| 能给子组件传对象吗? | 可以,用 `s-对象='json-string'` 或在父组件里直接 `querySelector('child').$data = {...}` |
|
|
431
|
+
| 路由能否用 history 模式? | 当前仅实现 hash 模式,history 模式可自行扩展 |
|
|
432
|
+
| 如何调试响应式数据? | 浏览器 DevTools 控制台直接 `document.querySelector('my-el').$data` 即可读写 |
|
|
433
|
+
| 如何在组件中获取路由参数? | 路由参数会自动作为组件属性传入,可通过 `this.$data.id` 或直接使用 `id` 获取(如路径为 `/user/:id`) |
|
|
434
|
+
|
|
435
|
+
---
|
|
436
|
+
|
|
437
|
+
## 贡献指南
|
|
438
|
+
|
|
439
|
+
1. Fork 仓库并创建特性分支
|
|
440
|
+
2. 保持代码风格一致,补充对应测试与文档
|
|
441
|
+
3. 运行 `npm run test` 确保通过
|
|
442
|
+
4. 对公共 API 的变更请遵循 **SemVer**
|
|
443
|
+
5. 提交 Pull Request,标题注明 `feat:` / `fix:` / `docs:` 等
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## 版本与发布
|
|
448
|
+
|
|
449
|
+
- 当前版本:**0.0.28**
|
|
450
|
+
- 遵循语义化版本(SemVer)
|
|
451
|
+
- 构建产物位于 `dist/`,`package.json` 的 `"module"` 指向 `dist/solely.js`,类型声明 `dist/solely.d.ts`
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
455
|
+
## 许可证
|
|
456
|
+
|
|
457
|
+
MIT License
|