# learn-ts-vue-base

**Repository Path**: hzy45/learn-ts-vue-base

## Basic Information

- **Project Name**: learn-ts-vue-base
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TypeScript 学习路线

> 基于 Vue 3 知识基础，由浅入深掌握 TypeScript 语法及与 Vue 3 的结合使用。
>
> ⭐ = 日常开发高频使用　🔥 = Vue 3 项目核心必会

## 运行方式

每个 .ts 文件可独立运行（.vue 文件仅作学习展示，不要求在本项目内运行）：

```bash
npm run 01   # 等同于 npx ts-node 01-basics.ts
npm run 02   # 依此类推...
npm run 03
npm run 04
npm run 06
npm run 07
npm run 08
npm run 11
```

类型检查：

```bash
npm run check   # npx tsc --noEmit
npm run build   # npx tsc（编译输出到 dist/）
```

> 说明：05、09、10、12 为 `.vue` 文件，仅作 Vue 3 + TS 语法展示，本项目内不提供运行脚本。

---

## tsconfig.json 常用选项说明

| 选项                               | 本项目取值 | 说明                                                                    |
| ---------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `target`                           | ES2020     | 编译输出的 ECMAScript 版本                                              |
| `module`                           | commonjs   | 模块系统。本项目为 ts-node 学习环境；**真实 Vue 3 项目用 `esnext`**     |
| `lib`                              | ES2020/DOM | 内置类型库，`DOM` 让代码中可以使用 `window`、`document` 等              |
| `strict`                           | true       | 开启全部严格类型检查（`strictNullChecks` 等），**Vue 项目强烈建议开启** |
| `esModuleInterop`                  | true       | 让 CJS 模块可以用 `import x from 'x'` 的默认导入语法                    |
| `skipLibCheck`                     | true       | 跳过 `.d.ts` 类型检查，显著加快编译速度                                 |
| `forceConsistentCasingInFileNames` | true       | 强制文件名大小写一致，避免跨平台 bug                                    |
| `resolveJsonModule`                | true       | 允许 `import data from './foo.json'`                                    |
| `declaration` / `sourceMap`        | true       | 生成 `.d.ts` 声明文件和 source map，便于调试和库开发                    |

---

## 阶段 01：基础类型、接口、类型别名

**文件**：`01-basics.ts`

| 知识点            | 说明                                                                                     | 频率               |
| ----------------- | ---------------------------------------------------------------------------------------- | ------------------ | --- |
| 基础类型          | `string`、`number`、`boolean`、`null`、`undefined`、`any`、`unknown`、`symbol`、`bigint` | ⭐                 |
| 数组与元组        | `number[]`、`Array<T>`、`[string, number]`、命名元组                                     | ⭐                 |
| 对象类型三种声明  | 匿名对象类型、`interface`、`type`                                                        | ⭐                 |
| interface vs type | 声明合并、`extends` 继承 vs 联合/交叉类型                                                | ⭐                 |
| 枚举              | 普通枚举、常量枚举 `const enum`                                                          |                    |
| 字面量类型        | `"light"                                                                                 | "dark"` 精确约束值 | ⭐  |

**关键要点**：

- ⭐ `interface` 用于定义对象形状，`type` 用于定义任意类型的别名——**几乎每个文件都会用到**
- ⭐ `?` 表示可选属性，`readonly` 表示只读——**Vue props 定义必备**
- 字面量类型可以精确约束值为特定字符串/数字——**组件 variant/size 等属性常用**
- 枚举适合有限的命名常量集合（但 Vue 3 项目中更常用字面量联合类型替代）

---

## 阶段 02：联合类型、交叉类型、泛型、工具类型

**文件**：`02-advanced-types.ts`

| 知识点                  | 说明                                               | 频率    |
| ----------------------- | -------------------------------------------------- | ------- |
| 联合类型                | `string | number` | ⭐  |
| 可辨识联合              | `status` 字段区分不同响应类型                      | 🔥      |
| 交叉类型                | `TypeA & TypeB` 合并多个类型                       | ⭐      |
| 泛型基础                | `identity<T>`、自动推断、泛型约束 `extends`        | ⭐      |
| 多泛型与 keyof          | `merge<T, U>`、`getProperty<T, K extends keyof T>` | ⭐      |
| 泛型接口与默认值        | `Repository<T>`、`PaginatedResponse<T = unknown>`  | 🔥      |
| Partial                 | 所有属性变可选                                     | 🔥      |
| Pick / Omit             | 选取 / 排除部分属性                                | 🔥      |
| Record                  | 键值对映射 `Record<K, V>`                          | 🔥      |
| Readonly                | 所有属性变只读                                     |         |
| Required                | 所有属性变必填                                     |         |
| Exclude / Extract       | 从联合类型中排除 / 提取                            | ⭐      |
| NonNullable             | 排除 `null` 和 `undefined`                         | ⭐      |
| ReturnType / Parameters | 获取函数返回值类型 / 参数类型                      | ⭐      |

