CSSNumericValue 怎样在兼容单位之间转换数值

我在处理响应式组件的尺寸规则时，最容易混在一起的是“数值”和“数值的单位”。字符串里的 "12px" 适合展示，却不适合继续做类型判断；而 CSS Typed OM 可以把它表达成带单位的对象。CSSNumericValue 的关键用法是：先明确数值属于哪一类，再把它转换到同类的目标单位。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/CSSNumericValue

长度单位之间通常可以通过 CSSNumericValue.to() 转换，但百分比、时间、角度等不同类型不能因为都长得像数字就直接互换。生产代码还应先做能力检测，并为不支持 Typed OM 的浏览器保留字符串或布局测量回退。

先把带单位的 CSS 数值变成可判断的对象

CSSUnitValue 表示一个单一单位的数值，value 是数值本身，unit 是单位名。它继承自 CSSNumericValue，因此可以使用 type()、to() 等数值操作。下面的例子只演示对象关系，不依赖本地浏览器截图。

// 将带单位的长度统一到 px，并保留异常信息
function convertLengthToPx(number, unit) {
  // CSSUnitValue 把数值和单位放在同一个可操作对象中
  const source = new CSSUnitValue(number, unit);

  // type() 用来查看数值类别；这里只接受 length
  const numericType = source.type();
  if (numericType.length !== 1) {
    throw new TypeError("输入值不是单一长度类型");
  }

  try {
    // to() 返回目标单位的新 CSSNumericValue，不修改 source
    return source.to("px");
  } catch (error) {
    // 单位不兼容时交给调用方决定回退策略
    throw new TypeError(`无法把 ${unit} 转成 px：${error.message}`);
  }
}

const converted = convertLengthToPx(10, "cm");
console.log(converted.value, converted.unit);

这里的重点不是把任意字符串强行换算，而是让转换入口接收明确的单位对象。to("px") 会返回新的对象，原来的输入仍然保留原单位；这使得同一个输入可以服务于不同的展示或布局分支。

转换前先看类型，避免把不同维度混在一起

CSSNumericValue.type() 返回数值类型信息。长度、角度、时间和分辨率属于不同的 CSS 数值类别；即使它们都能写成“数字加单位”，也不能把 10px 当成 10s 或 10deg 来换算。

实际项目里，可以把转换函数的输入收窄成一个明确领域，例如只接受长度。对来自样式表的动态值，不要默认它一定是 CSSUnitValue：数学表达式可能产生 CSSMathValue，复合值还可能包含多个项。先检查对象能力，再决定是继续使用 Typed OM，还是回到 CSS 字符串。

// 只把单一 length 值转换为目标单位
function tryConvert(value, targetUnit) {
  // 先确认对象提供 type() 和 to()，避免旧环境直接抛出引用错误
  if (!value || typeof value.type !== "function" || typeof value.to !== "function") {
    return { ok: false, reason: "当前环境没有可用的 CSSNumericValue 接口" };
  }

  const type = value.type();
  if (type.length !== 1) {
    return { ok: false, reason: "只接受单一长度值" };
  }

  try {
    // 目标单位不兼容时由 to() 抛出异常
    return { ok: true, value: value.to(targetUnit) };
  } catch (error) {
    return { ok: false, reason: "目标单位与输入类型不兼容" };
  }
}

异常处理应当围绕“调用方下一步做什么”来设计：如果只是展示尺寸，可以保留原始 CSS 文本；如果必须得到实际像素，则需要让浏览器完成布局后再读取对应的计算样式或尺寸，而不是私自给百分比套一个固定换算比例。

兼容单位才能转换，不兼容时要保留回退

MDN 将 CSSNumericValue 标记为 Limited availability，因此不能把它当作所有浏览器都存在的基础接口。启用前先检查 CSSNumericValue、CSSUnitValue 和目标方法；不满足时，把原始值继续交给 CSS，或采用项目已有的布局测量方案。

这条边界也适用于 computedStyleMap()：它返回的是可读的 StylePropertyMapReadOnly，数值可以保留 CSS 的类型信息，但它本身不是“把所有单位都变成 px”的万能入口。只有在目标属性和浏览器能力都明确时，才把结果交给 Typed OM 转换。

我会这样做最后的取舍

• 只处理单一长度值时，用 CSSUnitValue 建模，再调用 type() 与 to()。
• 遇到复合数学值、百分比或不兼容单位时，不猜换算结果，保留原值或转入布局测量。
• 把能力检测放在功能入口，Typed OM 不可用时让 CSS 字符串方案继续工作。

对我来说，CSSNumericValue 的价值不是替代所有 CSS 字符串，而是为“需要继续计算的数值”提供清楚的类型边界。只要把可转换范围和回退责任写在接口旁边，尺寸处理就不会因为一个看似普通的单位字符串变成隐蔽的兼容性问题。

相关问题

CSSNumericValue.to() 会修改原对象吗？

不会。它返回目标单位的数值对象，原对象仍保持自己的数值和单位；需要同时保留多个单位时，可以分别保存返回值。

为什么百分比不能按固定比例转成 px？

百分比通常依赖属性和包含块的上下文，缺少布局参照物时没有唯一的像素结果。应保留百分比，或在布局完成后读取实际尺寸。