solely 0.1.0 → 0.1.2

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
@@ -2,7 +2,7 @@
2
2
 
3
3
  <div align="center">
4
4
 
5
- ![Solely Logo](./public/solely.svg)
5
+ <img src="https://raw.githubusercontent.com/solelyjs/solely/main/public/solely.svg" alt="Solely Logo" width="180" />
6
6
 
7
7
  **一个轻量级、现代化的 Web 组件开发框架**
8
8
 
@@ -296,7 +296,7 @@ Solely 采用模块化设计,主要由以下部分组成:
296
296
 
297
297
  ```
298
298
  solely/
299
- ├── compiler/ # 模板编译器
299
+ ├── compiler/ # 模板编译器
300
300
  │ ├── ir/ # 中间表示层
301
301
  │ └── parser/ # AST 解析器
302
302
  ├── runtime/ # 运行时核心
@@ -328,7 +328,7 @@ solely/
328
328
  @CustomElement({
329
329
  tagName: 'my-component', // 必须:组件标签名
330
330
  template: '...', // 必须:HTML 模板字符串
331
- props: [...], // 可选:属性定义
331
+ props: [...], // 可选:属性定义,设置后会自动同步到 $data 中,外部修改会触发响应式
332
332
  styles: '...', // 可选:组件样式
333
333
  shadowDOM: { use: true } // 可选:使用 Shadow DOM
334
334
  })
@@ -341,6 +341,78 @@ class MyComponent extends BaseElement<MyData> {
341
341
 
342
342
  组件的基类,提供响应式属性、生命周期钩子和渲染方法。
343
343
 
344
+ #### 属性设置方式
345
+
346
+ Solely 支持两种属性设置方式:
347
+
348
+ 1. **静态属性设置** (`attr="value"`):
349
+ - 语法:`attr="value"`
350
+ - 作用:设置普通 HTML attribute,值为字符串
351
+ - 行为:**只有在组件的 `props` 中定义的属性**才会自动同步到组件的 `$data` 中,外部修改会触发响应式更新
352
+ - 示例:`<my-component title="Hello"></my-component>`(需在组件的 `props` 中定义 `title`)
353
+
354
+ 2. **动态属性绑定** (`:attr="表达式"`):
355
+ - 语法:`:attr="表达式"`
356
+ - 作用:绑定动态表达式的值
357
+ - 行为:**不会自动触发响应式更新**,需要用户自己实现 `get`/`set` 方法来处理响应式逻辑
358
+ - 注意:如果需要在元素定义前设置该属性,需要在 `upgradeProps` 中添加,以防止属性失效
359
+ - 示例:`<my-component :title="$data.pageTitle"></my-component>`
360
+
361
+ #### Upgrade Property
362
+
363
+ `upgradeProps` 是一个静态属性,用于指定需要在元素定义前设置的属性列表,确保这些属性的 getter/setter 能够正常工作:
364
+
365
+ **示例**:
366
+
367
+ ```typescript
368
+ // 1. 创建元素实例(此时自定义元素尚未注册)
369
+ const element = document.createElement('my-component');
370
+
371
+ // 2. 设置属性(此时属性会直接成为实例属性,不会触发 getter/setter)
372
+ element.value = 'initial value';
373
+ element.disabled = true;
374
+
375
+ // 3. 定义自定义元素
376
+ class MyComponent extends BaseElement<{ value: string; disabled: boolean }> {
377
+ static upgradeProps = ['value', 'disabled']; // 指定需要升级的属性
378
+
379
+ constructor() {
380
+ super({ value: '', disabled: false });
381
+ }
382
+
383
+ // 假设我们有自定义的 getter/setter
384
+ get value() {
385
+ return this.$data.value;
386
+ }
387
+
388
+ set value(newValue) {
389
+ this.$data.value = newValue;
390
+ console.log('Value changed:', newValue);
391
+ }
392
+
393
+ get disabled() {
394
+ return this.$data.disabled;
395
+ }
396
+
397
+ set disabled(newValue) {
398
+ this.$data.disabled = newValue;
399
+ console.log('Disabled changed:', newValue);
400
+ }
401
+ }
402
+
403
+ // 4. 注册自定义元素
404
+ customElements.define('my-component', MyComponent);
405
+
406
+ // 5. 添加到 DOM
407
+ document.body.appendChild(element);
408
+ // 此时,upgradeProps 会确保之前设置的属性重新通过 getter/setter 进行设置
409
+ // 控制台会输出:
410
+ // Value changed: initial value
411
+ // Disabled changed: true
412
+ ```
413
+
414
+ **作用**:当元素在自定义元素注册前就被设置了属性时,这些属性会直接成为元素的实例属性,而不会触发自定义元素的 getter/setter。通过 `upgradeProps` 可以确保这些属性在元素注册后重新通过 getter/setter 进行设置,从而保证属性的响应式功能正常工作。
415
+
344
416
  #### 生命周期钩子
345
417
 
346
418
  Solely 提供了完整的生命周期钩子函数,用于在组件的不同阶段执行自定义逻辑:
@@ -349,13 +421,90 @@ Solely 提供了完整的生命周期钩子函数,用于在组件的不同阶
349
421
  |---|---|---|
350
422
  | `created()` | 组件实例创建后 | 在组件构造函数执行完成后调用,此时组件尚未挂载到 DOM |
351
423
  | `mounted()` | 组件挂载到 DOM 后 | 组件首次渲染完成后调用,可在此进行 DOM 操作 |
424
+ | `onInit()` | 组件初始化后 | 在 `mounted()` 之后调用,支持返回 Promise,适用于需要异步初始化的场景 |
352
425
  | `beforeUpdate()` | 数据更新前 | 在组件数据更新导致重新渲染前调用 |
353
426
  | `updated()` | 数据更新后 | 在组件数据更新导致重新渲染后调用 |
354
- | `unmounted()` | 组件从 DOM 移除后 | 组件被销毁时调用,可在此清理资源 |
355
- | `attributeChanged(name, oldValue, newValue)` | 属性变化时 | 当组件的观察属性发生变化时调用 |
356
427
  | `beforeAttributesUpdate()` | 属性更新前 | 在属性更新导致重新渲染前调用 |
357
428
  | `afterAttributesUpdate()` | 属性更新后 | 在属性更新导致重新渲染后调用 |
358
- | `onInit()` | 组件初始化后 | 组件挂载完成后调用,支持异步操作 |
429
+ | `attributeChanged(name, oldValue, newValue)` | 属性变化时 | 当组件的观察属性发生变化时调用,参数分别为属性名、旧值和新值 |
430
+ | `unmounted()` | 组件从 DOM 移除后 | 组件被销毁时调用,可在此清理资源 |
431
+
432
+ #### 生命周期调用顺序
433
+
434
+ 1. **组件创建阶段**:`created()` → `mounted()` → `onInit()`
435
+ 2. **数据更新阶段**:`beforeUpdate()` → 渲染更新 → `updated()`
436
+ 3. **属性更新阶段**:`attributeChanged()` → `beforeAttributesUpdate()` → 渲染更新 → `updated()` → `afterAttributesUpdate()`
437
+ 4. **组件销毁阶段**:`unmounted()`
438
+
439
+ #### 模板级生命周期钩子
440
+
441
+ Solely 支持在组件模板的普通元素上定义生命周期钩子,用于在元素的挂载和更新时执行自定义逻辑:
442
+
443
+ | 钩子属性 | 调用时机 | 说明 |
444
+ |---|---|---|
445
+ | `mounted` | 元素挂载后 | 在元素首次渲染完成后调用,可调用组件方法并接收元素本身作为参数 |
446
+ | `updated` | 元素更新后 | 在元素数据更新导致重新渲染后调用,可调用组件方法并接收元素本身作为参数 |
447
+
448
+ **示例**:
449
+
450
+ ```html
451
+ <!-- 组件模板中 -->
452
+ <label mounted="this.onOptionMounted(el)" updated="this.onOptionUpdated(el)">步长:</label>
453
+ ```
454
+
455
+ ```typescript
456
+ // 组件类中
457
+ class MyComponent extends BaseElement<MyData> {
458
+ // 元素挂载时调用
459
+ onOptionMounted(label: HTMLLabelElement) {
460
+ console.log('Label mounted:', label);
461
+ }
462
+
463
+ // 元素更新时调用
464
+ onOptionUpdated(label: HTMLLabelElement) {
465
+ console.log('Label updated:', label);
466
+ }
467
+ }
468
+ ```
469
+
470
+ **说明**:
471
+ - 钩子属性中可以使用 `this` 访问组件实例
472
+ - 钩子函数会接收元素本身作为参数(通过 `el` 变量)
473
+ - 可以在钩子中调用组件的方法,实现更复杂的逻辑
474
+ - 这些钩子是针对模板中的具体元素的,与组件级生命周期钩子是分开的
475
+
476
+ #### 元素引用 (ref)
477
+
478
+ Solely 支持在模板元素上使用 `ref` 属性来获取元素引用,方便在组件中直接访问 DOM 元素:
479
+
480
+ **示例**:
481
+
482
+ ```html
483
+ <!-- 组件模板中 -->
484
+ <input ref="usernameInput" type="text" placeholder="请输入用户名">
485
+ <button ref="submitButton" @click="this.handleSubmit()">提交</button>
486
+ ```
487
+
488
+ ```typescript
489
+ // 组件类中
490
+ class MyComponent extends BaseElement<MyData> {
491
+ // 处理提交
492
+ handleSubmit() {
493
+ // 通过 $refs 访问元素
494
+ const username = this.$refs.usernameInput.value;
495
+ console.log('提交的用户名:', username);
496
+
497
+ // 可以直接操作 DOM 元素
498
+ this.$refs.submitButton.disabled = true;
499
+ }
500
+ }
501
+ ```
502
+
503
+ **说明**:
504
+ - 在模板元素上添加 `ref="名称"` 属性
505
+ - 在组件中通过 `this.$refs.名称` 访问对应的 DOM 元素
506
+ - 支持在任何模板元素上使用,包括原生 HTML 元素和自定义组件
507
+ - 元素挂载后即可通过 `$refs` 访问
359
508
 
360
509
  #### 示例代码
361
510