SoFunction
Updated on 2025-03-04

d3-scale Detailed explanation of the usage example of d3-scaleTime

Install

npm install d3-scale

use

import { scaleTime } from 'd3-scale';
var x = scaleTime()
    .domain([new Date(2000, 0, 1, 0), new Date(2000, 0, 1, 2)]);

API

Continuous scale maps a continuous, quantitative input domain to a continuous output range. If the range is also numeric, the mapping may be inverted. You cannot directly build a continuous scale, but try linear, power, logarithmic, characteristic, radial, time, or sequential color scales.

continuous(value)

Given a value in the domain, return the corresponding value in the range. If the given value is outside the domain domain and clamping is not enabled, the mapping may be inferred, so that the returned value is out of range.

For example, to apply a location encoding:

var x = ()
    .domain([10, 130])
    .range([0, 960]);
x(20); // 80
x(50); // 320

Or apply color coding:

var color = ()
    .domain([10, 100])
    .range(["brown", "steelblue"]);
color(20); // "#9a3439"
color(50); // "#7b5167"

(value)

Given a value in the range, return the corresponding value in the domain. Reversal is useful for interactions, such as determining the data value corresponding to the mouse position.

For example, to invert a position encoding:

var x = ()
    .domain([10, 130])
    .range([0, 960]);
(80); // 20
(320); // 50

If the given value is outside the range and clamping is not enabled, the mapping result corresponding to the value may be extrapolated, so that the returned value is outside the domain. This method is only supported when the range is a number. If the range is not a number, NaN is returned.

For the valid value y in the range, continuous((y)) is approximately equal to y; similarly, for the valid value x in the domain, (continuous(x)) is approximately equal to x. Due to the limitations of floating point accuracy, the proportion and its inverse may be inaccurate.

([domain])

If domain is specified, the domain of the scale is set to the specified array of numbers. The array must contain two or more elements. If the elements in a given array are not numbers, they will be forced to become numbers. If no domain is specified, a copy of the current domain is returned.

Although continuous color levels usually have two values ​​in their domain and range, specifying more than two values ​​will result in a sharded color level.

For example, to create a divergence color scale, interpolate between white and red with negative values, and between white and green with positive values:

var color = ()
    .domain([-1, 0, 1])
    .range(["red", "white", "green"]);
color(-0.5); // "rgb(255, 128, 128)"
color(+0.5); // "rgb(128, 192, 128)"

Internally, the shard scale performs a binary search of the range interpolator corresponding to the given domain value. Therefore, the fields must be arranged in ascending or descending order. If the domain and range have different lengths N and M, only *min(N,M)* elements will be taken for display.

([range])

If range is specified, the range of the scale is set to the specified array of values. The array must contain two or more elements. Unlike domains, elements in a given array need not be numbers; any values ​​supported by the underlying interpolator will work, but note that the numeric range is required for invert. If no range is specified, a copy of the current range of the tick is returned. See for more examples.

([range])

Set the scale range to the specified array of values, and set the scale interpolate to interpolateRound. This is a convenient method, equivalent to:

continuous
    .range(range)
    .interpolate();

Rounding interpolators are sometimes useful for avoiding anti-aliasing artifacts, but you can also consider the "crispEdges" style for shape rendering. Note that this interpolation can only be used in digital ranges.

(clamp)

If clamp is specified, clamp is enabled or disabled accordingly. If clamping is disabled and the scale is passed a value outside the domain, the scale may return an out-of-domain value through extrapolation. If clamping is enabled, the return value of the tick is always within the range of the tick.

clamping is commonly used. For example:

var x = ()
    .domain([10, 130])
    .range([0, 960]);
x(-10); // -160, outside range
(-160); // -10, outside domain
(true);
x(-10); // 0, clamped to range
(-160); // 10, clamped to domain

