TypeScript 中如何实现带双数值参数的 ClampedNumber 钳制数字类型
带范围约束的自定义数值类型优雅实现方案
核心实现思路
TypeScript 本身没有原生的数值范围限定类型,要实现等价于ClampedNumber<min, max>的效果,需要结合品牌类型(Brand Type)做类型层面的范围隔离 + 统一工厂函数做运行时真实校验,避免只靠类型约束、运行时无兜底的问题。
分步实现
1. 定义基础的ClampedNumber泛型
用品牌标记给带范围约束的数值做类型区分,让TS能识别「这是一个被限定在固定区间的数值」,和普通number类型做隔离:
/** * 带范围标记的数值类型 * @template TMin 合法范围下限 * @template TMax 合法范围上限 */ type ClampedNumber<TMin extends number, TMax extends number> = number & { // 唯一品牌标记,保证不同范围的数值类型互斥 readonly __brand: unique symbol; readonly __range: [TMin, TMax]; }
2. 实现统一的安全构造工厂
封装带运行时夹取逻辑的构造函数,避免外部直接绕过校验生成违规值:
/** * 生成指定范围的ClampedNumber构造器 * @param min 范围下限 * @param max 范围上限 */ function createClamped<TMin extends number, TMax extends number>(min: TMin, max: TMax) { // 对输入值做真实的范围夹取,保证运行时值不会越界 return (input: number): ClampedNumber<TMin, TMax> => { const safeValue = Math.min(Math.max(input, min), max); // 给校验通过的值打上对应的品牌类型标记 return safeValue as ClampedNumber<TMin, TMax>; }; }
3. 替换原有接口的普通number字段
把原本Angle接口里的裸number类型,替换为带明确范围限定的ClampedNumber:
// 定义角度合法范围为0~360度 type Angle = { value: ClampedNumber<0, 360>; } // 配套生成对应范围的角度值构造器 const createAngleValue = createClamped(0, 360);
方案优势
- 类型隔离性:不同范围的
ClampedNumber是完全独立的类型,比如ClampedNumber<0, 360>和ClampedNumber<-90, 90>不能互相赋值,TS会直接拦截类型混淆的问题 - 复用性:所有需要做数值范围限定的场景,都可以复用同一套泛型和工厂函数,不需要为每个范围单独写重复的校验逻辑
- 双重保障:类型层的约束和运行时的真实夹取逻辑统一,不会出现类型合法但运行时值越界的问题
使用示例
// 合法构造:值在0~360范围内 const normalAngle: Angle = { value: createAngleValue(120) }; // 越界输入自动被夹取到合法范围,类型层面完全合法 const outOfRangeAngle: Angle = { value: createAngleValue(480) }; // 运行时实际值为360 // 直接赋值普通number会被TS拦截 const wrongAngle: Angle = { value: 60 }; // 类型报错:number无法赋值给带品牌标记的ClampedNumber类型
内容的提问来源于stack exchange,提问作者defrid
相关产品推荐
相关产品推荐

