# @type-dom/framework

> ## 框架概述

Latest version **0.9.0** (published 2026-09-10) · 0 weekly downloads

## Install

```sh
npm install @type-dom/framework
pnpm add @type-dom/framework
yarn add @type-dom/framework
bun add @type-dom/framework
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2026-09-10 |
| First published | 2023-11-05 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 1.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | xjf7711 |

## Links

- npm: https://www.npmjs.com/package/@type-dom/framework
- Repository: https://github.com/type-dom/framework
- Homepage: https://github.com/type-dom/framework#readme
- Issues: https://github.com/type-dom/framework/issues
- npm.io page: https://npm.io/package/@type-dom/framework

## Dependencies (4)

- [tslib](https://npm.io/package/tslib.md) ^2.3.0
- [@type-dom/utils](https://npm.io/package/@type-dom/utils.md) *
- [@type-dom/signals](https://npm.io/package/@type-dom/signals.md) *
- [@type-dom/css-type](https://npm.io/package/@type-dom/css-type.md) *

## Recent versions

- 0.9.0 (latest) — 2026-09-10
- 0.5.2 — 2026-09-10
- 0.5.0 — 2026-03-14
- 0.4.2 — 2025-05-31
- 0.4.1 — 2025-05-31
- 0.4.0 — 2025-05-09
- 0.3.0 — 2025-04-29
- 0.2.1 — 2025-04-28
- 0.2.0 — 2025-04-26
- 0.1.13 — 2025-01-31
- 0.1.12 — 2024-11-08
- 0.1.11 — 2024-10-16
- 0.1.9 — 2024-09-23
- 0.1.8 — 2024-09-23
- 0.1.7 — 2024-09-05
- … 17 more at https://npm.io/package/@type-dom/framework/versions

## README

# TypeDOM Framework

## 框架概述

TypeDOM 是一个完全面向对象（OOP）设计的 TypeScript 前端框架，基于虚拟 DOM 技术，参考 Vuejs/AngularJS/Ext.js 框架架构。它采用抽象类/具体类/实例的组织方式，为前端开发提供了独特的面向对象编程体验。

### 核心设计理念

**面向对象编程（OOP）为核心**
- 完全面向对象的设计思路，所有组件都是类的实例
- 支持类、继承、封装、多态等 OOP 特性
- 通过抽象类和具体类建立清晰的类层次结构
- 实例化管理组件生命周期和状态

**虚拟 DOM 与直接操作并重**
- 基于虚拟 DOM 技术，但不完全依赖虚拟 DOM diff
- 直接操作原生 DOM，通过 TypeScript 提供类型安全保障
- 精确控制 DOM 操作，避免不必要的重排重绘
- 支持直接 DOM 操作与虚拟 DOM 的灵活切换

## 技术架构深度解析

### 架构层次结构

```
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│              (AppRoot, AppElement, 业务组件)                 │
├─────────────────────────────────────────────────────────────┤
│                      Framework Core                         │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐  │
│  │   Core API  │   Renderer  │  Reactivity │   DOM Ops   │  │
│  │             │             │   System    │             │  │
│  └─────────────┴─────────────┴─────────────┴─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                    Abstract Layer                           │
│  TypeNode → TypeElement → TypeHtml / TypeSvg               │
├─────────────────────────────────────────────────────────────┤
│                    Infrastructure                           │
│           Utils, Helpers, Constants, Types                  │
└─────────────────────────────────────────────────────────────┘
```

### 核心模块详细分析

#### 1. 核心抽象层 (Abstract Layer)

**TypeNode 抽象类** (`/src/core/abstracts/type-node/type-node.abstract.ts`)
- **作用**: 所有节点的基类，定义了虚拟节点的基本行为和属性
- **核心属性**:
  - `uid`: 唯一标识符，用于节点比较和调试
  - `ClassName`: 类名标识（只读 getter，返回 `constructor.name`），用于运行时类型识别
  - `props`: 节点属性集合
  - `childNodes`: 子节点数组
  - `parent`: 父节点引用
  - `dom`: 对应的真实 DOM 节点
  - `lifeCycles`: 生命周期钩子集合

- **关键方法**:
  - `mount()`: 挂载到指定容器
  - `render()`: 渲染虚拟 DOM 到真实 DOM
  - `unmount()`: 卸载节点及其子节点
  - `findChildNode()`: 查找子节点
  - `findDownNodes()`: 深度查找后代节点
  - `toJSON()`: 序列化为 JSON 格式

**TypeElement 抽象类** (`/src/core/abstracts/type-element/type-element.abstract.ts`)
- **继承**: 继承自 `TypeNode`
- **扩展功能**:
  - 元素特有的属性和方法
  - DOM 元素操作封装
  - 样式和属性管理
  - 事件处理机制

**专用元素抽象类**:
- `TypeHtml`: HTML 元素抽象类（Div、Span、Button、Input 等 **87 个** HTML 标签类均继承自此；标签类位于 `src/core/components/html-element/`）
- `TypeSvg`: SVG 元素抽象类（SvgCircle、SvgRect、SvgPath 等 **19 个** SVG 标签类均继承自此；位于 `src/core/components/svg-element/`）
- `Fragment`: 片段组件（继承自 `TypeElement`，可直接实例化，用于多根节点/条件渲染/路由视图等场景）。`Fragment`、`XElement`、`TextNode`、`CommentNode` 均为 `src/core/components/` 下的**可实例化具体类**（非抽象类），不要把它们与 `TypeNode`/`TypeElement`/`TypeHtml`/`TypeSvg` 这 4 个抽象基类混淆。

#### 2. 核心 API 层 (Core API)

**组件系统** (`/src/core/component.ts` - 37.64 KB)
- 提供组件**选项与组合式 API 支撑**，负责组件实例化、生命周期钩子（beforeCreate、created、mounted 等）、属性与状态管理、事件发射/监听、插槽支持。
- 主要导出：`Data`、`ComponentOptions`、`SetupContext`、`currentInstance`、`getCurrentInstance`、`setCurrentInstance`、`unsetCurrentInstance`、`validateComponentName`、`createSetupContext`、`getComponentPublicInstance`、`getComponentName`、`formatComponentName`。
- 注意：本框架**没有独立的 `TypeComponent` 抽象类**。组件基类即为 `TypeElement` / `TypeHtml` 这条抽象链——业务组件通过继承 `Div`、`Fragment` 等具体类（如 `class UserCard extends Div`）来创建，而非继承某个虚构的 `TypeComponent`。

**工具函数** (`/src/core/helpers/`)
- `mergeProps` / `isTypeNode` 等虚拟节点与属性处理的辅助函数（原 `vnode.ts` 已移除，相关能力下沉到 `helpers/`）。

**API 创建和注入**
- `apiCreateApp.ts` (11.76 KB): 应用创建 API
- `apiInject.ts` (4.47 KB): 依赖注入 API
- `apiLifecycle.ts` (6.36 KB): 生命周期 API
- `apiSetupHelpers.ts` (14.3 KB): 组合式 API 辅助函数

#### 3. 渲染器层 (Renderer)

**渲染核心** (`/src/core/renderer/`)
- **patch.ts** (29.93 KB): 核心补丁算法
  - 节点差异计算和最小更新
  - 节点类型处理和转换
  - 子节点 diff 算法
  - 性能优化策略

- **hydration.ts** (32.53 KB): 服务端渲染水合
  - SSR 内容客户端激活
  - 水合不匹配处理
  - 渐进式水合策略

- **mountChildren.ts**: 子节点挂载管理
- **remove.ts** (1.93 KB): 节点移除清理
- **render.ts**: 渲染入口函数

**DOM 操作层** (`/src/dom/`)
- **nodeOps.ts** (4.6 KB): 原生 DOM 操作封装
  - 跨浏览器兼容性处理
  - DOM 操作抽象接口
  - 事件系统集成

- **patchProp.ts** (4.32 KB): 属性更新算法
  - 属性差异计算
  - 样式和类更新优化
  - 事件监听器管理

**指令与转换/解析/测试辅助模块** (`/src/core/directives/`、`/src/core/transforms/`、`/src/parser/`、`/src/test-utils/`)
- **directives/**：指令是 `TypeProps` 的构造参数字段，由 `core/components/fragment/mountFragment.ts` 统一编排，顺序为 `vIf → vShow → vModel → (render) → vOnce → vMemo → vFor`。内置指令：`vIf`、`vShow`、`vModel`、`vOnce`、`vMemo`、`vFor`、`vOn`（提供 `withModifiers`）、`vLoading`、`vRepeatClick`。
- **transforms/**：`transformSlot`（作用域插槽转换）、`useRecurseRender`（递归渲染），已由 `core/index.ts` 公开导出。
- **parser/**：模板/结构解析工具（如 `Parser` 类）。
- **test-utils/**：测试辅助（`nodeOps`、`patchProp`、`serialize`、`triggerEvent`），供 Vitest 使用。

#### 5. 响应式系统 (Reactivity)

**响应式核心** (`/src/reactivity/`)
- **reactive.ts** (12.88 KB): 响应式对象实现
  - Proxy-based 响应式系统
  - 深度响应式转换
  - 响应式状态跟踪

- **ref.ts** (10.71 KB): 引用类型管理
  - 基本类型响应式包装
  - 引用解包和访问
  - 响应式引用集合

- **watch.ts** (13.86 KB): 观察者模式
  - 副作用函数管理
  - 依赖收集和触发
  - 异步观察支持

- **batchEffect.ts**: 批量更新优化
  - 异步更新队列
  - 批量执行策略
  - 更新优先级管理

#### 6. 组件辅助系统

**组件选项和工具**
- `componentOptions.ts` (33.92 KB): 组件选项定义和验证
- `componentProps.ts` (24.6 KB): 属性定义和处理
- `componentEmits.ts` (9.8 KB，另含 `componentEmits.interface.ts` / `componentEmits.legacy.ts`): 事件发射系统
- `componentSlots.ts`: 插槽管理机制
- `componentPublicInstance.ts` (22.07 KB): 公共实例接口

**生命周期管理**
- `scheduler.ts` (9.83 KB): 任务调度器
- `errorHandling.ts` (5.74 KB): 错误处理系统
- `warning.ts` (~0.8 KB): 警告和调试信息

## 核心特性深度分析

### 1. 面向对象设计优势

**类层次结构清晰**
```typescript
// 典型的类继承结构
TypeNode (抽象基类)
├── TypeElement (元素抽象类)
│   ├── TypeHtml (HTML元素)
│   ├── TypeSvg (SVG元素)
│   ├── XElement (通用元素，继承自 TypeElement)
│   └── Fragment (片段节点/组件基类，继承自 TypeElement)
├── TextNode (文本节点)
└── CommentNode (注释节点)

