D3

路径 ​

🌐 Paths

地理路径生成器，geoPath，接受给定的 GeoJSON 几何或要素对象，并生成 SVG 路径数据字符串或 渲染到 Canvas。路径可以与 投影 或 变换 一起使用，或者可以直接用于将平面几何渲染到 Canvas 或 SVG。

🌐 The geographic path generator, geoPath, takes a given GeoJSON geometry or feature object and generates SVG path data string or renders to a Canvas. Paths can be used with projections or transforms, or they can be used to render planar geometry directly to Canvas or SVG.

geoPath(projection, context) ​

来源 · 使用默认设置创建新的地理路径生成器。如果指定了 projection，则设置当前投影。如果指定了 context，则设置当前上下文。

js
const path = d3.geoPath(projection); // for SVG
js
const path = d3.geoPath(projection, context); // for canvas

path(对象, ...参数) ​

🌐 path(object, ...arguments)

来源 · 渲染给定的 对象，它可以是任何 GeoJSON 要素或几何对象：

  • 点 - 一个单一的位置
  • 多点 - 一组位置
  • LineString - 一组形成连续线的坐标
  • MultiLineString - 由多个位置数组组成的多条线的数组
  • Polygon - 由位置数组组成的数组，形成一个多边形（可能有空洞）
  • 多边形集合 - 由多个多边形组成的多维位置数组
  • 几何集合 - 一组几何对象
  • 要素 - 包含上述几何对象之一的要素
  • FeatureCollection - 特性对象的数组

类型 Sphere 也受到支持，它对于渲染地球的轮廓非常有用；球体没有坐标。任何额外的 arguments 都会传递给 pointRadius 访问器。

🌐 The type Sphere is also supported, which is useful for rendering the outline of the globe; a sphere has no coordinates. Any additional arguments are passed along to the pointRadius accessor.

要显示多个要素，请将它们组合成一个要素集合：

🌐 To display multiple features, combine them into a feature collection:

js
svg.append("path")
    .datum({type: "FeatureCollection", features: features})
    .attr("d", d3.geoPath());

或者使用多个路径元素：

🌐 Or use multiple path elements:

js
svg.selectAll()
  .data(features)
  .join("path")
    .attr("d", d3.geoPath());

单独的路径元素通常比单个路径元素慢。然而，独立的路径元素在样式和交互（例如，点击或鼠标悬停）方面是有用的。画布渲染（参见 path.context）通常比 SVG 更快，但实现样式和交互需要更多的努力。

🌐 Separate path elements are typically slower than a single path element. However, distinct path elements are useful for styling and interaction (e.g., click or mouseover). Canvas rendering (see path.context) is typically faster than SVG, but requires more effort to implement styling and interaction.

path.area(object) ​

来源 · 返回指定 GeoJSON 对象 的投影平面面积（通常以像素平方为单位）。

js
path.area(california) // 17063.1671837991 px²

Point、MultiPoint、LineString 和 MultiLineString 几何图形的面积为零。对于 Polygon 和 MultiPolygon 几何图形，该方法首先计算外环的面积，然后减去任意内部孔洞的面积。此方法会遵循 projection 执行的任何裁剪；参见 projection.clipAngle 和 projection.clipExtent。这是 geoArea 的平面等效方法。

🌐 Point, MultiPoint, LineString and MultiLineString geometries have zero area. For Polygon and MultiPolygon geometries, this method first computes the area of the exterior ring, and then subtracts the area of any interior holes. This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of geoArea.

path.bounds(object) ​

来源 · 返回指定 GeoJSON 对象 的投影平面边界框（通常以像素为单位）。

js
path.bounds(california) // [[18.48513821663947, 159.95146883594333], [162.7651668852596, 407.09641570706725]]

边界框由一个二维数组表示：[[x₀, y₀], [x₁, y₁]]，其中 x₀ 是最小的 x 坐标，y₀ 是最小的 y 坐标，x₁ 是最大 x 坐标，y₁ 是最大 y 坐标。这对于例如放大到特定特性非常方便。（注意，在投影平面坐标中，最小纬度通常是最大的 y 值，而最大纬度通常是最小的 y 值。）该方法会遵循 projection 执行的任何裁剪；见 projection.clipAngle 和 projection.clipExtent。这是 geoBounds 的平面等价物。

🌐 The bounding box is represented by a two-dimensional array: [[x₀, y₀], [x₁, y₁]], where x₀ is the minimum x-coordinate, y₀ is the minimum y coordinate, x₁ is maximum x-coordinate, and y₁ is the maximum y coordinate. This is handy for, say, zooming in to a particular feature. (Note that in projected planar coordinates, the minimum latitude is typically the maximum y-value, and the maximum latitude is typically the minimum y-value.) This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of geoBounds.

path.centroid(object) ​

来源 · 返回指定 GeoJSON 对象 的投影平面中心（通常以像素为单位）。