**关键要点**：

- 🔥 **可辨识联合**是 Vue 3 组件 props 和 API 响应处理的核心模式——**几乎每个接口请求都会用到**
- ⭐ 泛型让类型可复用，`extends` 约束泛型范围——**Composable 和 API 封装的基础**
- ⭐ `keyof` + 泛型 = 类型安全的属性访问
- 🔥 **工具类型（Partial/Pick/Omit/Record）** 在日常开发中使用频率极高——**编辑/创建表单、API 参数类型必用**

---

## 阶段 03：函数类型、类

**文件**：`03-functions-classes.ts`

| 知识点             | 说明                                         | 频率 |
| ------------------ | -------------------------------------------- | ---- |
| 函数类型           | 参数类型、返回值类型、函数类型表达式         | ⭐   |
| 可选参数与默认参数 | `greeting?: string`、`greeting = "Hello"`    | ⭐   |
| 剩余参数           | `...numbers: number[]`                       |      |
| 函数重载           | 同一函数多种参数组合                         |      |
| 类的访问修饰符     | `public`、`private`、`protected`、`readonly` | ⭐   |
| getter / setter    | 属性访问器                                   | ⭐   |
| 参数属性简写       | 构造器参数直接声明为类属性                   | ⭐   |
| 继承与 override    | `extends`、`super()`、`override`             |      |
| 抽象类             | `abstract` 类和方法                          |      |
| 类实现接口         | `implements Serializable, Comparable<T>`     |      |
| 静态成员与单例     | `static`、私有构造器                         |      |
| 泛型集合类         | `Collection<T>`                              |      |
| EventEmitter       | 类型安全的事件总线                           | 🔥   |

---

## 阶段 04：类型守卫、类型收窄、断言

**文件**：`04-type-guards.ts`

| 知识点              | 说明                         | 频率 |
| ------------------- | ---------------------------- | ---- |
| typeof 类型守卫     | `typeof value === 'string'`  | ⭐   |
| instanceof          | 类的实例检查                 | ⭐   |
| in 操作符           | 检查对象属性是否存在         | ⭐   |
| 自定义类型守卫      | `result is ApiSuccessResult` | 🔥   |
| 可辨识联合 + switch | 类型穷尽检查                 | 🔥   |
| 类型断言            | `as Type`、`!` 非空断言      | ⭐   |
| satisfies 操作符    | 类型检查但不拓宽（TS 4.9+）  | ⭐   |

**关键要点**：

- 🔥 **可辨识联合 + switch** 是处理多种状态的核心模式
- ⭐ `satisfies` 让你既享受类型检查，又保留字面量类型推断
- ⭐ `assertNever` 函数确保所有情况都被处理

---

## 阶段 05：Vue 3 + TypeScript 常见模式

**文件**：`05-vue3-patterns.vue`

> 本章已迁移为 SFC 写法，以 `<script setup lang="ts">` 展示 Vue 3 + TS 的核心模式。

| 知识点           | 说明                          | 频率   |
| ---------------- | ----------------------------- | ------ | --- |
| defineComponent  | Vue 组件类型定义              | 🔥     |
| PropType         | 复杂 props 类型（数组、函数） | 🔥     |
| ref / reactive   | 响应式数据的类型              | 🔥     |
| computed         | 计算属性自动推断              | 🔥     |
| watch            | 监听器的类型                  | ⭐     |
| Composable       | 组合式函数 + 泛型             | 🔥     |
| provide / inject | InjectionKey 确保类型安全     | 🔥     |
| 模板 ref         | `ref<HTMLInputElement         | null>` | ⭐  |
| useField 表单    | 类型安全的表单字段            | ⭐     |

**关键要点**：