```

**封装性和继承性**
- 每个类都有明确的职责和边界
- 通过继承复用通用功能
- 通过多态实现组件行为的灵活扩展
- 私有属性和方法的访问控制

**实例化管理**
- 每个组件都是类的实例，拥有独立的状态
- 实例间相互隔离，避免状态污染
- 支持实例的动态创建和销毁

### 2. 虚拟 DOM 优化策略

**精确的 DOM 控制**
- 不依赖传统的虚拟 DOM diff 算法
- 直接操作目标节点，减少中间层开销
- 智能的节点复用和更新策略

**Patch Flags 优化**
```typescript
// 编译时生成的优化标记
// 实际定义并导出于 @type-dom/utils（libs/utils/src/shared/patchFlags.ts）
import { PatchFlags } from '@type-dom/utils';

enum PatchFlags {
  TEXT = 1,                  // 动态文本子节点
  CLASS = 1 << 1,            // 动态 class
  STYLE = 1 << 2,            // 动态 style
  PROPS = 1 << 3,            // 动态非 class/style 属性
  FULL_PROPS = 1 << 4,       // 带动态 key 的 props，需全量 diff
  NEED_HYDRATION = 1 << 5,   // 需要属性水合
  STABLE_FRAGMENT = 1 << 6,  // 子节点顺序不变的片段
  KEYED_FRAGMENT = 1 << 7,   // 带 key 的片段
  UNKEYED_FRAGMENT = 1 << 8, // 无 key 的片段
  NEED_PATCH = 1 << 9,       // 仅需非 props 补丁
  DYNAMIC_SLOTS = 1 << 10,   // 动态插槽
  DEV_ROOT_FRAGMENT = 1 << 11, // 仅开发环境的根片段
  CACHED = -1,               // 缓存的静态节点
  BAIL = -2                  // 退出优化模式，全量对比
}
```

**Block Tree 优化**
- 将模板分为嵌套的块（Block）
- 块内节点结构稳定，只跟踪动态节点
- 大幅减少节点对比的计算量

### 3. 响应式系统设计

**响应式标记**
```typescript
// libs/framework/src/reactivity/constants.ts
// 以字面量字符串而非数字定义，便于在调试器中查看
export enum ReactiveFlags {
  SKIP = '__v_skip',
  IS_REACTIVE = '__v_isReactive',
  IS_READONLY = '__v_isReadonly',
  IS_SHALLOW = '__v_isShallow',
  RAW = '__v_raw',
  IS_REF = '__v_isRef',
}

