solely 0.1.6 → 0.1.8
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 +81 -1
- package/dist/compiler/ir/buildIR.d.ts +14 -0
- package/dist/compiler/parser/parser.d.ts +2 -0
- package/dist/index.js +662 -596
- package/dist/index.umd.cjs +11 -10
- package/dist/runtime/component/decorators.d.ts +19 -0
- package/dist/runtime/reactivity/index.d.ts +2 -2
- package/dist/runtime/reactivity/observe.d.ts +27 -1
- package/dist/runtime/renderer/renderIR.d.ts +13 -0
- package/dist/runtime/router/core.d.ts +13 -0
- package/dist/shared/env.d.ts +4 -0
- package/dist/shared/functions.d.ts +7 -0
- package/dist/shared/gen-function.d.ts +4 -1
- package/dist/shared/index.d.ts +1 -0
- package/dist/shared/is-object.d.ts +5 -0
- package/dist/shared/url.d.ts +2 -2
- package/dist/types/ast.d.ts +10 -0
- package/dist/types/ir.d.ts +31 -0
- package/dist/types/lifecycle.d.ts +12 -0
- package/dist/types/loop.d.ts +3 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
- **🎨 强大模板**:基于 AST 的模板编译,支持条件渲染和列表渲染
|
|
20
20
|
- **⚡ 响应式系统**:高效的响应式数据绑定,自动追踪依赖
|
|
21
21
|
- **🧩 Web 组件**:原生 Web 组件支持,可自定义元素
|
|
22
|
+
- **🛡️ 安全可靠**:编译时模板固定,自动 HTML 转义,内置 XSS 防护机制
|
|
22
23
|
- **📦 插件系统**:灵活的插件扩展机制
|
|
23
24
|
- **🧪 测试完善**:完整的单元测试覆盖
|
|
24
25
|
- **🗺️ 路由支持**:内置路由系统,支持单页应用开发
|
|
@@ -28,6 +29,8 @@
|
|
|
28
29
|
- [快速开始指南](./docs/guide.md) - 从零开始学习 Solely
|
|
29
30
|
- [API 文档](./docs/api.md) - 完整的 API 参考
|
|
30
31
|
- [示例项目](./examples/) - 实际应用示例
|
|
32
|
+
- [安全机制说明](#安全机制) - 了解框架的 XSS 防护机制
|
|
33
|
+
- [安全演示](./examples/security-demo/) - 查看 XSS 防护实际效果
|
|
31
34
|
|
|
32
35
|
## 📦 安装
|
|
33
36
|
|
|
@@ -324,7 +327,46 @@ solely/
|
|
|
324
327
|
4. **路由系统**:支持单页应用的路由管理,包括路由定义、导航和组件挂载
|
|
325
328
|
5. **插件系统**:提供扩展机制,支持自定义功能
|
|
326
329
|
|
|
327
|
-
##
|
|
330
|
+
## �️ 安全机制
|
|
331
|
+
|
|
332
|
+
Solely 框架内置了多层安全防护机制,有效防止常见的 XSS(跨站脚本攻击):
|
|
333
|
+
|
|
334
|
+
### 编译时安全
|
|
335
|
+
|
|
336
|
+
- **模板编译时固定**:所有模板在构建阶段编译为中间表示(IR),运行时无法更改模板结构
|
|
337
|
+
- **无运行时解析**:不存在 `eval` 或动态模板解析,杜绝代码注入
|
|
338
|
+
|
|
339
|
+
### 自动 HTML 转义
|
|
340
|
+
|
|
341
|
+
- **文本插值自动转义**:使用 `{{ }}` 插值时,框架自动进行 HTML 实体编码
|
|
342
|
+
|
|
343
|
+
```html
|
|
344
|
+
<!-- 用户输入: <script>alert('XSS')</script> -->
|
|
345
|
+
<div>{{ $data.userInput }}</div>
|
|
346
|
+
<!-- 渲染结果: <script>alert('XSS')</script> -->
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
### 安全最佳实践
|
|
350
|
+
|
|
351
|
+
| ✅ 推荐做法 | ❌ 避免做法 |
|
|
352
|
+
|---|---|
|
|
353
|
+
| 使用 `{{ }}` 插值显示用户内容 | 将用户输入绑定到 `:innerHTML` |
|
|
354
|
+
| 对用户输入进行验证和清理 | 直接操作 DOM 插入不可信内容 |
|
|
355
|
+
| 使用 CSP (Content Security Policy) | 信任未经检验的第三方 API 数据 |
|
|
356
|
+
| 富文本使用白名单过滤 | 动态构造模板字符串 |
|
|
357
|
+
|
|
358
|
+
### 注意事项
|
|
359
|
+
|
|
360
|
+
⚠️ **如果框架支持 `:innerHTML` 指令**:
|
|
361
|
+
|
|
362
|
+
- 永远不要将用户输入绑定到 `:innerHTML`
|
|
363
|
+
- 永远不要将第三方 API 数据直接绑定到 `:innerHTML`
|
|
364
|
+
- 仅对完全可信的静态内容使用 `:innerHTML`
|
|
365
|
+
- 如需渲染富文本,请使用专门的富文本组件并进行白名单过滤
|
|
366
|
+
|
|
367
|
+
查看 [安全演示示例](./examples/security-demo/) 了解框架如何防护 XSS 攻击。
|
|
368
|
+
|
|
369
|
+
## � API 参考
|
|
328
370
|
|
|
329
371
|
### CustomElement 装饰器
|
|
330
372
|
|
|
@@ -474,6 +516,7 @@ class MyComponent extends BaseElement<MyData> {
|
|
|
474
516
|
```
|
|
475
517
|
|
|
476
518
|
**说明**:
|
|
519
|
+
|
|
477
520
|
- 钩子属性中可以使用 `this` 访问组件实例
|
|
478
521
|
- 钩子函数会接收元素本身作为参数(通过 `el` 变量)
|
|
479
522
|
- 可以在钩子中调用组件的方法,实现更复杂的逻辑
|
|
@@ -507,6 +550,7 @@ class MyComponent extends BaseElement<MyData> {
|
|
|
507
550
|
```
|
|
508
551
|
|
|
509
552
|
**说明**:
|
|
553
|
+
|
|
510
554
|
- 在模板元素上添加 `ref="名称"` 属性
|
|
511
555
|
- 在组件中通过 `this.$refs.名称` 访问对应的 DOM 元素
|
|
512
556
|
- 支持在任何模板元素上使用,包括原生 HTML 元素和自定义组件
|
|
@@ -587,6 +631,41 @@ const state = observe({
|
|
|
587
631
|
state.name = 'New Name'; // 触发回调
|
|
588
632
|
```
|
|
589
633
|
|
|
634
|
+
#### 特殊对象处理
|
|
635
|
+
|
|
636
|
+
响应式系统会自动处理以下特殊情况:
|
|
637
|
+
|
|
638
|
+
| 对象类型 | 处理方式 | 说明 |
|
|
639
|
+
|---|---|---|
|
|
640
|
+
| `Object.freeze()` | 跳过代理 | 被冻结的对象不会被代理,直接返回原对象 |
|
|
641
|
+
| `Object.seal()` | 跳过代理 | 被密封的对象不会被代理,直接返回原对象 |
|
|
642
|
+
| `File` / `Blob` | 跳过代理 | 浏览器原生文件对象不会被代理 |
|
|
643
|
+
| `FormData` | 跳过代理 | 表单数据对象不会被代理 |
|
|
644
|
+
| `ArrayBuffer` | 跳过代理 | 二进制数据缓冲区不会被代理 |
|
|
645
|
+
| `Response` / `Request` | 跳过代理 | Fetch API 对象不会被代理 |
|
|
646
|
+
|
|
647
|
+
**示例**:
|
|
648
|
+
|
|
649
|
+
```typescript
|
|
650
|
+
// 冻结对象不会被代理
|
|
651
|
+
const frozen = Object.freeze({ count: 0 });
|
|
652
|
+
const state = observe({ frozen }, (change) => {
|
|
653
|
+
console.log('变化:', change);
|
|
654
|
+
});
|
|
655
|
+
|
|
656
|
+
// 修改冻结对象的属性不会触发回调
|
|
657
|
+
state.frozen.count = 1; // 静默失败,无回调
|
|
658
|
+
|
|
659
|
+
// File 对象不会被代理
|
|
660
|
+
const file = new File(['content'], 'test.txt');
|
|
661
|
+
const state2 = observe({ file }, (change) => {
|
|
662
|
+
console.log('变化:', change);
|
|
663
|
+
});
|
|
664
|
+
|
|
665
|
+
// File 对象保持原样
|
|
666
|
+
console.log(state2.file instanceof File); // true
|
|
667
|
+
```
|
|
668
|
+
|
|
590
669
|
### 路由系统
|
|
591
670
|
|
|
592
671
|
Solely 提供了功能强大的内置路由系统,支持单页应用开发,包括路由定义、导航、参数传递、路由守卫等功能。
|
|
@@ -896,6 +975,7 @@ beforeEach: (to, from) => {
|
|
|
896
975
|
- **待办事项示例** (`examples/todo/`) - 列表管理和状态示例
|
|
897
976
|
- **表单示例** (`examples/form/`) - 表单处理和验证示例
|
|
898
977
|
- **天气示例** (`examples/weather/`) - 异步数据获取示例
|
|
978
|
+
- **安全演示** (`examples/security-demo/`) - XSS 防护机制演示
|
|
899
979
|
|
|
900
980
|
### 运行示例
|
|
901
981
|
|
|
@@ -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;
|