路径

¥Paths

地理路径生成器 geoPath 获取给定的 GeoJSON 几何图形或要素对象，并生成 SVG 路径数据字符串或 渲染到画布。路径可以与 projections 或 transforms 一起使用，也可以用于将平面几何图形直接渲染到 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)

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

¥Source · Creates a new geographic path generator with the default settings. If projection is specified, sets the current projection. If context is specified, sets the current context.

const path = d3.geoPath(projection); // for SVG

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

path(object, ...arguments) {#_path}

源代码 · 渲染给定对象，该对象可以是任何 GeoJSON 要素或几何对象：

¥Source · Renders the given object, which may be any GeoJSON feature or geometry object:

• 点 - 单个位置

  ¥Point - a single position

• MultiPoint - 位置数组

  ¥MultiPoint - an array of positions

• LineString - 构成连续线的位置数组

  ¥LineString - an array of positions forming a continuous line

• MultiLineString - 构成多条线的位置数组数组

  ¥MultiLineString - an array of arrays of positions forming several lines

• 多边形 - 构成多边形（可能带有孔）的位置数组数组

  ¥Polygon - an array of arrays of positions forming a polygon (possibly with holes)

• MultiPolygon - 一个构成多个多边形的多维位置数组

  ¥MultiPolygon - a multidimensional array of positions forming multiple polygons

• GeometryCollection - 几何对象数组

  ¥GeometryCollection - an array of geometry objects

• 功能 - 一个包含上述几何对象之一的特性

  ¥Feature - a feature containing one of the above geometry objects

• FeatureCollection - 特性对象数组

  ¥FeatureCollection - an array of feature objects

同时还支持 Sphere 类型，这对于渲染地球轮廓非常有用；球体没有坐标。任何其他参数都会传递给 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:

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

或者使用多个路径元素：

¥Or use multiple path elements:

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) {#path_area}

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

¥Source · Returns the projected planar area (typically in square pixels) for the specified GeoJSON object.

path.area(california) // 17063.1671837991 px²

点、多点、线串和多线串几何图形的面积为零。对于多边形和多多边形几何体，此方法首先计算外环的面积，然后减去所有内部孔洞的面积。此方法会观察 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) {#path_bounds}

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

¥Source · Returns the projected planar bounding box (typically in pixels) for the specified GeoJSON object.

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) {#path_centroid}

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

¥Source · Returns the projected planar centroid (typically in pixels) for the specified GeoJSON object.

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

这对于例如标记州或县边界，或显示符号地图非常方便。例如，非连续统计图 可能会围绕其质心缩放每个州。此方法会观察 projection 执行的任何裁剪操作；参见 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) {#path_digits}

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

¥Source · If digits is specified (as a non-negative number), sets the number of fractional digits for coordinates generated in SVG path strings.

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

如果未指定投影，则返回当前的位数，默认为 3。

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

path.digits() // 3

此选项仅当关联的 context 为空时适用，例如使用此圆弧生成器生成 路径数据 时。

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

path.measure(object) {#path_measure}

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

¥Source · Returns the projected planar length (typically in pixels) for the specified GeoJSON object.

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) {#path_projection}

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

¥Source · If a projection is specified, sets the current projection to the specified projection.

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

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

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

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.

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

¥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) {#path_context}

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

¥Source · If context is specified, sets the current render context and returns the path generator.

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

如果上下文为空，则 路径生成器 将返回一个 SVG 路径字符串；如果上下文非空，路径生成器将调用指定上下文上的方法来渲染几何体。上下文必须实现 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()

如果未指定上下文，则返回当前渲染上下文，默认为 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) {#path_pointRadius}

源代码 · 如果指定了半径，则将用于显示点和多点几何体的半径设置为指定的数字。

¥Source · If radius is specified, sets the radius used to display Point and MultiPoint geometries to the specified number.

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

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

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

path.pointRadius() // 10

半径访问器默认为 4.5。半径通常指定为一个常量，但也可以指定为一个函数，该函数根据每个特性计算，并传递给 路径生成器 的任何参数。例如，如果你的 GeoJSON 数据包含其他属性，你可以在 radius 函数中访问这些属性来改变点的大小；或者，为了获得更大的灵活性，你可以同时使用 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.