export enum TrackOpTypes {
  GET = 'get',
  HAS = 'has',
  ITERATE = 'iterate',
}

export enum TriggerOpTypes {
  SET = 'set',
  ADD = 'add',
  DELETE = 'delete',
  CLEAR = 'clear',
}
```

> 说明：`ReactiveNode` / `Link` 这套基于双向链表的依赖结构是 `@type-dom/signals` 的内部实现，不在 framework 中。

**批量更新优化**
- 异步更新队列，避免频繁 DOM 操作
- 微任务级别的更新调度
- 更新优先级和中断机制

### 4. 类型安全体系

**编译时类型检查**
- 完整的 TypeScript 类型定义
- 泛型约束确保类型安全
- 接口定义组件契约

**运行时类型识别**
```typescript
// 通过只读的 ClassName getter 进行运行时类型识别
// （返回 this.constructor.name，无需在每个子类中显式赋值）
abstract class TypeNode {
  get ClassName(): string {
    return this.constructor.name;
  }

  getRoot<T extends TypeNode>(): T | undefined {
    // 类型安全的根节点查找
  }
}

// isTypeNode 是独立导出的函数，不是静态方法
import { isTypeNode } from '@type-dom/framework';
export function isTypeNode(value: any): value is TypeNode {
  return value instanceof TypeNode;
}
```

## 与传统框架对比分析

### 与 React 对比

| 维度 | TypeDOM | React |
|------|---------|-------|
| **设计理念** | 完全面向对象 | 函数式编程 + 组件化 |
| **状态管理** | 类属性 + 响应式系统 | useState/useReducer Hooks |
| **DOM 操作** | 直接操作 + 虚拟 DOM | 虚拟 DOM diff |
| **类型系统** | TypeScript 原生支持 | 需要额外类型定义 |
| **学习曲线** | 面向对象背景友好 | 函数式概念门槛 |
| **性能** | 直接操作，无 diff 开销 | 虚拟 DOM diff 开销 |
| **生态** | 新兴框架，生态较小 | 成熟生态，资源丰富 |

### 与 Vue 对比

| 维度 | TypeDOM | Vue |
|------|---------|-----|
| **响应式** | Proxy + 精细控制 | Proxy + 自动追踪 |
| **组件模型** | 类继承 | Options API / Composition API |
| **模板编译** | 运行时 + 编译时优化 | 编译时优化为主 |
| **类型支持** | 原生 TypeScript | 逐步增强 |
| **扩展性** | 面向对象扩展 | 插件和 Mixin 机制 |

### 独特优势

1. **面向对象纯粹性**: 100% 面向对象设计，无函数式污染
2. **直接 DOM 控制**: 避免虚拟 DOM 开销，性能更可控
3. **精确类型安全**: 编译时和运行时的双重类型保障
4. **标准化数据交换**: 天然支持 JSON/XML 数据结构转换
5. **企业级设计模式**: 天然支持 MVC、MVVM 等企业架构

## 性能特征分析

### 优势场景

**1. 大型复杂应用**
- 类继承体系清晰，代码结构易于维护
- 面向对象设计天然支持复杂业务逻辑建模
- 类型安全减少运行时错误

**2. 需要精确 DOM 控制的应用**
- OFD 文档编辑器、富文本编辑器等
- 游戏开发和图形应用
- 需要与原生 API 深度集成的场景

**3. 企业级应用**
- 严格的代码组织和规范
- 长生命周期项目的稳定性要求
- 团队协作的标准化需求

### 性能基准

**DOM 操作性能**
- 直接操作比虚拟 DOM 快约 30%（基于 CSS Typed OM 测试）
- 避免虚拟 DOM diff 算法的计算开销
- 精确控制更新范围，减少不必要的重排重绘

**内存使用**
- 无虚拟 DOM 树的内存开销
- 类实例化管理，内存使用可预测
- 垃圾回收友好，无循环引用问题

**启动性能**
- Vite 支持秒级开发服务器启动
- 按需编译，无全量打包开销
- Tree-shaking 优化，只加载使用代码

## 生态系统架构

### 核心库矩阵

| 库名 | 功能定位 | 核心特性 | 与主框架关系 |
|------|----------|----------|-------------|
| `@type-dom/ui` | UI 组件库 | 60+ 组件，主题系统 | 基于 TypeDOM 构建 |
| `@type-dom/svgs` | SVG 图标库 | 矢量图标，按需加载 | 独立组件生态 |
| `@type-dom/form-builder` | 动态表单 | JSON Schema 驱动 | 业务逻辑扩展 |
| `@type-dom/router` | 路由管理 | History API，嵌套路由 | 应用级功能 |
| `@type-dom/i18n` | 国际化 | 多语言，RTL 支持 | 跨地域支持 |
| `@type-dom/signals` | 响应式 | Signal 系统，批更新 | 状态管理补充 |

### 扩展机制

**插件系统**
```typescript
// 框架级插件接口
interface FrameworkPlugin {
  install(app: TypeApp, ...options: any[]): void;
}

