solely 0.1.5 → 0.1.7

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
@@ -474,6 +474,7 @@ class MyComponent extends BaseElement<MyData> {
474
474
  ```
475
475
 
476
476
  **说明**:
477
+
477
478
  - 钩子属性中可以使用 `this` 访问组件实例
478
479
  - 钩子函数会接收元素本身作为参数(通过 `el` 变量)
479
480
  - 可以在钩子中调用组件的方法,实现更复杂的逻辑
@@ -507,6 +508,7 @@ class MyComponent extends BaseElement<MyData> {
507
508
  ```
508
509
 
509
510
  **说明**:
511
+
510
512
  - 在模板元素上添加 `ref="名称"` 属性
511
513
  - 在组件中通过 `this.$refs.名称` 访问对应的 DOM 元素
512
514
  - 支持在任何模板元素上使用,包括原生 HTML 元素和自定义组件
@@ -587,6 +589,41 @@ const state = observe({
587
589
  state.name = 'New Name'; // 触发回调
588
590
  ```
589
591
 
592
+ #### 特殊对象处理
593
+
594
+ 响应式系统会自动处理以下特殊情况:
595
+
596
+ | 对象类型 | 处理方式 | 说明 |
597
+ |---|---|---|
598
+ | `Object.freeze()` | 跳过代理 | 被冻结的对象不会被代理,直接返回原对象 |
599
+ | `Object.seal()` | 跳过代理 | 被密封的对象不会被代理,直接返回原对象 |
600
+ | `File` / `Blob` | 跳过代理 | 浏览器原生文件对象不会被代理 |
601
+ | `FormData` | 跳过代理 | 表单数据对象不会被代理 |
602
+ | `ArrayBuffer` | 跳过代理 | 二进制数据缓冲区不会被代理 |
603
+ | `Response` / `Request` | 跳过代理 | Fetch API 对象不会被代理 |
604
+
605
+ **示例**:
606
+
607
+ ```typescript
608
+ // 冻结对象不会被代理
609
+ const frozen = Object.freeze({ count: 0 });
610
+ const state = observe({ frozen }, (change) => {
611
+ console.log('变化:', change);
612
+ });
613
+
614
+ // 修改冻结对象的属性不会触发回调
615
+ state.frozen.count = 1; // 静默失败,无回调
616
+
617
+ // File 对象不会被代理
618
+ const file = new File(['content'], 'test.txt');
619
+ const state2 = observe({ file }, (change) => {
620
+ console.log('变化:', change);
621
+ });
622
+
623
+ // File 对象保持原样
624
+ console.log(state2.file instanceof File); // true
625
+ ```
626
+
590
627
  ### 路由系统
591
628
 
592
629
  Solely 提供了功能强大的内置路由系统,支持单页应用开发,包括路由定义、导航、参数传递、路由守卫等功能。
@@ -2,11 +2,25 @@ import { ASTNode, IRRoot } from '../../types';
2
2
  /**
3
3
  * 将 s-model 转换成 :value / @input / @change
4
4
  * 在 AST → IR 转换前调用
5
+ * @param node AST 节点
5
6
  */
6
7
  export declare function transformModel(node: ASTNode): void;
8
+ /** 构建 IR 的选项 */
7
9
  export interface BuildIROptions {
10
+ /** 源代码字符串 */
8
11
  source?: string;
12
+ /** 文件名 */
9
13
  filename?: string;
10
14
  }
15
+ /**
16
+ * 构建 IR(中间表示)
17
+ * @param ast AST 节点数组
18
+ * @param options 构建选项
19
+ * @returns IR 根节点
20
+ */
11
21
  export declare function buildIR(ast: ASTNode[], options?: BuildIROptions): IRRoot;
22
+ /**
23
+ * 清除 IR 编译缓存
24
+ * @param filename 指定文件名,不传则清除所有缓存
25
+ */
12
26
  export declare function clearIRCache(filename?: string): void;
@@ -1,5 +1,7 @@
1
1
  import { ASTNode } from '../../types';
2
2
  /**
3
3
  * 主解析函数:生成最简单的 AST
4
+ * @param html HTML 字符串
5
+ * @returns AST 节点数组
4
6
  */
5
7
  export declare function parseHtml(html: string): ASTNode[];