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/README.md CHANGED
@@ -1,275 +1,457 @@
1
- # Solely
2
-
3
- ## 项目简介
4
-
5
- 在当今的软件开发领域,前端框架的选择对于项目的成功至关重要。我们注意到,市面上的许多前端框架虽然功能强大,但往往过于复杂,与原生JavaScript(JS)或TypeScript(TS)的写法差异较大,这不仅增加了开发者的学习成本,也不利于技术的积累和迁移。特别是对于小型项目,这些框架的全面性反而导致了资源的浪费,因为它们往往包含了许多项目并不需要的复杂功能。
6
-
7
- 为了解决这一问题,我们开发了一款简单而高效的前端框架。它的核心优势在于:
8
-
9
- 1. **简化复杂性**:我们的框架设计简洁,易于上手,与原生JS/TS的写法保持一致,便于技术积累。
10
- 2. **专注核心功能**:针对小型项目,我们的框架专注于提供必要的响应式功能,避免了不必要的功能堆砌,从而减少了项目的臃肿。
11
- 3. **性能优化**:轻量级的设计减少了资源消耗,提高了项目运行效率。
12
- 4. **技术兼容性**:与原生JS/TS的高兼容性,使得开发者可以在不同项目间轻松迁移和应用技术。
13
- 5. **高度定制性**:根据项目需求灵活定制功能,避免功能浪费。
14
-
15
- 我们致力于持续优化框架,确保它能够适应不断变化的前端开发需求,并根据用户反馈进行调整和改进。我们的目标是提供一个既满足小型项目需求,又不牺牲性能和易用性的前端解决方案。
16
-
17
- ## 安装
18
-
19
- ```shell
20
- npm i solely
21
- ```
22
-
23
- ## 语法规则
24
-
25
- ### 响应式数据
26
-
27
- Solely 中内置了响应式数据 `$data`,每当 `$data` 中的数据更改时,页面也会同步更新。
28
-
29
- ### 模板语法
30
-
31
- Solely 使用基于 HTML 的模板语法,能够精准地将数据绑定到呈现的 DOM 上。所有模板都是语法正确的 HTML,可被标准的浏览器和 HTML 解析器顺利解析。
32
-
33
- ### 文本插值
34
-
35
- 文本插值是最基础的数据绑定形式,使用双大括号语法。在这些语法中,`this` 指向 `Element` 实例。为了简化书写,可以省略 `$data` 前面的 `this`,两种写法在功能上等同:
36
-
37
- ```html
38
- <div>消息: {{ this.$data.msg }}</div>
39
- <div>消息: {{ $data.msg }}</div>
40
- ```
41
-
42
- 双大括号标签会被替换为 `Element` 实例中 `$data.msg` 的值。同时,每次 `$data.msg` 属性更改时,它也会同步更新。
43
-
44
- ### Attribute 绑定
45
-
46
- 双大括号不能在 HTML attributes 中使用。想要响应式地绑定一个 attribute,应该使用 `s-[attribute]` 指令,即在需要绑定的属性前面添加 `s-` 前缀:
47
-
48
- ```html
49
- <div s-id="$data.id"></div>
50
- ```
51
-
52
- `s-[attribute]` 指令指示 Solely 将元素的 `id` attribute 与组件的 `$data.id` 属性保持一致。
53
-
54
- **注意:** `s-[attribute]` 也可以用于 Class 与 Style 绑定,如 `s-class`、`s-style` 等。
55
-
56
- ### 布尔型 Attribute
57
-
58
- 布尔型 attribute 依据 `true` / `false` 值来决定 attribute 是否应该存在于该元素上。如:`checked`、`disabled`、`readOnly`、`selected` 等。`s-[attribute]` 在这种场景下的行为略有不同:
59
-
60
- ```html
61
- <button s-disabled="$data.disabled">Button</button>
62
- ```
63
-
64
- 当 `$data.disabled` 为真值时,元素会包含这个 `disabled` attribute。而当其为其他假值时,attribute 将被忽略。
65
-
66
- ### 使用 JavaScript 表达式
67
-
68
- Solely 在所有的数据绑定中都支持 JavaScript 表达式,除了 `eval`、`Function`、`setTimeout`、`setInterval` 等部分不安全代码。
69
-
70
- ```html
71
- <div>{{ $data.number + 1 }}</div>
72
- <div>{{ $data.ok ? 'YES' : 'NO' }}</div>
73
- <div>{{ this.getMessage() }}</div>
74
- ```
75
-
76
- ```ts
77
- @CustomElement({
78
- tagName: "sample-message",
79
- template: template,
80
- })
81
- export class SampleMessage extends BaseElement {
82
- constructor() {
83
- super();
84
- }
85
-
86
- async onInit() {
87
- this.$data = {
88
- number: 1,
89
- ok: true,
90
- };
91
- }
92
-
93
- getMessage() {
94
- return "message";
95
- }
96
- }
97
- ```
98
-
99
- **注意:** 绑定在表达式中的方法在组件每次更新时都会被重新调用,因此不应该产生任何副作用,比如改变数据或触发异步操作。
100
-
101
- ### 事件绑定
102
-
103
- Solely 采用与标签中直接绑定事件相同的方式,不需要进行额外的处理。与文本插值和 Attribute 绑定相同,`this` 和 `$data` 也已经内置,不同的是,`value` 也可以直接被使用。
104
-
105
- ```html
106
- <button onclick="$data.count++">Add 1</button>
107
- <input
108
- type="search"
109
- placeholder="搜索"
110
- s-value="$data.searchText"
111
- onchange="$data.searchText=value"
112
- />
113
- <button onclick="this.search()">搜索</button>
114
- ```
115
-
116
- ### 双向绑定(Model)
117
-
118
- 通过 `s-model` 指令实现表单元素与数据的双向绑定:
119
-
120
- ```html
121
- <input type="text" s-model="$data.message">
122
- <select s-model="$data.selected">
123
- <option value="A">选项A</option>
124
- </select>
125
- ```
126
-
127
- 支持的表单元素:
128
-
129
- - `<input>` (text/checkbox/radio)
130
- - `<textarea>`
131
- - `<select>`
132
-
133
- **注意:** 双向绑定的表达式只支持 `$data` 中的属性。基于这个特性,你也可以省略 `$data` ,直接使用对应的属性,如 `$data.selected` 可以省略成 `selected`。
134
-
135
- ```html
136
- <input type="text" s-model="$data.message">
137
- <select s-model="selected">
138
- <option value="A">选项A</option>
139
- </select>
140
- ```
141
-
142
- ### 条件判断
143
-
144
- Solely 引入了 `<If>` 标签,基于 `condition` 关键字绑定的表达式值的真假性,有条件地渲染元素或模板片段。该标签不会在 HTML 中渲染,只控制内部元素的展示。
145
-
146
- ```html
147
- <If condition="$data.if">
148
- <div>内容1</div>
149
- <div>内容2</div>
150
- <div>内容3</div>
151
- </If>
152
- ```
153
-
154
- ### 列表渲染
155
-
156
- Solely 引入了 `<For>` 标签,根据由 `each` 关键字绑定的表达式值返回的数组来渲染列表。`item` 关键字是迭代的别名,默认为 `item`,但可以通过为其赋值进行修改。标签内部的元素可以使用 `item` 关键字绑定的内容,使用 `index` 关键字绑定内容的索引。该标签不会在 HTML 中渲染,只控制内部元素的展示。
157
-
158
- ```html
159
- <For each="$data.f" item="i">
160
- <For each="$data.e">
161
- <div>For 外层 {{i}} 内层 {{item}}</div>
162
- <button onclick="this.onClick(i,item)">点击</button>
163
- </For>
164
- </For>
165
- <!-- 使用index指定索引 -->
166
- <For each="$data.pages" item="page" index="i"></For>
167
- ```
168
-
169
- ### 类绑定
170
-
171
- 支持三种形式实现动态类绑定:
172
-
173
- 1. **对象语法**:
174
-
175
- ```html
176
- <div s-class="{ active: $data.isActive, 'text-danger': $data.hasError }"></div>
177
- ```
178
-
179
- 2. **字符串语法**:
180
-
181
- ```html
182
- <div s-class="static-class dynamic-class"></div>
183
- ```
184
-
185
- 3. **数组语法**:
186
-
187
- ```html
188
- <div s-class="[$data.class1, $data.class2, { highlight: $data.isHighlight }]"></div>
189
- ```
190
-
191
- ### 样式绑定
192
-
193
- 支持三种形式实现动态样式绑定:
194
-
195
- 1. **对象语法**(支持嵌套对象):
196
-
197
- ```html
198
- <div s-style="{
199
- color: $data.textColor,
200
- fontSize: $data.fontSize + 'px',
201
- border: {
202
- width: '1px',
203
- style: 'solid'
204
- }
205
- }"></div>
206
- ```
207
-
208
- 2. **字符串语法**:
209
-
210
- ```html
211
- <div s-style="color: red; font-size: 14px;"></div>
212
- ```
213
-
214
- 3. **数组语法**(支持混合类型):
215
-
216
- ```html
217
- <div s-style="[$data.baseStyles, { padding: $data.padding + 'px' }]"></div>
218
- ```
219
-
220
- ### 自定义元素
221
-
222
- 通过继承 `BaseElement` 创建自定义组件:
223
-
224
- ```ts
225
- import { BaseElement, CustomElement } from "solely";
226
-
227
- @CustomElement({
228
- tagName: "my-component",
229
- template: `<div>{{ $data.count }}</div>`
230
- })
231
- class MyComponent extends BaseElement {
232
- onInit() {
233
- this.$data = { count: 0 };
234
- }
235
- }
236
- ```
237
-
238
- ### 生命周期
239
-
240
- 组件生命周期方法:
241
-
242
- - `onInit()`: 组件初始化时调用
243
-
244
- ### 注意事项
245
-
246
- 1. **性能优化**:
247
-
248
- - 避免在模板表达式中进行复杂计算
249
- - 列表渲染始终为 `<For>` 元素添加唯一的 `key` 属性
250
-
251
- 2. **命名空间**:
252
-
253
- SVG 元素会自动应用 `svg` 命名空间:
254
-
255
- ```html
256
- <svg s-width="$data.size">
257
- <circle cx="50" cy="50" r="40"/>
258
- </svg>
259
- ```
260
-
261
- 3. **组件通信**:
262
-
263
- 通过自定义事件实现父子组件通信:
264
-
265
- ```ts
266
- // 触发事件
267
- this.dispatchEvent(new CustomEvent('update', { detail: value }));
268
-
269
- // 监听事件
270
- <my-component onupdate="console.log(event.detail)"></my-component>
271
- ```
272
-
273
- ## 许可证
274
-
275
- MIT License
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