当前位置：首页 > news >正文

TypeScript 联合类型

news 2026/5/31 15:55:01

TypeScript 中的联合类型（Union Types）详解

联合类型是 TypeScript 类型系统中最强大的特性之一，使用|（竖线）将多个类型组合起来，表示一个值可以是几种类型中的任意一种。

1. 基本语法与用法

letid:string|number=123;// 可以是 string 或 numberid="abc123";// OK// id = true; // 错误：boolean 不属于联合类型

常见基础联合类型：

letflag:boolean|null=true;flag=null;// OKletstatus:"loading"|"success"|"error"="loading";status="success";// OK// status = "failed"; // 错误：不是这三个值之一

2. 类型缩小（Type Narrowing）—— 联合类型的核心优势

TypeScript 会根据条件判断自动缩小变量的类型范围，提供更精确的类型检查和智能提示。

functionprintId(id:string|number){// 这里 id 是 string | numberif(typeofid==="string"){// TS 自动缩小：这里 id 是 stringconsole.log(id.toUpperCase());// 安全调用字符串方法console.log(id.length);}else{// TS 自动缩小：这里 id 是 numberconsole.log(id.toFixed(2));// 安全调用数字方法}}printId(123);// 调用数字分支printId("hello");// 调用字符串分支

其他常见类型守卫（Type Guards）方式：

functionprocess(value:string|null|number){if(value===null){// value 被缩小为 nullreturn;}if(typeofvalue==="string"){// value 被缩小为 stringvalue.toLowerCase();}else{// value 被缩小为 numbervalue.toPrecision(2);}}

typeof检查原始类型（string/number/boolean/symbol/function）
===/!==检查字面量或 null/undefined
自定义类型守卫函数：

functionisString(value:any):valueisstring{returntypeofvalue==="string";}functionlog(value:string|number){if(isString(value)){// value 被缩小为 stringconsole.log(value.repeat(2));}}

3. 与其他类型的组合

a. 联合类型 + 数组

letmixedArray:(string|number)[]=[1,"two",3,"four"];mixedArray.push(5);// OKmixedArray.push("six");// OK// mixedArray.push(true); // 错误

b. 联合类型 + 对象属性

interfaceSuccess{type:"success";data:string;}interfaceError{type:"error";message:string;}typeResult=Success|Error;// 可辨识联合（Discriminated Union）functionhandleResult(result:Result){if(result.type==="success"){// result 被缩小为 Successconsole.log(result.data.toUpperCase());}else{// result 被缩小为 Errorconsole.log("错误："+result.message);}}

可辨识联合是联合类型的最佳实践模式：通过一个共同的字面量属性（tag，如type、kind）来区分不同分支。

4. 联合类型与函数

// 参数为联合类型functionformat(value:string|number):string{returntypeofvalue==="number"?value.toFixed(2):value.trim();}// 返回值为联合类型functiongetStatus():"ok"|"failed"|null{returnMath.random()>0.5?"ok":"failed";}

5. 常见内置联合类型

string | null | undefined：常用于可选值（开启strictNullChecks时）
HTMLElement | null：如document.getElementById()
any可以看作是所有类型的联合（但不推荐使用）

6. 注意事项

联合类型的方法限制：只能调用所有类型共有的方法。

letvalue:string|number="hello";// value.toUpperCase(); // 错误：number 上没有这个方法value.toString();// OK：string 和 number 都有 toString()

使用类型守卫来安全访问特定类型的方法。

7. 最佳实践建议

场景	推荐用法
可能为空的值	`string
状态机	`“idle”
API 响应	可辨识联合（带`type`或`kind`字段）
多类型参数	联合类型 + 类型守卫函数
避免过度宽松	尽量用具体字面量联合，而不是 `string