js
path.centroid(california) // [82.08679434495191, 288.14204870673404]

这对于例如标注州或县的边界，或显示符号地图非常方便。例如，一个非连续等面积地图可能会围绕每个州的质心进行缩放。这种方法会遵循投影执行的任何裁剪；参见projection.clipAngle 和 projection.clipExtent。这是 geoCentroid 的平面等价物。

🌐 This is handy for, say, labeling state or county boundaries, or displaying a symbol map. For example, a noncontiguous cartogram might scale each state around its centroid. This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of geoCentroid.

path.digits(digits) ​

来源 · 如果指定了 digits（作为非负数），则设置在 SVG 路径字符串中生成的坐标的小数位数。

js
const path = d3.geoPath().digits(3);

如果未指定projection，则返回当前的数字位数，默认值为3。

🌐 If projection is not specified, returns the current number of digits, which defaults to 3.

js
path.digits() // 3

此选项仅在关联的上下文 为 null 时适用，例如当此弧生成器用于生成路径数据 时。

🌐 This option only applies when the associated context is null, as when this arc generator is used to produce path data.

path.measure(object) ​

来源 · 返回指定 GeoJSON 对象 的投影平面长度（通常以像素为单位）。

js
path.measure(california) // 825.7124297512761

点和多点几何的长度为零。对于多边形和多多边形几何，此方法计算所有环的总长度。此方法遵循投影（projection）执行的任何裁剪；参见 projection.clipAngle 和 projection.clipExtent。这是 geoLength 的平面等效方法。

🌐 Point and MultiPoint geometries have zero length. For Polygon and MultiPolygon geometries, this method computes the summed length of all rings. This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of geoLength.

path.projection(projection) ​

来源 · 如果指定了投影，则将当前投影设置为指定的投影。

js
const path = d3.geoPath().projection(d3.geoAlbers());

如果未指定projection，则返回当前投影。

🌐 If projection is not specified, returns the current projection.

js
path.projection() // a d3.geoAlbers instance

投影默认为 null，表示恒等变换：输入几何体不会被投影，而是直接以原始坐标进行渲染。这对于快速渲染预投影几何体或快速渲染等矩形投影非常有用。

🌐 The projection defaults to null, which represents the identity transformation: the input geometry is not projected and is instead rendered directly in raw coordinates. This can be useful for fast rendering of pre-projected geometry, or for fast rendering of the equirectangular projection.

给定的 projection 通常是 D3 内置的 地理投影 之一；然而，任何暴露 projection.stream 函数的对象都可以使用，从而支持使用 自定义投影。有关任意几何变换的更多示例，请参见 D3 的 变换。

🌐 The given projection is typically one of D3’s built-in geographic projections; however, any object that exposes a projection.stream function can be used, enabling the use of custom projections. See D3’s transforms for more examples of arbitrary geometric transformations.

path.context(context) ​

来源 · 如果指定了context，则设置当前渲染上下文并返回路径生成器。

js
const context = canvas.getContext("2d");
const path = d3.geoPath().context(context);

如果 context 为 null，则 路径生成器 将返回一个 SVG 路径字符串；如果 context 非 null，则路径生成器将改为在指定的 context 上调用方法来渲染几何图形。context 必须实现以下 CanvasRenderingContext2D API 的子集：

🌐 If the context is null, then the path generator will return an SVG path string; if the context is non-null, the path generator will instead call methods on the specified context to render geometry. The context must implement the following subset of the CanvasRenderingContext2D API:

  • context.beginPath()
  • context.moveTo(x, y)
  • context.lineTo(x, y)
  • context.arc(x, y, radius, startAngle, endAngle)
  • context.closePath()

如果未指定 context，则返回当前渲染上下文，默认值为 null。另请参见 d3-path。

🌐 If a context is not specified, returns the current render context which defaults to null. See also d3-path.

path.pointRadius(radius) ​

来源 · 如果指定了 radius，则将用于显示 Point 和 MultiPoint 几何图形的半径设置为指定的数值。

js
const path = d3.geoPath().pointRadius(10);

如果未指定 radius，则返回当前半径访问器。

🌐 If radius is not specified, returns the current radius accessor.

js
path.pointRadius() // 10

半径访问器的默认值为 4.5。虽然半径通常以数字常量的形式指定，但它也可以指定为一个函数，该函数会为每个要素计算，并传入传递给path generator的任何参数。例如，如果你的 GeoJSON 数据有额外的属性，你可以在半径函数中访问这些属性以改变点的大小；或者，你可以使用symbol和projection来获得更大的灵活性。

🌐 The radius accessor defaults to 4.5. While the radius is commonly specified as a number constant, it may also be specified as a function which is computed per feature, being passed the any arguments passed to the path generator. For example, if your GeoJSON data has additional properties, you might access those properties inside the radius function to vary the point size; alternatively, you could symbol and a projection for greater flexibility.