solely 0.0.29 → 0.1.0

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 (52) hide show
  1. package/README.md +817 -507
  2. package/dist/compiler/index.d.ts +2 -0
  3. package/dist/compiler/ir/buildIR.d.ts +12 -0
  4. package/dist/compiler/ir/index.d.ts +1 -0
  5. package/dist/compiler/parser/index.d.ts +1 -0
  6. package/dist/compiler/parser/parser.d.ts +5 -0
  7. package/dist/index.d.ts +4 -0
  8. package/dist/index.js +1756 -0
  9. package/dist/index.umd.cjs +47 -0
  10. package/dist/plugin.d.ts +1 -0
  11. package/dist/plugins/html-parse-precompile.d.ts +1 -0
  12. package/dist/plugins/html-precompile.d.ts +1 -0
  13. package/dist/plugins/index.d.ts +1 -0
  14. package/dist/runtime/component/base-element.d.ts +24 -0
  15. package/dist/{base → runtime/component}/decorators.d.ts +6 -4
  16. package/dist/runtime/component/index.d.ts +2 -0
  17. package/dist/runtime/index.d.ts +4 -0
  18. package/dist/runtime/reactivity/index.d.ts +2 -0
  19. package/dist/runtime/reactivity/observe.d.ts +47 -0
  20. package/dist/{utils/observe.d.ts → runtime/reactivity/types.d.ts} +0 -8
  21. package/dist/runtime/renderer/index.d.ts +1 -0
  22. package/dist/runtime/renderer/renderIR.d.ts +25 -0
  23. package/dist/runtime/router/core.d.ts +42 -0
  24. package/dist/runtime/router/index.d.ts +6 -0
  25. package/dist/runtime/router/router-link.d.ts +17 -0
  26. package/dist/runtime/router/router-view.d.ts +25 -0
  27. package/dist/runtime/router/types.d.ts +65 -0
  28. package/dist/shared/event-listeners.d.ts +2 -0
  29. package/dist/shared/gen-function.d.ts +3 -0
  30. package/dist/shared/index.d.ts +6 -0
  31. package/dist/shared/templateError.d.ts +9 -0
  32. package/dist/types/ast.d.ts +38 -0
  33. package/dist/types/component.d.ts +66 -0
  34. package/dist/types/index.d.ts +4 -0
  35. package/dist/types/ir.d.ts +67 -0
  36. package/dist/types/lifecycle.d.ts +4 -0
  37. package/dist/types/loop.d.ts +4 -0
  38. package/package.json +24 -6
  39. package/dist/base/base-element.d.ts +0 -56
  40. package/dist/base/index.d.ts +0 -5
  41. package/dist/base/router-view.d.ts +0 -43
  42. package/dist/solely.d.ts +0 -2
  43. package/dist/solely.js +0 -928
  44. package/dist/solely.umd.cjs +0 -3
  45. package/dist/utils/ast-processor.d.ts +0 -2
  46. package/dist/utils/async-queue.d.ts +0 -1
  47. package/dist/utils/event-listeners.d.ts +0 -2
  48. package/dist/utils/html-parse.d.ts +0 -45
  49. package/dist/utils/index.d.ts +0 -8
  50. /package/dist/{utils → shared}/functions.d.ts +0 -0
  51. /package/dist/{utils → shared}/is-object.d.ts +0 -0
  52. /package/dist/{utils → shared}/url.d.ts +0 -0