// 组件级扩展：业务组件继承具体元素类（而非虚构的 TypeComponent）
class CustomComponent extends Div {
  // 通过继承和组合扩展功能
}
```

**自定义元素支持**
```typescript
class AppElement extends HTMLElement {
  connectedCallback() {
    const appRoot = new AppRoot();
    appRoot.mount(this);
  }
}
customElements.define('app-root', AppElement);
```

## 开发体验和工具链

### 开发工具支持

**IDE 集成**
- VS Code 插件提供智能提示
- TypeScript 语言服务完整支持
- 调试工具集成

**构建工具**
- Vite: 开发服务器和构建优化
- Rollup: 库打包优化
- Webpack: 兼容性支持

**测试工具**
- Vitest: 单元测试框架
- Playwright: E2E 测试
- Testing Library: 组件测试

### 调试和诊断

**开发调试**
```typescript
// 生命周期钩子调试
class DebugComponent extends Div {
  created() {
    console.log('Component created:', this.uid);
  }
  
  mounted() {
    console.log('Component mounted:', this.dom);
  }
}
```

**性能监控**
- 组件渲染时间追踪
- 内存使用监控
- 响应式更新频率统计

## 应用场景和最佳实践

### 适用场景

**1. 政务信息化系统**
- OFD 文档处理需求
- 严格的格式标准要求
- 长期维护和稳定性要求

**2. 企业级后台管理**
- 复杂表单和流程管理
- 面向对象的数据建模
- 团队协作开发

**3. 文档编辑和处理**
- 需要精确控制文档结构
- 复杂的交互逻辑
- 标准化数据交换

**4. 游戏和图形应用**
- 面向对象的设计模式匹配
- 直接 DOM 操作性能优势
- 复杂状态管理需求

### 最佳实践

**组件设计原则**
```typescript
// 1. 单一职责原则
class UserProfileCard extends Div {
  // 只负责用户信息展示
}