([value]

If a value is specified, sets the output value of the scale for the undefined (or NaN) input value and returns this scale. If no value is specified, the current unknown value is returned, which is undefined by default.

(interpolate)

If interpolate is specified, the range interpolate factory for the scale bar is set. This interpolator factory is used to create interpolators for each pair of adjacent values ​​in the range; these interpolators then map the normalized domain parameter t in [0, 1] to the corresponding values ​​in the range. If no factory is specified, the current interpolation factory of the scale is returned, which is default. See d3-interpolate for more interpolate.

For example, consider a divergent color scale with three color ranges.

var color = ()
    .domain([-100, 0, +100])
    .range(["red", "white", "green"]);

Create two interpolators inside the scale, which is equivalent to:

var i0 = ("red", "white"),
    i1 = ("white", "green");

A common reason to specify a custom interpolator is to change the color space of the interpolation. For example, to use HCL.

var color = ()
    .domain([10, 100])
    .range(["brown", "steelblue"])
    .interpolate();

Or provide Cubehelix with a custom gamma.

var color = ()
    .domain([10, 100])
    .range(["brown", "steelblue"])
    .interpolate((3));

Note: The default interpolator can reuse the return value. For example, if the range value is an object, the value interpoler always returns the same object, modifying it in place. This is usually acceptable if the range is used to set properties or styles (and is desirable for performance); however, if you need to store the return value of the range, you must specify your own interpolator or copy as appropriate.

([count])

Returns about how many representative values ​​are there in the scale domain. If no count is specified, the default is 10. The returned scale values ​​are uniformly spaced, have human-readable values ​​(such as multiples of 10), and are guaranteed to be within the domain range. Ticks are usually combined with visual data to display reference lines, or tick marks. The specified count is just an estimated value; the tick may return more or fewer values ​​depending on the domain. See d3-array's ticks.

([count[, specifier]])

Returns a numeric format function suitable for displaying the tick value, and automatically calculates the appropriate accuracy based on the fixed interval between the tick values. The specified count should be the same as the count used to generate the scale value.

An optional specifier allows custom formatting, where the precision of the format is automatically set by the scale to fit the scale interval. For example, to format percentage changes, you can write:

var x = ()
    .domain([-1, 1])
    .range([0, 960]);
var ticks = (5),
    tickFormat = (5, "+%");
(tickFormat); // ["-100%", "-50%", "+0%", "+50%", "+100%"]

If the specified person uses the format type s, the tick returns a format based on the SI-prefix of the maximum value in the field. If the specifier has specified an accuracy, this method is equivalent to. See.

([count])

Extend the domain so that it starts and ends with beautiful integer values. This method usually modifies the domain of the tick and can only extend the boundary to the nearest integer value. An optional tick count parameter allows greater control over the step size used to extend the bounds, ensuring that the returned tick will completely cover the domain. Nicing is useful if the domain is calculated from data, such as the degree of use, and may be irregular. For example, for a domain of [0.201479..., 0.996679...], a good domain might be [0.2, 1.0]. If the domain has more than two values, the division of the domain only affects the first and last values. See also d3-array's tickStep.

Extending a scale affects only the current domain; it does not automatically beautify the domain that is subsequently used. If necessary, you must redecorate the scale bar after setting up a new domain.

()

Returns an exact copy of this scale. Changes to this scale will not affect the returned scale and vice versa.

(start, stop, count[, specifier])

Returns a numeric format function suitable for displaying the tick value, and automatically calculates the appropriate accuracy based on the fixed interval between the determined tick values.

An optional specifier allows custom formatting, where the precision of the format is automatically set by the scale to fit the scale interval. For example, to format percentage changes, you can write:

var tickFormat = (-1, 1, 5, "+%");
tickFormat(-0.5); // "-50%"

If the specified person uses format type s, the tick returns a SI-prefix format based on the larger absolute values ​​of start and stop. If the specifier has specified an accuracy, this method is equivalent to.

([interval]) ([count])

Returns the representative date in the tick field. The returned tick values ​​are evenly spaced (mostly), have reasonable values ​​(such as midnight every day), and are guaranteed to be within the domain range. Ticks are usually combined with visual data to display reference lines, or tick marks.

An optional count can be specified to affect how many ticks are generated. If no count is specified, the default is 10. The specified count is just a reference value; the scale may return more or fewer values ​​depending on the field. For example, to create 10 default tick marks:

var x = ();
(10);
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 03:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 06:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 09:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 12:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 15:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 18:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 21:00:00 GMT-0800 (PST),
//  Sun Jan 02 2000 00:00:00 GMT-0800 (PST)]
// 10 were set but only 9 were returned

The following time intervals are considered as the default time interval:

  • 1-, 5-, 15- and 30-minute.
  • 1-, 3-, 6- and 12-hour.
  • 1- and 2-day.
  • 1-week.
  • 1- and 3-month.
  • 1-year.

In order to replace counting, a time interval can be specified explicitly. To trim the ticks generated at a given time interval, use.

For example, create ticks for a 15-minute interval:

var x = ()
    .domain([new Date(2000, 0, 1, 0), new Date(2000, 0, 1, 2)]);
((15));
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 02:00:00 GMT-0800 (PST)]

Or, pass a value function to:

((function(d) {
  return () % 15 === 0;
}));

Note: In some cases, for example, for daily marks, specifying a step will result in irregular intervals of punctuation because the time intervals have different lengths.

([count[, specifier]]) ([interval[, specifier]])

Returns a time format function suitable for displaying the tick value. The specified count or interval is currently ignored, but will be accepted for consistency with other scales (e.g.). If a format specifier is specified, this method is equivalent to format. If no specified specifier is specified, the default time format will be returned. The default multi-scale time format selects a human-readable representation based on the specified date, as follows:

  • %Y-- represents the year boundary, such as 2011.
  • %B - With the month as the boundary, like February.
  • %b %d - With week as the boundary, like February 6.
  • %a %d - is bounded by the day, such as Monday 07.
  • %I %p - bounded by hours, such as 01 AM.
  • %I:%M - With minutes as the limit, such as 01:23.
  • :%S - The boundary is based on seconds, such as :45.
  • .%L-- represents the number of milliseconds for all other times, such as 0.012.

Although somewhat unusual, the benefit of this default behavior is that it provides a local and global context: For example, formatting a string of ticks to [11 PM, Mon 07, 01 AM] can display information on hours, dates and dates at the same time instead of just hours [11 PM, 12 AM, 01 AM]. If you want to launch your own conditional time format, see d3-Time-format.

([count]) ([interval])

Extend the domain so that it starts and ends with beautiful integer values. This method usually modifies the domain of the tick and may only extend the boundary to the nearest circle value. See Learn more.

An optional tick parameter allows greater control over the step size used to extend the boundary, ensuring that the returned tick will completely cover the field. In addition, a time interval can be specified to clearly set the scale. If an interval is specified, you can also specify an optional step size to skip some ticks. For example, ((10)) will expand the domain to an even number of 10 seconds (0, 10, 20, etc.). See more details.

([[domain, ]range])

Equivalent to scaleTime, but the returned time scale runs in coordinated Universal Time (UTC) rather than local time.

The above is the detailed explanation of the use example of d3-scale d3-scaleTime. For more information about d3-scale d3-scaleTime, please pay attention to my other related articles!