Vue 3 中的 TypeScript 基础
一、为什么 Vue 项目需要 TypeScript
JavaScript 允许对象结构在运行时自由变化。项目较大后，常见问题包括：
- 接口字段拼写错误；
- 函数参数传错类型；
null数据没有判断；- 重构字段后遗漏调用位置；
- 编辑器无法提示复杂对象结构。
TypeScript 在代码运行前进行类型检查：
编写代码 ↓ TypeScript 检查类型 ↓ 编译成 JavaScript ↓ 浏览器执行它不会替代运行时数据校验，但可以显著减少开发阶段错误。
二、在 Vue 中启用 TypeScript
<script setup lang="ts">lang="ts"表示脚本使用 TypeScript。
三、基础类型
consttitle:string='数字孪生';consttemperature:number=1650;constloading:boolean=false;TypeScript 通常能够自动推断：
consttitle='数字孪生';// 推断为 string没有必要为每个简单变量都重复标注类型。
四、数组类型
constsignalCodes:string[]=['BATH_TEMP','O2_FLOW'];对象数组：
interfaceSignalItem{code:string;label:string;value:number;}constsignals:SignalItem[]=[];五、使用interface描述对象
interfaceHeatHeader{heatId:string;converterNo:string;steelGrade:string;status:string;}使用：
constheat:HeatHeader={heatId:'H001',converterNo:'BOF-1',steelGrade:'Q235',status:'running'};少字段、字段类型错误或多余字段都可能得到编辑器提示。
六、可选属性
interfaceHeatHeader{heatId:string;modelVersion?:string;}?表示字段可能不存在。
读取时应考虑缺失：
constversion=heat.modelVersion||'unknown';七、联合类型
typeDisplayMode='realtime'|'playback';变量只能使用规定值：
constmode=ref<DisplayMode>('playback');mode.value='realtime';mode.value='other';// 类型错误联合类型特别适合：
- 页面模式；
- 风险等级；
- 请求状态；
- 视角名称；
- 设备阶段。
八、可空类型
接口数据加载前通常没有值：
constheatMeta=ref<HeatHeader|null>(null);使用时先判断：
if(!heatMeta.value){return;}console.log(heatMeta.value.heatId);或者使用可选链：
constid=heatMeta.value?.heatId||'--';T | null能强制开发者考虑数据尚未返回的阶段。
九、ref<T>()泛型
constloading=ref<boolean>(false);constwarnings=ref<WarningItem[]>([]);constheatMeta=ref<HeatHeader|null>(null);简单值可以依赖自动推断：
constloading=ref(false);空数组和null初始值通常更需要显式泛型，因为 TypeScript 无法从初始值推断完整业务类型。
十、computed<T>()泛型
constcurrentHeat=computed<HeatHeader|null>(()=>{returnsnapshot.value?.heat||playback.value?.heat||null;});多数情况下 TypeScript 可以自动推断，但显式标注有助于确保分支返回值一致。
十一、函数参数和返回值
functionformatTemperature(value:number|null):string{if(value===null){return'--';}return`${value.toFixed(0)}°C`;}参数类型防止调用者传入错误数据，返回值类型防止函数不同分支返回不一致。
十二、对象映射Record
constlabelStyles=ref<Record<string,string>>({});它表示：
键是 string 值也是 string例如：
labelStyles.value={lance:'left: 20px; top: 30px;',vessel:'left: 100px; top: 80px;'};也可以使用对象值：
interfacePositionStyle{left:string;top:string;}conststyles=ref<Record<string,PositionStyle>>({});十三、类型别名与接口怎样选择
interface
适合描述对象结构：
interfaceMetricCard{key:string;label:string;value:number|null;}type
适合联合类型、组合类型或简单别名：
typeRiskLevel='normal'|'warning'|'critical';typeNullableNumber=number|null;两者能力有重叠，项目内保持统一风格更重要。
十四、import type
importtype{HeatHeader,HeatPlayback}from'@/api/heat/types';import type表示这些导入只参与类型检查，不需要出现在运行时 JavaScript 中。
普通值导入仍使用：
import{getHeatDetail}from'@/api/heat';可以在同一条导入中混合：
import{buildPlaybackGroups,typePlaybackGroup}from'./playback';十五、定时器类型
浏览器和 Node.js 对定时器返回类型的声明可能不同。项目中常用：
consttimer=ref<ReturnType<typeofsetInterval>|null>(null);这样 TypeScript 会根据当前环境自动得到正确类型。
十六、类型保护
typeof
functionreadNumber(value:unknown):number|null{if(typeofvalue==='number'&&Number.isFinite(value)){returnvalue;}returnnull;}数组判断
if(Array.isArray(value)){console.log(value.length);}自定义类型保护
interfaceFieldFrame{temperature:number[];velocity:number[];}functionisFieldFrame(value:unknown):valueisFieldFrame{if(!value||typeofvalue!=='object'){returnfalse;}constframe=valueasPartial<FieldFrame>;returnArray.isArray(frame.temperature)&&Array.isArray(frame.velocity);}十七、unknown与any
any
functionhandleError(error:any){console.log(error.message);}any会关闭类型检查。
unknown
functionhandleError(error:unknown){constmessage=errorinstanceofError?error.message:String(error);}unknown要求先判断类型，更安全。
接口错误、外部 JSON 和第三方数据通常适合使用unknown再缩小类型。
十八、接口类型不等于运行时验证
即使声明：
constresponse:HeatHeader=awaitfetchData();也不能保证后端实际返回正确字段。TypeScript 类型会在编译后消失。
重要接口仍应进行运行时检查，例如：
if(!data||typeofdata.heatId!=='string'){thrownewError('接口字段缺失');}大型项目可以使用 Zod 等校验库，但快速入门阶段应先建立“类型声明不是数据验证”的意识。
十九、Vue Props 的 TypeScript
interfaceHistoryState{timestamp:string;temperature:number|null;}defineProps<{state:HistoryState;title?:string;}>();事件也可以声明类型：
constemit=defineEmits<{change:[index:number];close:[];}>();二十、一个完整示例
<script setup lang="ts"> import { computed, ref } from 'vue'; interface SignalPoint { code: string; value: number; unit?: string; } type DisplayMode = 'realtime' | 'playback'; const displayMode = ref<DisplayMode>('playback'); const signals = ref<SignalPoint[]>([]); const selectedCode = ref<string | null>(null); const selectedSignal = computed<SignalPoint | null>(() => { if (!selectedCode.value) { return null; } return signals.value.find( item => item.code === selectedCode.value ) || null; }); function formatSignal(point: SignalPoint | null): string { if (!point) { return '--'; } return `${point.value} ${point.unit || ''}`.trim(); } </script>二十一、常见误区
1. 为了不报错全部使用any
短期消除提示，长期失去类型系统价值。
2. 认为 TypeScript 会自动校验后端数据
类型只在开发和编译阶段生效。
3. 对简单值过度标注
constloading:boolean=false;可以依赖推断，减少重复代码。
4. 不处理null
接口数据、DOM 引用和可选结果经常需要显式可空类型。
二十二、本章小结
Vue 项目中最需要掌握的 TypeScript 写法包括：
interface 联合类型 T | null ref<T>() computed<T>() 函数参数与返回值 Record import type unknown 与类型保护下一章将学习 Vue Router，理解 URL、页面组件和多模式页面之间的关系。
Vue 3 中的 TypeScript 基础
一、为什么 Vue 项目需要 TypeScript
JavaScript 允许对象结构在运行时自由变化。项目较大后，常见问题包括：
- 接口字段拼写错误；
- 函数参数传错类型；
null数据没有判断；- 重构字段后遗漏调用位置；
- 编辑器无法提示复杂对象结构。
TypeScript 在代码运行前进行类型检查：
编写代码 ↓ TypeScript 检查类型 ↓ 编译成 JavaScript ↓ 浏览器执行它不会替代运行时数据校验，但可以显著减少开发阶段错误。
二、在 Vue 中启用 TypeScript
<script setup lang="ts">lang="ts"表示脚本使用 TypeScript。
三、基础类型
consttitle:string='数字孪生';consttemperature:number=1650;constloading:boolean=false;TypeScript 通常能够自动推断：
consttitle='数字孪生';// 推断为 string没有必要为每个简单变量都重复标注类型。
四、数组类型
constsignalCodes:string[]=['BATH_TEMP','O2_FLOW'];对象数组：
interfaceSignalItem{code:string;label:string;value:number;}constsignals:SignalItem[]=[];五、使用interface描述对象
interfaceHeatHeader{heatId:string;converterNo:string;steelGrade:string;status:string;}使用：
constheat:HeatHeader={heatId:'H001',converterNo:'BOF-1',steelGrade:'Q235',status:'running'};少字段、字段类型错误或多余字段都可能得到编辑器提示。
六、可选属性
interfaceHeatHeader{heatId:string;modelVersion?:string;}?表示字段可能不存在。
读取时应考虑缺失：
constversion=heat.modelVersion||'unknown';七、联合类型
typeDisplayMode='realtime'|'playback';变量只能使用规定值：
constmode=ref<DisplayMode>('playback');mode.value='realtime';mode.value='other';// 类型错误联合类型特别适合：
- 页面模式；
- 风险等级；
- 请求状态；
- 视角名称；
- 设备阶段。
八、可空类型
接口数据加载前通常没有值：
constheatMeta=ref<HeatHeader|null>(null);使用时先判断：
if(!heatMeta.value){return;}console.log(heatMeta.value.heatId);或者使用可选链：
constid=heatMeta.value?.heatId||'--';T | null能强制开发者考虑数据尚未返回的阶段。
九、ref<T>()泛型
constloading=ref<boolean>(false);constwarnings=ref<WarningItem[]>([]);constheatMeta=ref<HeatHeader|null>(null);简单值可以依赖自动推断：
constloading=ref(false);空数组和null初始值通常更需要显式泛型，因为 TypeScript 无法从初始值推断完整业务类型。
十、computed<T>()泛型
constcurrentHeat=computed<HeatHeader|null>(()=>{returnsnapshot.value?.heat||playback.value?.heat||null;});多数情况下 TypeScript 可以自动推断，但显式标注有助于确保分支返回值一致。
十一、函数参数和返回值
functionformatTemperature(value:number|null):string{if(value===null){return'--';}return`${value.toFixed(0)}°C`;}参数类型防止调用者传入错误数据，返回值类型防止函数不同分支返回不一致。
十二、对象映射Record
constlabelStyles=ref<Record<string,string>>({});它表示：
键是 string 值也是 string例如：
labelStyles.value={lance:'left: 20px; top: 30px;',vessel:'left: 100px; top: 80px;'};也可以使用对象值：
interfacePositionStyle{left:string;top:string;}conststyles=ref<Record<string,PositionStyle>>({});十三、类型别名与接口怎样选择
interface
适合描述对象结构：
interfaceMetricCard{key:string;label:string;value:number|null;}type
适合联合类型、组合类型或简单别名：
typeRiskLevel='normal'|'warning'|'critical';typeNullableNumber=number|null;两者能力有重叠，项目内保持统一风格更重要。
十四、import type
importtype{HeatHeader,HeatPlayback}from'@/api/heat/types';import type表示这些导入只参与类型检查，不需要出现在运行时 JavaScript 中。
普通值导入仍使用：
import{getHeatDetail}from'@/api/heat';可以在同一条导入中混合：
import{buildPlaybackGroups,typePlaybackGroup}from'./playback';十五、定时器类型
浏览器和 Node.js 对定时器返回类型的声明可能不同。项目中常用：
consttimer=ref<ReturnType<typeofsetInterval>|null>(null);这样 TypeScript 会根据当前环境自动得到正确类型。
十六、类型保护
typeof
functionreadNumber(value:unknown):number|null{if(typeofvalue==='number'&&Number.isFinite(value)){returnvalue;}returnnull;}数组判断
if(Array.isArray(value)){console.log(value.length);}自定义类型保护
interfaceFieldFrame{temperature:number[];velocity:number[];}functionisFieldFrame(value:unknown):valueisFieldFrame{if(!value||typeofvalue!=='object'){returnfalse;}constframe=valueasPartial<FieldFrame>;returnArray.isArray(frame.temperature)&&Array.isArray(frame.velocity);}十七、unknown与any
any
functionhandleError(error:any){console.log(error.message);}any会关闭类型检查。
unknown
functionhandleError(error:unknown){constmessage=errorinstanceofError?error.message:String(error);}unknown要求先判断类型，更安全。
接口错误、外部 JSON 和第三方数据通常适合使用unknown再缩小类型。
十八、接口类型不等于运行时验证
即使声明：
constresponse:HeatHeader=awaitfetchData();也不能保证后端实际返回正确字段。TypeScript 类型会在编译后消失。
重要接口仍应进行运行时检查，例如：
if(!data||typeofdata.heatId!=='string'){thrownewError('接口字段缺失');}大型项目可以使用 Zod 等校验库，但快速入门阶段应先建立“类型声明不是数据验证”的意识。
十九、Vue Props 的 TypeScript
interfaceHistoryState{timestamp:string;temperature:number|null;}defineProps<{state:HistoryState;title?:string;}>();事件也可以声明类型：
constemit=defineEmits<{change:[index:number];close:[];}>();二十、一个完整示例
<script setup lang="ts"> import { computed, ref } from 'vue'; interface SignalPoint { code: string; value: number; unit?: string; } type DisplayMode = 'realtime' | 'playback'; const displayMode = ref<DisplayMode>('playback'); const signals = ref<SignalPoint[]>([]); const selectedCode = ref<string | null>(null); const selectedSignal = computed<SignalPoint | null>(() => { if (!selectedCode.value) { return null; } return signals.value.find( item => item.code === selectedCode.value ) || null; }); function formatSignal(point: SignalPoint | null): string { if (!point) { return '--'; } return `${point.value} ${point.unit || ''}`.trim(); } </script>二十一、常见误区
1. 为了不报错全部使用any
短期消除提示，长期失去类型系统价值。
2. 认为 TypeScript 会自动校验后端数据
类型只在开发和编译阶段生效。
3. 对简单值过度标注
constloading:boolean=false;可以依赖推断，减少重复代码。
4. 不处理null
接口数据、DOM 引用和可选结果经常需要显式可空类型。
二十二、本章小结
Vue 项目中最需要掌握的 TypeScript 写法包括：
interface 联合类型 T | null ref<T>() computed<T>() 函数参数与返回值 Record import type unknown 与类型保护下一章将学习 Vue Router，理解 URL、页面组件和多模式页面之间的关系。
