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]
CSSNumericValuecan't be constructed directly. Instances are created by the numeric factory functions such asCSS.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
CSSNumericValuefrom a string of CSS, such as"42px".
- : Creates a
Instance methods
- CSSNumericValue.add()
- : Returns a new value that is the sum of the
CSSNumericValueand the supplied values.
- : Returns a new value that is the sum of the
- CSSNumericValue.sub()
- : Returns a new value that is the
CSSNumericValueminus the supplied values.
- : Returns a new value that is the
- CSSNumericValue.mul()
- : Returns a new value that is the
CSSNumericValuemultiplied by the supplied values.
- : Returns a new value that is the
- CSSNumericValue.div()
- : Returns a new value that is the
CSSNumericValuedivided by the supplied values.
- : Returns a new value that is the
- CSSNumericValue.min()
- : Returns the smallest of the
CSSNumericValueand the supplied values, or a CSSMathMin if they don't all have the same unit.
- : Returns the smallest of the
- CSSNumericValue.max()
- : Returns the largest of the
CSSNumericValueand the supplied values, or a CSSMathMax if they don't all have the same unit.
- : Returns the largest of the
- CSSNumericValue.equals()
- : Returns
trueif every value passed is the same as theCSSNumericValue, written with the same values and units, andfalseotherwise.
- : Returns
- CSSNumericValue.to()
- : Converts the
CSSNumericValueto a CSSUnitValue in the specified unit.
- : Converts the
- CSSNumericValue.toSum()
- : Converts the
CSSNumericValueinto a CSSMathSum whose terms use only the specified units, or into the simplest such sum if no units are given.
- : Converts the
- CSSNumericValue.type()
- : Returns a
CSSNumericTypedictionary that describes the type of theCSSNumericValue, such as a length or an angle.
- : Returns a
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。离线整理了版式、链接和媒体显示。