- 🔥 **Composable 是 Vue 3 + TS 的核心复用模式**，善用泛型
- ⭐ `InjectionKey` 是 provide/inject 类型安全的唯一正确方式
- ⭐ `ref<T>` 显式类型主要用于初始值为 null 的场景

---

## 阶段 06：实战模式（API 封装、状态管理类型、表单校验）

**文件**：`06-practical-patterns.ts`

| 知识点                  | 说明                                     | 频率 |
| ----------------------- | ---------------------------------------- | ---- |
| 类型安全 API 封装       | 泛型响应类型、请求配置                   | 🔥   |
| API 路由映射            | 路径参数、请求/响应类型映射              | 🔥   |
| Pinia 风格 Store 定义   | State/Getters/Actions 类型化             | 🔥   |
| 类型安全路由定义        | 路由参数解析                             | ⭐   |
| 条件类型生成 getter     | `[K in keyof T as \`get${Capitalize}\`]` | ⭐   |
| 深度 Partial / Required | 递归工具类型                             | ⭐   |
| 类型安全 Event Bus      | EventMap 约束                            | ⭐   |
| 类型安全配置构建器      | TableConfig<T>                           | ⭐   |

---

## 阶段 07：装饰器（Decorators）选学附录

**文件**：`07-decorators.ts`

> ⚠️ **选学提示**：装饰器在 Vue 3 日常业务开发中使用频率极低（vue-class-component 已边缘化），本章作为**选学附录**，可跳过。
> TS 5.0+ 已支持原生装饰器，语法与本章使用的 `experimentalDecorators` 略有差异；如无特定需求可直接跳到第 08 章。

| 知识点     | 说明                                 | 频率 |
| ---------- | ------------------------------------ | ---- |
| 类装饰器   | 接收构造函数作为参数                 | ⭐   |
| 方法装饰器 | target、propertyKey、descriptor 参数 | ⭐   |
| 属性装饰器 | Object.defineProperty 拦截           | ⭐   |
| 参数装饰器 | 装饰器参数                           |      |
| 装饰器工厂 | 返回装饰器的函数，可传递参数         | ⭐   |

**关键要点**：

- ⭐ 装饰器执行顺序：参数装饰器 → 方法装饰器 → 访问器装饰器 → 属性装饰器 → 类装饰器
- ⭐ 装饰器工厂是返回装饰器的函数，用于传递配置参数
- 🔥 Vue 3 的 defineComponent 内部封装了装饰器逻辑

---

## 阶段 08：声明文件、条件类型与 infer

**文件**：`08-advanced-types.ts`

| 知识点         | 说明                              | 频率 |
| -------------- | --------------------------------- | ---- |
| 条件类型       | `T extends U ? X : Y`             | ⭐   |
| infer 关键字   | 在条件类型中推断类型              | 🔥   |
| 分配式条件类型 | 联合类型自动展开计算              | ⭐   |
| 递归类型       | DeepPartial、DeepReadonly         | ⭐   |
| 模板字面量类型 | `get${Capitalize<K>}` 生成器      | ⭐   |
| 模块扩展       | `declare module 'vue'`            | ⭐   |
| 高级工具类型   | PartialBy、RequiredBy、Parameters | ⭐   |

**关键要点**：

- 🔥 **infer** 是类型推导的利器，用于从复杂类型中提取子类型
- ⭐ 分配式条件类型会自动将联合类型展开计算，用 `[]` 可阻止分配
- ⭐ 模板字面量类型可以拼接生成新的字符串字面量类型

---

## 阶段 09：Vue 3 SFC（单文件组件）TypeScript 实战

**文件**：`09-vue3-sfc.vue`

| 知识点               | 说明                     | 频率 |
| -------------------- | ------------------------ | ---- |
| defineProps 泛型写法 | `defineProps<Props>()`   | 🔥   |
| withDefaults         | 响应式默认值（Vue 3.3+） | 🔥   |
| defineEmits 类型化   | 完整类型声明             | 🔥   |
| toRefs / toRef       | 响应式解构               | ⭐   |
| 模板中类型收窄       | `v-if` + 类型守卫        | ⭐   |
| defineExpose         | 向父组件暴露方法         | ⭐   |

**关键要点**：

- 🔥 Vue 3.3+ 的 `defineProps<{...}>()` 泛型写法是未来主流
- ⭐ 模板中的 `v-if` 可以配合类型守卫实现类型收窄
- ⭐ `withDefaults` 让 props 默认值具有响应式

---

