大网数据广告活动
Web 标准与前端开发

CSSNumericValue

· 52CE 我爱测

The **`CSSNumericValue`** interface of the CSS Typed Object Model API is the base interface for objects that represent CSS numeric values, such as `10px`, `50%`, or `calc(1px + 2em)`. It provides the common methods for basic arithmetic, comparing values, and converting between un

CSS Typed Object Model API

The CSSNumericValue interface of the CSS Typed Object Model API is the base interface for objects that represent CSS numeric values, such as 10px, 50%, or calc(1px + 2em). It provides the common methods for basic arithmetic, comparing values, and converting between units.

[!NOTE] CSSNumericValue can't be constructed directly. Instances are created by the numeric factory functions such as CSS.px(), by CSSNumericValue.parse_static, or by reading a style, and are always one of its subtypes, listed below.

Instance properties

None.

Static methods

  • CSSNumericValue.parse_static
    • : Creates a CSSNumericValue from a string of CSS, such as "42px".

Instance methods

  • CSSNumericValue.add()
    • : Returns a new value that is the sum of the CSSNumericValue and the supplied values.
  • CSSNumericValue.sub()
    • : Returns a new value that is the CSSNumericValue minus the supplied values.
  • CSSNumericValue.mul()
    • : Returns a new value that is the CSSNumericValue multiplied by the supplied values.
  • CSSNumericValue.div()
    • : Returns a new value that is the CSSNumericValue divided by the supplied values.
  • CSSNumericValue.min()
    • : Returns the smallest of the CSSNumericValue and the supplied values, or a CSSMathMin if they don't all have the same unit.
  • CSSNumericValue.max()
    • : Returns the largest of the CSSNumericValue and the supplied values, or a CSSMathMax if they don't all have the same unit.
  • CSSNumericValue.equals()
    • : Returns true if every value passed is the same as the CSSNumericValue, written with the same values and units, and false otherwise.
  • CSSNumericValue.to()
    • : Converts the CSSNumericValue to a CSSUnitValue in the specified unit.
  • CSSNumericValue.toSum()
    • : Converts the CSSNumericValue into a CSSMathSum whose terms use only the specified units, or into the simplest such sum if no units are given.
  • CSSNumericValue.type()
    • : Returns a CSSNumericType dictionary that describes the type of the CSSNumericValue, such as a length or an angle.

Interfaces based on CSSNumericValue

The following interfaces inherit from CSSNumericValue:

  • CSSMathClamp
  • CSSMathInvert
  • CSSMathMax
  • CSSMathMin
  • CSSMathNegate
  • CSSMathProduct
  • CSSMathSum
  • CSSMathValue
  • CSSUnitValue

Examples

Doing arithmetic with numeric values

The following code adds and multiplies numeric values created with the numeric factory functions. When the result can be written as a single value in one unit, the method returns a CSSUnitValue. Otherwise, it returns one of the CSSMathValue subtypes, which keep the terms separate.

const sameUnits = CSS.px(10).add(CSS.px(5));
console.log(sameUnits.constructor.name); // "CSSUnitValue"
console.log(sameUnits.toString()); // "15px"

const mixedUnits = CSS.px(10).add(CSS.percent(5));
console.log(mixedUnits.constructor.name); // "CSSMathSum"
console.log(mixedUnits.toString()); // "calc(10px + 5%)"

const doubled = CSS.px(10).mul(2);
console.log(doubled.toString()); // "20px"

Growing a box with arithmetic

This example uses the arithmetic methods to make a box wider each time a button is clicked, up to a maximum width. Note that there is hidden logging code that isn't relevant to the example.

HTML

First we define the box to grow, and the button we use to grow it.

<div id="grow-box"></div>
<button id="grow-button">Grow by 20px</button>
<pre id="log"></pre>

CSS

The box starts 100 pixels wide.

#grow-box {
  width: 100px;
  height: 50px;
  margin-bottom: 1rem;
  background-color: #6666dd;
}
#log {
  height: 120px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

The code first gets the box and the button, and sets the maximum width as a CSSUnitValue. It then uses Element.computedStyleMap to get the box's starting width, and logs it along with its CSSNumericValue.type().

const growBox = document.getElementById("grow-box");
const growButton = document.getElementById("grow-button");
const maxWidth = CSS.px(300);

const startWidth = growBox.computedStyleMap().get("width");
log(`start: ${startWidth}, type: ${JSON.stringify(startWidth.type())}`);

Each time the button is clicked, the handler reads the box's current width and uses CSSNumericValue.add() to add 20 pixels to it. It then uses CSSNumericValue.min() to make sure the new width is never larger than maxWidth. Because all the values are in px, each method returns a single CSSUnitValue, which the handler sets as the box's new width.

growButton.addEventListener("click", () => {
  const width = growBox.computedStyleMap().get("width");
  const newWidth = width.add(CSS.px(20)).min(maxWidth);
  growBox.attributeStyleMap.set("width", newWidth);
  log(`width: ${newWidth}`);
});

Result

Click the button to grow the box. The log starts with the box's width and its type, {"length":1}, which means the width is a length. It then shows the new width after each click, and the box stops growing at 300px.

Growing a box with arithmetic

Specifications

Browser compatibility

See also

  • CSSImageValue
  • CSSKeywordValue
  • CSSTransformValue
  • CSSUnparsedValue

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。