class UserEditForm extends Div {
  // 只负责用户信息编辑
}

// 2. 开闭原则 - 通过继承扩展
class AdminUserProfileCard extends UserProfileCard {
  // 扩展管理员特有的显示逻辑
}

// 3. 依赖倒置原则
abstract class DataService {
  abstract fetchUserData(): Promise<User>;
}

class HttpUserService extends DataService {
  // 具体实现
}
```

**性能优化策略**
```typescript
// 1. 合理使用响应式
class OptimizedComponent extends Div {
  // 只对需要响应的数据使用响应式
  private counter = 0; // 非响应式，避免不必要追踪
  public reactiveCounter = ref(0); // 响应式，需要触发更新
}

// 2. 批量更新
class BatchUpdateComponent extends Div {
  private updateQueue: (() => void)[] = [];
  
  scheduleUpdate(update: () => void) {
    this.updateQueue.push(update);
    // 批量执行，避免频繁更新
    nextTick(() => {
      this.updateQueue.forEach(fn => fn());
      this.updateQueue = [];
    });
  }
}
```

## 未来发展方向

### 技术演进路线

**短期目标 (6-12个月)**
1. **性能优化**: 进一步完善渲染性能，减少内存占用
2. **开发工具**: 增强调试工具和开发体验
3. **生态建设**: 丰富 UI 组件库和工具库
4. **文档完善**: 建立完整的文档和示例体系

**中期目标 (1-2年)**
1. **服务端渲染**: 完善 SSR 和静态站点生成
2. **微前端支持**: 提供微前端架构支持
3. **跨平台扩展**: 支持桌面和移动端应用开发
4. **AI 辅助开发**: 集成 AI 编程助手

**长期愿景 (3-5年)**
1. **行业标准**: 成为企业级前端开发标准之一
2. **生态繁荣**: 建立完整的开发者生态
3. **技术引领**: 在前端架构设计方面引领趋势
4. **全球影响**: 在国际市场获得认可和应用

### 创新方向

**1. WebAssembly 集成**
- 核心算法 WASM 化，进一步提升性能
- 支持高性能计算和图形处理

**2. 量子计算准备**
- 研究量子计算对传统编程模型的冲击
- 为未来的计算范式做准备

**3. 元宇宙支持**
- VR/AR 应用开发支持
- 3D 图形和交互能力增强

## 总结评价

TypeDOM 框架代表了前端开发的一种全新思路：**回归面向对象本质，追求极致性能和控制力**。它的独特价值在于：

**技术价值**
- 证明了面向对象在前端领域的可行性
- 提供了虚拟 DOM 之外的另一种性能优化路径
- 建立了 TypeScript 与 OOP 结合的典范

**工程价值**
- 为企业级应用提供了可靠的技术选型
- 降低了复杂业务系统的开发和维护成本
- 提升了代码的可读性和可维护性

**战略价值**
- 打破了传统前端框架的垄断格局
- 为中国前端技术发展贡献了新的思路
- 推动了前端工程化向更深层次发展

TypeDOM 不仅仅是一个技术框架，更是一种设计哲学的体现：**在追求技术进步的同时，不应忘记软件工程的本质——用清晰的逻辑和严谨的结构来解决实际问题**。它为企业级前端开发提供了一个值得认真考虑的选择，特别是在需要处理复杂业务逻辑和长期维护的大型项目中。

---
_Source: https://npm.io/package/@type-dom/framework · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._