## 阶段 10：Vue 3 + TypeScript 实战 - Pinia 状态管理

**文件**：`10-pinia-store.vue`

| 知识点               | 说明                         | 频率 |
| -------------------- | ---------------------------- | ---- |
| Pinia Store 类型定义 | State/Getters/Actions 泛型化 | 🔥   |
| Store 完整示例       | User CRUD 操作               | 🔥   |
| 订阅 Store 变化      | watch 监听                   | ⭐   |
| Store 热更新         | acceptHMRUpdate              |      |

**关键要点**：

- 🔥 Setup Store 语法（`defineStore(id, () => {...})`）是类型安全最佳实践
- ⭐ 完整的泛型定义让 Store 的 state/getters/actions 都有类型提示
- ⭐ `acceptHMRUpdate` 支持开发环境热更新

---

## 阶段 11：模块与声明（常用语法补全）

**文件**：`11-modules-and-declarations.ts` + `shims-vue.d.ts`

| 知识点                           | 说明                                          | 频率 |
| -------------------------------- | --------------------------------------------- | ---- |
| `import type` / `export type`    | 类型专用导入，编译后完全擦除                  | 🔥   |
| `as const` 断言                  | 保持字面量类型，替代 enum 生成联合类型        | 🔥   |
| `Promise<T>` / `async/await`     | 异步函数类型、`Promise.all` 元组推断          | 🔥   |
| `try/catch` 中的 `unknown`       | TS 4.4+ catch 变量为 `unknown`，必须类型收窄  | ⭐   |
| `void` vs `undefined` vs `never` | 函数返回值三者区别                            | ⭐   |
| `declare module`                 | 扩展第三方模块类型（如 Vue 全局属性）         | ⭐   |
| `declare global`                 | 声明全局变量 / Window 扩展                    |      |
| 独立 `.d.ts` 文件                | `*.vue` 模块声明、`import.meta.env`、静态资源 | 🔥   |

**关键要点**：

- 🔥 `import type` 在 Volar/vue-tsc 项目中几乎每个文件都会用到
- 🔥 `as const` + `typeof X[number]` 是**替代 enum 的主流写法**
- ⭐ catch 变量是 `unknown`，需用 `instanceof Error` 收窄后再访问 `.message`
- 🔥 `shims-vue.d.ts` 展示真实 Vue 3 项目中 `.d.ts` 文件的写法

---

## 阶段 12：Vue 3 SFC 进阶写法（Vue 3.3+ / 3.4+ / 3.5+）

**文件**：`12-vue3-sfc-advanced.vue`

| 知识点                       | 说明                                             | 频率 |
| ---------------------------- | ------------------------------------------------ | ---- |
| `<script setup generic="T">` | 泛型组件，父组件传值自动推断类型                 | 🔥   |
| `defineModel<T>()`           | v-model 现代写法（Vue 3.4+），读写 `.value` 即可 | 🔥   |
| 具名 v-model                 | `defineModel<T>('name')` 支持多个 v-model        | ⭐   |
| `defineSlots<T>()`           | 插槽类型化（Vue 3.3+），作用域插槽参数有类型提示 | 🔥   |
| `useTemplateRef<T>(name)`    | 模板 ref 新 API（Vue 3.5+），无需写 `\| null`    | ⭐   |
| `defineEmits` 对象字面量写法 | `{ event: [args] }` 比调用签名元组更简洁         | 🔥   |
| `defineExpose`               | 向父组件暴露方法，保持类型提示                   | ⭐   |

**关键要点**：

- 🔥 **泛型组件**是 Vue 3 + TS 写通用列表 / 表格组件的最佳实践
- 🔥 `defineModel` 让 v-model 不再需要手动写 `props + emit` 两处样板代码
- ⭐ `useTemplateRef` 比老的 `ref<HTMLElement \| null>(null)` 更直观

---

## 学习路径建议

1. **入门**：01 → 02 → 03（基础语法）
2. **进阶**：04 → 11 → 05（类型守卫 + 常用语法补全 + Vue 3 核心模式）
3. **实战**：06 → 09 → 12 → 10（综合应用 + SFC 进阶 + Pinia）
4. **深入（可选）**：08 → 07（高级类型 + 装饰器附录）

## 下一步

- 学习在真实 Vue 3 项目中应用这些模式
- 研究 Vue 3 官方类型定义源码
- 尝试为的开源库编写声明文件