package/README.md CHANGED
@@ -1,507 +1,817 @@
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
- ### 插槽(Slots)支持
319
-
320
- 当 shadowDOM 功能处于开启状态时,该组件支持使用标准的 Web Components 插槽功能,并允许对插槽名称进行动态修改。
321
-
322
- ```ts
323
- // 带插槽的组件
324
- @CustomElement({
325
- tagName: 'my-layout',
326
- template: `
327
- <header><slot name="header"></slot></header>
328
- <main><slot></slot></main>
329
- <footer><slot s-name="$data.footerSlotName"></slot></footer>
330
- `,
331
- shadowDOM: { use: true },
332
- styles: `
333
- header, footer { background: #f0f0f0; padding: 10px; }
334
- main { padding: 20px; }
335
- `
336
- })
337
- class MyLayout extends BaseElement<{ footerSlotName: string }> {
338
- constructor() {
339
- super({ footerSlotName: 'default-footer' })
340
- }
341
-
342
- // 动态修改插槽名称
343
- changeFooterSlot() {
344
- this.$data.footerSlotName = 'custom-footer'
345
- }
346
- }
347
- ```
348
-
349
- ```html
350
- <my-layout>
351
- <!-- 命名插槽 -->
352
- <h1 slot="header">页面标题</h1>
353
-
354
- <!-- 默认插槽 -->
355
- <p>这是页面内容...</p>
356
-
357
- <!-- 动态插槽 -->
358
- <div slot="default-footer">默认页脚</div>
359
- <div slot="custom-footer">自定义页脚</div>
360
- </my-layout>
361
- ```
362
-
363
- 使用动态插槽时,通过 `s-name="$data.slotName"` 语法绑定动态插槽名称,当数据变化时,插槽内容会自动重新分配。
364
-
365
- ---
366
-
367
- ## 组件通信
368
-
369
- | 方式 | 示例 |
370
- |---|---|
371
- | 属性下行 | `<child s-$data="$data.message"></child>` |
372
- | 事件上行 | 子 `this.dispatchEvent(new CustomEvent('update', {detail, bubbles:true}))` <br> 父 `<child on-update="this.handleUpdate(event)">` |
373
- | 全局 Store | 任意单例 class / Context 均可,框架无侵入 |
374
-
375
- ---
376
-
377
- ## 生命周期(按顺序)
378
-
379
- | 钩子 | 触发时机 | 用途 |
380
- |---|---|---|
381
- | `constructor()` | 实例创建 | 通过 `super(data)` 一次性注入响应式状态(推荐) |
382
- | `created()` | 构造函数结束后微任务 | 同步初始化,首帧前执行 |
383
- | `connectedCallback()` | 元素连接到 DOM | **内部使用**,负责样式注入和首次渲染,请勿重写 |
384
- | `beforeUpdate()` | 每次数据变更 → DOM 更新前 | 可读取新数据,准备更新 |
385
- | `mounted()` | 首次 DOM 更新完成后 | 访问真实 DOM |
386
- | `onInit()` | 首次 `mounted()` 后立即调用 | 兼容旧组件的初始化钩子,可用于依赖 DOM 或异步接口的操作 |
387
- | `updated()` | 后续每次 DOM 更新完成后 | 依赖 DOM 的后处理 |
388
- | `disconnectedCallback()` | 元素从 DOM 移除 | **内部使用**,负责清理和调用 `unmounted()`,请勿重写 |
389
- | `unmounted()` | 组件卸载时 | 清理定时器 / 事件监听器,防止内存泄漏 |
390
-
391
- ---
392
-
393
- ## 路由(hash 模式)
394
-
395
- ```ts
396
- const routes = [
397
- { path: 'home', tagName: 'home-page' },
398
- { path: 'user/:id', tagName: 'user-page' },
399
- {
400
- path: 'dashboard',
401
- tagName: 'dashboard-layout',
402
- children: [
403
- { path: 'profile', tagName: 'profile-page' },
404
- { path: 'settings', tagName: 'settings-page' }
405
- ]
406
- }
407
- ]
408
-
409
- class App extends BaseElement {
410
- constructor() {
411
- super({ routes })
412
- }
413
- }
414
- ```
415
-
416
- ```html
417
- <nav>
418
- <a href="#/home">首页</a>
419
- <a href="#/user/123">用户</a>
420
- </nav>
421
- <router-view s-$routes="$data.routes"></router-view>
422
- ```
423
-
424
- 在组件内通过 `this.params.id` 获取动态段。
425
-
426
- ---
427
-
428
- ## 性能与最佳实践
429
-
430
- - 避免在模板里做重计算 / 副作用函数
431
- - 高频事件(scroll / input)自行节流
432
- - 批量更新已内置,无需手动 `$nextTick`
433
- - 自定义元素名称 **必须含连字符**
434
- - 元素被移除时请在 `unmounted()` 内解绑事件 / 清定时器
435
-
436
- ---
437
-
438
- ## 目录结构
439
-
440
- ```
441
- src/ 核心源码(base/、utils/、solely.ts)
442
- dist/ 构建产物(ESM、UMD、*.d.ts)
443
- examples/ 官方示例(组件、路由、模板标签等)
444
- tests/ 单元测试(Vitest + JSDOM)
445
- public/ 静态资源
446
- ```
447
-
448
- ---
449
-
450
- ## 脚本命令
451
-
452
- ```bash
453
- npm run dev # Vite 开发服务器,热更新
454
- npm run build # 编译 TypeScript & 打包到 dist/
455
- npm run preview # 本地预览构建结果
456
- npm run test # 单元测试
457
- npm run test:ui # Vitest UI 交互模式
458
- npm run test:coverage # 生成覆盖率报告
459
- npm run link # 全局 link,供其他项目本地引用
460
- npm run pack:local # 生成 solely-<ver>.tgz,file: 引用
461
- ```
462
-
463
- ---
464
-
465
- ## 浏览器支持
466
-
467
- - **ES2020 + 原生 Web Components**
468
- - 最近 2 个主版本的 Chrome / Edge / Firefox / Safari
469
- - **不支持 IE**;旧环境请自行加 polyfill 并降级编译
470
-
471
- ---
472
-
473
- ## 常见问题(FAQ)
474
-
475
- | 问题 | 答复 |
476
- |---|---|
477
- | 必须先写 `this.` 吗? | 模板中可省略,直接写 `$data.xxx` |
478
- | 什么时候用 Shadow DOM? | 需要样式/结构隔离时,在 `@CustomElement({shadowDOM: { use: true }})` 开启 |
479
- | 组件支持插槽(Slots)吗? | 是的,当 shadowDOM 功能处于开启状态时,支持标准 Web Components 插槽功能,并允许使用 `s-name="$data.slotName"` 语法动态修改插槽名称 |
480
- | 能给子组件传对象吗? | 可以,用 `s-对象='json-string'` 或在父组件里直接 `querySelector('child').$data = {...}` |
481
- | 路由能否用 history 模式? | 当前仅实现 hash 模式,history 模式可自行扩展 |
482
- | 如何调试响应式数据? | 浏览器 DevTools 控制台直接 `document.querySelector('my-el').$data` 即可读写 |
483
- | 如何在组件中获取路由参数? | 路由参数会自动作为组件属性传入,可通过 `this.$data.id` 或直接使用 `id` 获取(如路径为 `/user/:id`) |
484
-
485
- ---
486
-
487
- ## 贡献指南
488
-
489
- 1. Fork 仓库并创建特性分支
490
- 2. 保持代码风格一致,补充对应测试与文档
491
- 3. 运行 `npm run test` 确保通过
492
- 4. 对公共 API 的变更请遵循 **SemVer**
493
- 5. 提交 Pull Request,标题注明 `feat:` / `fix:` / `docs:` 等
494
-
495
- ---
496
-
497
- ## 版本与发布
498
-
499
- - 当前版本:**0.0.29**
500
- - 遵循语义化版本(SemVer)
501
- - 构建产物位于 `dist/`,`package.json` 的 `"module"` 指向 `dist/solely.js`,类型声明 `dist/solely.d.ts`
502
-
503
- ---
504
-
505
- ## 许可证
506
-
507
- MIT License
1
+ # Solely - 轻量级 Web 组件框架
2
+
3
+ <div align="center">
4
+
5
+ ![Solely Logo](./public/solely.svg)
6
+
7
+ **一个轻量级、现代化的 Web 组件开发框架**
8
+
9
+ [![npm version](https://img.shields.io/npm/v/solely.svg)](https://www.npmjs.com/package/solely)
10
+ [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
12
+
13
+ </div>
14
+
15
+ ## ✨ 核心特性
16
+
17
+ - **🚀 高性能**:轻量级架构,零运行时依赖,快速渲染
18
+ - **🔧 类型安全**:完整的 TypeScript 支持,类型提示完善
19
+ - **🎨 强大模板**:基于 AST 的模板编译,支持条件渲染和列表渲染
20
+ - **⚡ 响应式系统**:高效的响应式数据绑定,自动追踪依赖
21
+ - **🧩 Web 组件**:原生 Web 组件支持,可自定义元素
22
+ - **📦 插件系统**:灵活的插件扩展机制
23
+ - **🧪 测试完善**:完整的单元测试覆盖
24
+ - **🗺️ 路由支持**:内置路由系统,支持单页应用开发
25
+
26
+ ## 📦 安装
27
+
28
+ ```bash
29
+ # 使用 npm
30
+ npm install solely
31
+
32
+ # 使用 yarn
33
+ yarn add solely
34
+
35
+ # 使用 pnpm
36
+ pnpm add solely
37
+ ```
38
+
39
+ ## 🎯 快速开始
40
+
41
+ ### 1. 创建一个简单的组件
42
+
43
+ 创建一个 TypeScript 文件:
44
+
45
+ ```typescript
46
+ // counter.ts
47
+ import { BaseElement, CustomElement } from 'solely';
48
+
49
+ @CustomElement({
50
+ tagName: 'my-counter',
51
+ template: `
52
+ <div class="counter">
53
+ <h2>计数器: {{ $data.count }}</h2>
54
+ <button @click="$data.count++">增加</button>
55
+ </div>
56
+ `,
57
+ props: [
58
+ { name: 'count', type: 'number' }
59
+ ],
60
+ styles: `
61
+ .counter {
62
+ text-align: center;
63
+ padding: 20px;
64
+ }
65
+ button {
66
+ padding: 10px 20px;
67
+ font-size: 16px;
68
+ cursor: pointer;
69
+ }
70
+ `
71
+ })
72
+ class MyCounter extends BaseElement<{ count: number }> {
73
+ constructor() {
74
+ super({ count: 0 });
75
+ }
76
+ }
77
+ ```
78
+
79
+ ### 2. 在 HTML 中使用
80
+
81
+ ```html
82
+ <!-- index.html -->
83
+ <!DOCTYPE html>
84
+ <html lang="zh-CN">
85
+ <head>
86
+ <meta charset="UTF-8">
87
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
88
+ <title>Solely 示例</title>
89
+ <script type="module" src="./counter.ts"></script>
90
+ </head>
91
+ <body>
92
+ <my-counter></my-counter>
93
+ </body>
94
+ </html>
95
+ ```
96
+
97
+ ## 📚 模板语法
98
+
99
+ 所有模板必须是 **合法 HTML**;框架会提前编译成高效更新函数,无运行时解析开销。
100
+
101
+ ### 语法对照表
102
+
103
+ | 功能 | 推荐语法 | 兼容语法 | 完整示例 |
104
+ |---|---|---|---|
105
+ | **文本插值** | `{{ 表达式 }}` | `{{ 表达式 }}` | `<span>{{ $data.msg }}</span>` |
106
+ | **属性绑定** | `:属性名="表达式"` | `s-属性名="表达式"` | `<img :src="$data.url" s-alt="$data.name">` |
107
+ | **布尔属性** | `:属性名="表达式"` | `s-属性名="表达式"` | `<button :disabled="$data.loading">提交</button>` |
108
+ | **双向绑定** | `s-model="字段路径"` | `s-model="字段路径"` | `<input s-model="$data.username">` |
109
+ | **原始事件** | `@事件名="语句"` | `on-事件名="语句"` | `<button @click="$data.count++">增加</button>` |
110
+ | **条件渲染** | `<If test="表达式">` | `<If condition="表达式">` | `<If test="$data.ok"><p>成功</p></If>` |
111
+ | **列表渲染** | `<For each="数组" item="项变量">` | `<For each="数组" item="项变量">` | `<For each="$data.list" item="it">{{ it }}</For>` |
112
+ | **动态类** | `:class="对象/数组/字符串"` | `s-class="对象/数组/字符串"` | `<div :class="{ active: $data.isActive }">` |
113
+ | **动态样式** | `:style="对象"` | `s-style="对象"` | `<div :style="{ color: $data.c }">` |
114
+
115
+ ### 详细语法说明
116
+
117
+ #### 1. 文本插值
118
+
119
+ 使用 `{{ 表达式 }}` 在模板中插入动态文本:
120
+
121
+ ```html
122
+ <h1>Hello, {{ $data.name }}!</h1>
123
+ <p>总数: {{ $data.items.length }}</p>
124
+ <p>{{ $data.price * $data.quantity }}</p>
125
+ ```
126
+
127
+ #### 2. 属性绑定
128
+
129
+ 使用 `:属性名` 绑定动态属性(推荐):
130
+
131
+ ```html
132
+ <img :src="$data.imageUrl" :alt="$data.imageAlt">
133
+ <a :href="$data.linkUrl">访问链接</a>
134
+ ```
135
+
136
+ 兼容语法:
137
+
138
+ ```html
139
+ <img s-src="$data.imageUrl" s-alt="$data.imageAlt">
140
+ <a s-href="$data.linkUrl">访问链接</a>
141
+ ```
142
+
143
+ #### 3. 布尔属性
144
+
145
+ 当表达式为真值时才会输出属性:
146
+
147
+ ```html
148
+ <button :disabled="$data.isLoading">提交</button>
149
+ <input :checked="$data.isAgreed">
150
+ ```
151
+
152
+ 兼容语法:
153
+
154
+ ```html
155
+ <button s-disabled="$data.isLoading">提交</button>
156
+ <input s-checked="$data.isAgreed">
157
+ ```
158
+
159
+ #### 4. 双向绑定
160
+
161
+ 使用 `s-model` 实现表单双向绑定(推荐):
162
+
163
+ ```html
164
+ <input s-model="$data.username">
165
+ <textarea s-model="$data.content"></textarea>
166
+ <select s-model="$data.selectedId">
167
+ <option value="1">选项1</option>
168
+ <option value="2">选项2</option>
169
+ </select>
170
+ ```
171
+
172
+ 兼容语法:
173
+
174
+ ```html
175
+ <input s-model="$data.username">
176
+ <textarea s-model="$data.content"></textarea>
177
+ <select s-model="$data.selectedId">
178
+ <option value="1">选项1</option>
179
+ <option value="2">选项2</option>
180
+ </select>
181
+ ```
182
+
183
+ #### 5. 事件处理
184
+
185
+ 使用 `@事件名` 绑定事件,可直接读写 `$data`(推荐):
186
+
187
+ ```html
188
+ <button @click="$data.count++">增加</button>
189
+ <button @click="$data.items.push($data.newItem); $data.newItem=''">添加</button>
190
+ <input @input="$data.searchText = event.target.value">
191
+ ```
192
+
193
+ 兼容语法:
194
+
195
+ ```html
196
+ <button onclick="$data.count++">增加</button>
197
+ <button onclick="$data.items.push($data.newItem); $data.newItem=''">添加</button>
198
+ <input oninput="$data.searchText = event.target.value">
199
+ ```
200
+
201
+ #### 6. 条件渲染
202
+
203
+ 使用 `<If>`、`<ElseIf>`、`<Else>` 进行条件渲染:
204
+
205
+ ```html
206
+ <If test="$data.isLoggedIn">
207
+ <p>欢迎回来,{{ $data.username }}!</p>
208
+ </If>
209
+ <ElseIf test="$data.isLoading">
210
+ <p>加载中...</p>
211
+ </ElseIf>
212
+ <Else>
213
+ <p>请登录</p>
214
+ </Else>
215
+ ```
216
+
217
+ 兼容语法:
218
+
219
+ ```html
220
+ <If condition="$data.isLoggedIn">
221
+ <p>欢迎回来,{{ $data.username }}!</p>
222
+ </If>
223
+ <ElseIf condition="$data.isLoading">
224
+ <p>加载中...</p>
225
+ </ElseIf>
226
+ <Else>
227
+ <p>请登录</p>
228
+ </Else>
229
+ ```
230
+
231
+ #### 7. 列表渲染
232
+
233
+ 使用 `<For>` 渲染列表:
234
+
235
+ ```html
236
+ <ul>
237
+ <For each="$data.items" item="item" index="i">
238
+ <li>{{ i + 1 }}. {{ item.name }}</li>
239
+ </For>
240
+ </ul>
241
+ ```
242
+
243
+ 兼容语法:
244
+
245
+ ```html
246
+ <ul>
247
+ <For each="$data.items" item="item" index="i">
248
+ <li>{{ i + 1 }}. {{ item.name }}</li>
249
+ </For>
250
+ </ul>
251
+ ```
252
+
253
+ #### 8. 动态类
254
+
255
+ 使用 `:class` 动态控制 CSS 类(推荐):
256
+
257
+ ```html
258
+ <div :class="{ active: $data.isActive, 'has-error': $data.hasError }">
259
+ 内容
260
+ </div>
261
+ <!-- 也支持数组和字符串 -->
262
+ <div :class="[$data.class1, $data.class2]">内容</div>
263
+ ```
264
+
265
+ 兼容语法:
266
+
267
+ ```html
268
+ <div s-class="{ active: $data.isActive, 'has-error': $data.hasError }">
269
+ 内容
270
+ </div>
271
+ <!-- 也支持数组和字符串 -->
272
+ <div s-class="[$data.class1, $data.class2]">内容</div>
273
+ ```
274
+
275
+ #### 9. 动态样式
276
+
277
+ 使用 `:style` 动态设置样式(推荐):
278
+
279
+ ```html
280
+ <div :style="{ color: $data.textColor, fontSize: $data.fontSize + 'px' }">
281
+ 动态样式
282
+ </div>
283
+ ```
284
+
285
+ 兼容语法:
286
+
287
+ ```html
288
+ <div s-style="{ color: $data.textColor, fontSize: $data.fontSize + 'px' }">
289
+ 动态样式
290
+ </div>
291
+ ```
292
+
293
+ ## 🏗️ 技术架构
294
+
295
+ Solely 采用模块化设计,主要由以下部分组成:
296
+
297
+ ```
298
+ solely/
299
+ ├── compiler/ # 模板编译器
300
+ │ ├── ir/ # 中间表示层
301
+ │ └── parser/ # AST 解析器
302
+ ├── runtime/ # 运行时核心
303
+ │ ├── component/ # 组件基类和装饰器
304
+ │ ├── reactivity/ # 响应式系统
305
+ │ ├── renderer/ # 渲染器
306
+ │ └── router/ # 路由系统
307
+ ├── shared/ # 共享工具函数
308
+ ├── types/ # TypeScript 类型定义
309
+ ├── plugins/ # 插件系统
310
+ └── tests/ # 测试文件
311
+ ```
312
+
313
+ ### 核心模块说明
314
+
315
+ 1. **编译器**:将模板转换为高效的渲染函数,支持 AST 解析和中间表示优化
316
+ 2. **运行时**:包含组件系统、响应式系统、渲染器和路由系统
317
+ 3. **响应式系统**:基于 Proxy 的响应式数据绑定,自动追踪依赖
318
+ 4. **路由系统**:支持单页应用的路由管理,包括路由定义、导航和组件挂载
319
+ 5. **插件系统**:提供扩展机制,支持自定义功能
320
+
321
+ ## 🔧 API 参考
322
+
323
+ ### CustomElement 装饰器
324
+
325
+ 组件的注册装饰器,用于定义组件的元信息:
326
+
327
+ ```typescript
328
+ @CustomElement({
329
+ tagName: 'my-component', // 必须:组件标签名
330
+ template: '...', // 必须:HTML 模板字符串
331
+ props: [...], // 可选:属性定义
332
+ styles: '...', // 可选:组件样式
333
+ shadowDOM: { use: true } // 可选:使用 Shadow DOM
334
+ })
335
+ class MyComponent extends BaseElement<MyData> {
336
+ // 组件逻辑
337
+ }
338
+ ```
339
+
340
+ ### BaseElement
341
+
342
+ 组件的基类,提供响应式属性、生命周期钩子和渲染方法。
343
+
344
+ #### 生命周期钩子
345
+
346
+ Solely 提供了完整的生命周期钩子函数,用于在组件的不同阶段执行自定义逻辑:
347
+
348
+ | 钩子函数 | 调用时机 | 说明 |
349
+ |---|---|---|
350
+ | `created()` | 组件实例创建后 | 在组件构造函数执行完成后调用,此时组件尚未挂载到 DOM |
351
+ | `mounted()` | 组件挂载到 DOM 后 | 组件首次渲染完成后调用,可在此进行 DOM 操作 |
352
+ | `beforeUpdate()` | 数据更新前 | 在组件数据更新导致重新渲染前调用 |
353
+ | `updated()` | 数据更新后 | 在组件数据更新导致重新渲染后调用 |
354
+ | `unmounted()` | 组件从 DOM 移除后 | 组件被销毁时调用,可在此清理资源 |
355
+ | `attributeChanged(name, oldValue, newValue)` | 属性变化时 | 当组件的观察属性发生变化时调用 |
356
+ | `beforeAttributesUpdate()` | 属性更新前 | 在属性更新导致重新渲染前调用 |
357
+ | `afterAttributesUpdate()` | 属性更新后 | 在属性更新导致重新渲染后调用 |
358
+ | `onInit()` | 组件初始化后 | 组件挂载完成后调用,支持异步操作 |
359
+
360
+ #### 示例代码
361
+
362
+ ```typescript
363
+ class MyComponent extends BaseElement<MyData> {
364
+ constructor() {
365
+ super({ /* 初始数据 */ });
366
+ }
367
+
368
+ // 组件实例创建后调用
369
+ created() {
370
+ console.log('组件实例已创建');
371
+ }
372
+
373
+ // 组件挂载到 DOM 后调用
374
+ mounted() {
375
+ console.log('组件已挂载到 DOM');
376
+ // 可在此进行 DOM 操作
377
+ }
378
+
379
+ // 数据更新前调用
380
+ beforeUpdate() {
381
+ console.log('组件即将更新');
382
+ }
383
+
384
+ // 数据更新后调用
385
+ updated() {
386
+ console.log('组件已更新');
387
+ }
388
+
389
+ // 组件从 DOM 移除后调用
390
+ unmounted() {
391
+ console.log('组件已卸载');
392
+ // 可在此清理资源
393
+ }
394
+
395
+ // 属性变化时调用
396
+ attributeChanged(name, oldValue, newValue) {
397
+ console.log(`属性 ${name} 从 ${oldValue} 变为 ${newValue}`);
398
+ }
399
+
400
+ // 组件初始化后调用,支持异步操作
401
+ async onInit() {
402
+ console.log('组件初始化中');
403
+ // 可在此进行异步操作,如数据获取
404
+ await fetchData();
405
+ console.log('组件初始化完成');
406
+ }
407
+ }
408
+ ```
409
+
410
+ #### 核心方法
411
+
412
+ | 方法 | 说明 | 参数 | 返回值 |
413
+ |---|---|---|---|
414
+ | `$data` | 获取/设置组件数据 | 新数据对象(设置时) | 当前数据对象 |
415
+ | `refresh()` | 手动触发组件刷新 | 无 | 无 |
416
+ | `emit(eventName, detail, options)` | 派发自定义事件 | eventName: 事件名<br>detail: 事件详情<br>options: 事件选项 | 无 |
417
+
418
+ ### observe
419
+
420
+ 创建响应式数据对象,用于非组件场景的响应式数据:
421
+
422
+ ```typescript
423
+ import { observe } from 'solely';
424
+
425
+ const state = observe({
426
+ name: 'Solely',
427
+ items: [1, 2, 3]
428
+ }, (path, newValue, oldValue) => {
429
+ console.log('数据变化:', path, oldValue, '->', newValue);
430
+ });
431
+
432
+ state.name = 'New Name'; // 触发回调
433
+ ```
434
+
435
+ ### 路由系统
436
+
437
+ Solely 提供了功能强大的内置路由系统,支持单页应用开发,包括路由定义、导航、参数传递、路由守卫等功能。
438
+
439
+ #### 路由配置
440
+
441
+ 首先,定义路由配置:
442
+
443
+ ```typescript
444
+ import { createRouter } from 'solely';
445
+
446
+ const routes = [
447
+ { path: '/', tagName: 'home-page' },
448
+ { path: '/about', tagName: 'about-page' },
449
+ { path: '/users/:id', tagName: 'user-detail' },
450
+ { path: '*', tagName: 'not-found' } // 404 页面
451
+ ];
452
+
453
+ const router = createRouter({
454
+ routes,
455
+ base: '/', // 基础路径
456
+ mode: 'history' // 路由模式:'hash' | 'history'
457
+ });
458
+
459
+ // 启动路由监听
460
+ router.setupListeners();
461
+ ```
462
+
463
+ #### 路由配置选项
464
+
465
+ | 选项 | 类型 | 说明 | 示例 |
466
+ |---|---|---|---|
467
+ | `path` | `string` | 路由路径,支持动态参数 | `'/users/:id'` |
468
+ | `tagName` | `string` | 组件标签名 | `'user-detail'` |
469
+ | `component` | `Function` | 异步组件加载函数 | `() => import('./pages/user.js')` |
470
+ | `name` | `string` | 路由名称 | `'user'` |
471
+ | `keepAlive` | `boolean` | 是否缓存组件实例 | `true` |
472
+ | `forceReload` | `boolean` | 是否强制重新加载 | `true` |
473
+ | `redirect` | `string` | 重定向路径 | `'/login'` |
474
+ | `props` | `Object` | 传递给组件的属性 | `{ title: '用户详情' }` |
475
+ | `meta` | `Object` | 路由元信息 | `{ requiresAuth: true }` |
476
+ | `children` | `RouteConfig[]` | 嵌套子路由 | `[{ path: 'profile', tagName: 'user-profile' }]` |
477
+
478
+ #### 路由导航
479
+
480
+ 使用路由方法进行页面导航:
481
+
482
+ ```typescript
483
+ // 基本导航
484
+ router.push('/about');
485
+
486
+ // 替换当前历史记录
487
+ router.replace('/about');
488
+
489
+ // 带查询参数
490
+ router.pushWithQuery('/search', { q: 'solely', page: '1' });
491
+
492
+ // 返回上一页
493
+ router.back();
494
+
495
+ // 解析路径为真实 URL
496
+ const url = router.resolve('/users/1'); // 根据模式返回 #/users/1 或 /users/1
497
+ ```
498
+
499
+ #### 路由参数
500
+
501
+ 获取路由参数:
502
+
503
+ ```typescript
504
+ // 获取当前路由信息
505
+ const currentRoute = router.getCurrentRoute();
506
+
507
+ if (currentRoute) {
508
+ // 获取路径参数
509
+ console.log(currentRoute.params.id); // 从 /users/:id 中获取 id
510
+
511
+ // 获取查询参数
512
+ console.log(currentRoute.query.q); // 从 ?q=solely 中获取 q
513
+
514
+ // 获取完整路径
515
+ console.log(currentRoute.fullPath); // /users/123?q=solely
516
+
517
+ // 获取路由元信息
518
+ console.log(currentRoute.meta); // { requiresAuth: true }
519
+
520
+ // 获取匹配的路由层级
521
+ console.log(currentRoute.matched); // 匹配的路由数组
522
+ }
523
+ ```
524
+
525
+ #### 路由守卫
526
+
527
+ Solely 支持全局路由守卫,用于控制导航流程:
528
+
529
+ ```typescript
530
+ // 创建路由时配置守卫
531
+ const router = createRouter({
532
+ routes,
533
+ beforeEach: async (to, from) => {
534
+ // 验证权限
535
+ if (to.meta.requiresAuth && !isLoggedIn) {
536
+ return '/login'; // 重定向到登录页
537
+ }
538
+
539
+ // 阻止导航
540
+ if (to.path === '/admin' && !isAdmin) {
541
+ return false;
542
+ }
543
+
544
+ // 允许导航
545
+ return true;
546
+ },
547
+ afterEach: (to, from) => {
548
+ // 导航完成后执行
549
+ console.log('从', from.fullPath, '导航到', to.fullPath);
550
+ document.title = to.meta.title || 'Solely App';
551
+ }
552
+ });
553
+ ```
554
+
555
+ #### 嵌套路由
556
+
557
+ Solely 支持嵌套路由,实现复杂的页面结构:
558
+
559
+ ```typescript
560
+ const routes = [
561
+ {
562
+ path: '/user',
563
+ tagName: 'user-layout',
564
+ children: [
565
+ { path: 'profile', tagName: 'user-profile' },
566
+ { path: 'settings', tagName: 'user-settings' },
567
+ { path: ':id', tagName: 'user-detail' }
568
+ ]
569
+ }
570
+ ];
571
+
572
+ // 对应的 URL:
573
+ // /user/profile
574
+ // /user/settings
575
+ // /user/123
576
+ ```
577
+
578
+ #### 异步路由
579
+
580
+ 支持异步组件加载,实现代码分割:
581
+
582
+ ```typescript
583
+ const routes = [
584
+ {
585
+ path: '/dashboard',
586
+ component: async () => {
587
+ const module = await import('./pages/dashboard.js');
588
+ return module.default; // 返回包含 tagName 的对象
589
+ }
590
+ }
591
+ ];
592
+ ```
593
+
594
+ #### 路由缓存
595
+
596
+ 使用 `keepAlive` 选项缓存组件实例,提升切换性能:
597
+
598
+ ```typescript
599
+ const routes = [
600
+ {
601
+ path: '/profile',
602
+ tagName: 'user-profile',
603
+ keepAlive: true // 缓存组件实例
604
+ }
605
+ ];
606
+ ```
607
+
608
+ #### 路由模式
609
+
610
+ Solely 支持两种路由模式:
611
+
612
+ | 模式 | 说明 | URL 格式 | 适用场景 |
613
+ |---|---|---|---|
614
+ | `hash` | 基于 URL hash | `#/users/123` | 兼容旧浏览器,无需服务器配置 |
615
+ | `history` | 基于 HTML5 History API | `/users/123` | 更美观的 URL,需要服务器支持 |
616
+
617
+ ```typescript
618
+ // Hash 模式(默认)
619
+ const router = createRouter({
620
+ routes,
621
+ mode: 'hash'
622
+ });
623
+
624
+ // History 模式
625
+ const router = createRouter({
626
+ routes,
627
+ mode: 'history',
628
+ base: '/app' // 应用基础路径
629
+ });
630
+ ```
631
+
632
+ #### 路由监听
633
+
634
+ 监听路由变化:
635
+
636
+ ```typescript
637
+ // 添加监听器
638
+ const unsubscribe = router.listen(() => {
639
+ console.log('路由已变化');
640
+ });
641
+
642
+ // 移除监听器
643
+ unsubscribe();
644
+ ```
645
+
646
+ #### 路由组件
647
+
648
+ Solely 提供了两个内置的路由组件:
649
+
650
+ **router-link**
651
+
652
+ ```html
653
+ <!-- 基本用法 -->
654
+ <router-link to="/about">关于我们</router-link>
655
+
656
+ <!-- 带激活状态 -->
657
+ <router-link to="/users" active-class="active">用户列表</router-link>
658
+
659
+ <!-- 精确匹配 -->
660
+ <router-link to="/users" exact>用户列表</router-link>
661
+
662
+ <!-- 自定义链接内容 -->
663
+ <router-link to="/profile">
664
+ <img src="avatar.png" alt="个人资料">
665
+ <span>个人资料</span>
666
+ </router-link>
667
+
668
+ <!-- 自定义模式(移除 a 标签包裹) -->
669
+ <router-link to="/dashboard" custom>
670
+ <button @click="event.preventDefault()">仪表盘</button>
671
+ </router-link>
672
+
673
+ <!-- 预加载路由 -->
674
+ <router-link to="/heavy-page" prefetch>重型页面</router-link>
675
+ ```
676
+
677
+ **router-view**
678
+
679
+ ```html
680
+ <!-- 基本用法 -->
681
+ <router-view></router-view>
682
+
683
+ <!-- 嵌套路由视图 -->
684
+ <div class="layout">
685
+ <aside>
686
+ <router-link to="/user/profile">个人资料</router-link>
687
+ <router-link to="/user/settings">设置</router-link>
688
+ </aside>
689
+ <main>
690
+ <router-view></router-view>
691
+ </main>
692
+ </div>
693
+ ```
694
+
695
+ #### 路由匹配规则
696
+
697
+ Solely 的路由匹配遵循以下优先级:
698
+
699
+ 1. **精确匹配**:完全匹配路径
700
+ 2. **动态参数**:`/users/:id` 匹配 `/users/123`
701
+ 3. **通配符**:`*` 匹配所有未匹配的路径
702
+
703
+ ```typescript
704
+ const routes = [
705
+ { path: '/users', tagName: 'user-list' }, // 精确匹配 /users
706
+ { path: '/users/:id', tagName: 'user-detail' }, // 匹配 /users/123
707
+ { path: '*', tagName: 'not-found' } // 匹配所有其他路径
708
+ ];
709
+ ```
710
+
711
+ #### 路由元信息
712
+
713
+ 使用路由元信息存储自定义数据:
714
+
715
+ ```typescript
716
+ const routes = [
717
+ {
718
+ path: '/admin',
719
+ tagName: 'admin-panel',
720
+ meta: {
721
+ requiresAuth: true,
722
+ requiresAdmin: true,
723
+ title: '管理面板'
724
+ }
725
+ }
726
+ ];
727
+
728
+ // 在守卫中使用
729
+ beforeEach: (to, from) => {
730
+ if (to.meta.requiresAuth && !isLoggedIn) {
731
+ return '/login';
732
+ }
733
+ }
734
+ ```
735
+
736
+ ## 📖 示例项目
737
+
738
+ 查看 [examples](./examples) 目录获取更多示例:
739
+
740
+ - **计数器示例** (`examples/counter/`) - 基础交互示例
741
+ - **待办事项示例** (`examples/todo/`) - 列表管理和状态示例
742
+ - **表单示例** (`examples/form/`) - 表单处理和验证示例
743
+ - **天气示例** (`examples/weather/`) - 异步数据获取示例
744
+
745
+ ### 运行示例
746
+
747
+ ```bash
748
+ # 安装依赖
749
+ npm install
750
+
751
+ # 启动开发服务器
752
+ npm run dev
753
+
754
+ # 访问示例
755
+ # 打开浏览器访问 http://localhost:5173/examples/
756
+ ```
757
+
758
+ ## 🧪 测试
759
+
760
+ ```bash
761
+ # 运行所有测试
762
+ npm test
763
+
764
+ # 运行测试并查看 UI
765
+ npm run test:ui
766
+
767
+ # 生成测试覆盖率报告
768
+ npm run test:coverage
769
+ ```
770
+
771
+ ## 🔧 构建和开发
772
+
773
+ ```bash
774
+ # 构建生产版本
775
+ npm run build
776
+
777
+ # 本地预览构建结果
778
+ npm run preview
779
+
780
+ # 全局链接(用于本地测试)
781
+ npm run link
782
+
783
+ # 本地打包(用于其他项目引用)
784
+ npm run pack:local
785
+ ```
786
+
787
+ ## 🤝 贡献指南
788
+
789
+ 欢迎贡献代码!请遵循以下步骤:
790
+
791
+ 1. **Fork 仓库**:在 GitHub 上 fork 本项目
792
+ 2. **克隆仓库**:`git clone https://github.com/your-username/solely.git`
793
+ 3. **创建分支**:`git checkout -b feature/your-feature`
794
+ 4. **安装依赖**:`npm install`
795
+ 5. **开发和测试**:编写代码并运行测试
796
+ 6. **提交代码**:`git commit -m "Add your feature"`
797
+ 7. **推送到远程**:`git push origin feature/your-feature`
798
+ 8. **创建 Pull Request**:在 GitHub 上创建 PR
799
+
800
+ ### 代码规范
801
+
802
+ - 遵循 TypeScript 编码规范
803
+ - 确保所有测试通过
804
+ - 保持代码风格一致
805
+ - 提供清晰的注释
806
+
807
+ ## 📄 许可证
808
+
809
+ 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
810
+
811
+ ## 🙏 致谢
812
+
813
+ 感谢所有为这个项目做出贡献的人!
814
+
815
+ ---
816
+
817
+ **Happy Coding with Solely! 🚀**