This is an automated email from the ASF dual-hosted git repository. sushuang pushed a commit to branch v6-doc-supplement-2 in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
commit 5c870a4558a8830d88b7fcba5c6a75591fcba64e Author: 100pah <[email protected]> AuthorDate: Thu Aug 7 06:20:45 2025 +0800 Tweak geoJSON example api. --- en/api/echarts.md | 105 ++++++++++++++++++++++++++++++++++++------------------ zh/api/echarts.md | 104 ++++++++++++++++++++++++++++++++++++----------------- 2 files changed, 143 insertions(+), 66 deletions(-) diff --git a/en/api/echarts.md b/en/api/echarts.md index e430abe8..06cb9ddc 100644 --- a/en/api/echarts.md +++ b/en/api/echarts.md @@ -159,49 +159,86 @@ Registers available maps. This can only be used after including [geo](option.htm Please refer to [option.geo](option.html#geo.map) for usage. -**Parameters** -+ `mapName` +**Parameters:** ++ **@param `mapName`:** Map name, referring to `map` value set in [geo](option.html#geo) component or [map](option.html#series-map). -+ `opt` ++ **@param `opt.geoJSON`:** - + `geoJSON` Optional. Data in GeoJson format. See [https://geojson.org/](https://geojson.org/) for more format information. Can be a JSON string or a parsed object. This key can also be `geoJson`. + Optional. Data in GeoJSON format. See [https://geojson.org/](https://geojson.org/) for more format information. Can be a JSON string or a parsed object. This key can also be `geoJson`. - + `svg` Optional. Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20SeriesSVG%20Base%20Map). Introduced in v5.1.0 + For example, A minimal geoJSON: + ```ts + const geoJSONSample = { + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[200, 3000], [500, 3000], [500, 5000], [200, 5000]] + ] + }, + "properties": { + "name": "Some Place", + "cp": [220, 2100] + } + } + ] + }; + echarts.registerMap('my_geo_sample', {geoJSON: geoJSONSample}); + ``` + Note: + + `features[i].properties.name` in GeoJSON is required by ECharts to query the corresponding region, or display the label. Property `name` is used by default, but can also be other properties, see [geo.nameProperty](option.html#geo.nameProperty). + + `features[i].properties.cp` is an optional property that ECharts can recoganize. It provides coordinates on which the label can be displayed. If not provided, the label will be displayed at the center of the region. - + `specialAreas` Optional. zoomed part of a specific area in the map for better visual effect. Only work for `geoJSON`. ++ **@param `opt.svg`:** -**For example [USA Population Estimates](${galleryEditorPath}map-usa): ** -```ts -echarts.registerMap('USA', usaJson, { - // Move Alaska to the bottom left of United States - Alaska: { - // Upper left longitude - left: -131, - // Upper left latitude - top: 25, - // Range of longitude - width: 15 - }, - // Hawaii - Hawaii: { - left: -110, - top: 28, - width: 5 - }, - // Puerto Rico - 'Puerto Rico': { - left: -76, - top: 26, - width: 2 - } -}); -``` + Optional. Data in SVG format. Can be a SVG string or a parsed SVG DOM object. See more info in [SVG Base Map](tutorial.html#SVG%20Base%20Map%20in%20Geo%20Coords%20and%20Map%20SeriesSVG%20Base%20Map). Introduced in `v5.1.0`. -Note: + For example, A minimal SVG: + ```ts + const mySVG = `<?xml version="1.0" encoding="utf-8"?> + <svg xmlns="http://www.w3.org/2000/svg"; xmlns:ooo="http://xml.openoffice.org/svg/export"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="1.2" fill-rule="evenodd" xml:space="preserve"> + <path name="left_rect" d="M 0,0 L 0,100 100,100 100,0 Z" fill="#765" stroke="rgb(56,93,138)" stroke-width="0" stroke-linecap="square" stroke-linejoin="miter"/> + </svg>`; + echarts.registerMap('my_geo_sample', {svg: mySVG}); + ``` + ++ **@param `opt.specialAreas`:** + + Optional. zoomed part of a specific area in the map for better visual effect. Only work for `geoJSON`. + + **[An example of specialAreas](${galleryEditorPath}map-usa): ** + ```ts + echarts.registerMap('USA', usaJson, { + // Move Alaska to the bottom left of United States + Alaska: { + // Upper left longitude + left: -131, + // Upper left latitude + top: 25, + // Range of longitude + width: 15 + }, + // Hawaii + Hawaii: { + left: -110, + top: 28, + width: 5 + }, + // Puerto Rico + 'Puerto Rico': { + left: -76, + top: 26, + width: 2 + } + }); + ``` -If you only import the required components in your project, starting from v5.3.0 `registerMap` has to be used after the `MapChart` or `GeoComponent` is imported. +Note: If you only import the required components in your project, starting from v5.3.0 `registerMap` cannot be called unless `MapChart` or `GeoComponent` is imported (ES module import). ## getMap(Function) ```ts diff --git a/zh/api/echarts.md b/zh/api/echarts.md index 6aafeb7b..e08cf795 100644 --- a/zh/api/echarts.md +++ b/zh/api/echarts.md @@ -158,47 +158,87 @@ echarts.use( 使用方法见 [option.geo](option.html#geo.map)。 **参数：** -+ `mapName` ++ **@param `mapName`:** 地图名称，在 [geo](option.html#geo) 组件或者 [map](option.html#series-map) 图表类型中设置的 `map` 对应的就是该值。 -+ `opt` - + `geoJSON` 可选。GeoJson 格式的数据，具体格式见 [https://geojson.org/](https://geojson.org/)。可以是 JSON 字符串，也可以是解析得到的对象。这个参数也可以写为 `geoJson`，效果相同。 ++ **@param `opt.geoJSON`:** - + `svg` 可选。从 `v5.1.0` 开始支持SVG 格式的数据。可以是字符串，也可以是解析得到的 SVG DOM 对象。更多信息参见 [SVG 底图](tutorial.html#%E5%9C%B0%E7%90%86%E5%9D%90%E6%A0%87%E7%B3%BB%E5%92%8C%E5%9C%B0%E5%9B%BE%E7%B3%BB%E5%88%97%E7%9A%84%20SVG%20%E5%BA%95%E5%9B%BE)。 + 可选。GeoJSON 格式的数据，具体格式见 [https://geojson.org/](https://geojson.org/)。可以是 JSON 字符串，也可以是解析得到的对象。这个参数也可以写为 `geoJson`，效果相同。 - + `specialAreas` 可选。将地图中的部分区域缩放到合适的位置，可以使得整个地图的显示更加好看。只在 `geoJSON` 中生效，`svg` 中不生效。 + 例如，一个极小的 GeoJSON： + ```ts + const geoJSONSample = { + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[2000, 2000], [5000, 2000], [5000, 5000], [2000, 5000]] + ] + }, + "properties": { + "name": "Some Place", + "cp": [220, 2100] + } + } + ] + }; + echarts.registerMap('my_geo_sample', geoJSONSample); + ``` + 注： + + GeoJSON 中的 `features[i].properties.name` 被 ECharts 默认使用来索引这个区域，或者显示图标文字。也可以使用其他属性名，参见 [geo.nameProperty](option.html#geo.nameProperty)。 + Note: + + GeoJSON 中的 `features[i].properties.cp` 是个 ECharts 可识别的可选属性。它提供了标签的位置坐标。如果没有提供，标签自动放置在相应区域的中心。 -示例 [USA Population Estimates](${galleryEditorPath}map-usa)： ++ **@param `opt.svg`:** -```ts -echarts.registerMap('USA', usaJson, { - // 把阿拉斯加移到美国主大陆左下方 - Alaska: { - // 左上角经度 - left: -131, - // 左上角纬度 - top: 25, - // 经度横跨的范围 - width: 15 - }, - // 夏威夷 - Hawaii: { - left: -110, - top: 28, - width: 5 - }, - // 波多黎各 - 'Puerto Rico': { - left: -76, - top: 26, - width: 2 - } -}); -``` + 可选。从 `v5.1.0` 开始支持SVG 格式的数据。可以是字符串，也可以是解析得到的 SVG DOM 对象。更多信息参见 [SVG 底图](tutorial.html#%E5%9C%B0%E7%90%86%E5%9D%90%E6%A0%87%E7%B3%BB%E5%92%8C%E5%9C%B0%E5%9B%BE%E7%B3%BB%E5%88%97%E7%9A%84%20SVG%20%E5%BA%95%E5%9B%BE)。 + + 例如，一个极小的 SVG： + ```ts + const mySVG = `<?xml version="1.0" encoding="utf-8"?> + <svg xmlns="http://www.w3.org/2000/svg"; xmlns:ooo="http://xml.openoffice.org/svg/export"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="1.2" fill-rule="evenodd" xml:space="preserve"> + <path name="left_rect" d="M 0,0 L 0,100 100,100 100,0 Z" fill="#765" stroke="rgb(56,93,138)" stroke-width="0" stroke-linecap="square" stroke-linejoin="miter"/> + </svg>`; + echarts.registerMap('my_geo_sample', {svg: mySVG}); + ``` + ++ **@param `opt.specialAreas`:** + + 可选。将地图中的部分区域缩放到合适的位置，可以使得整个地图的显示更加好看。只在 `geoJSON` 中生效，`svg` 中不生效。 + + [specialAreas 示例](${galleryEditorPath}map-usa)： + ```ts + echarts.registerMap('USA', usaJson, { + // 把阿拉斯加移到美国主大陆左下方 + Alaska: { + // 左上角经度 + left: -131, + // 左上角纬度 + top: 25, + // 经度横跨的范围 + width: 15 + }, + // 夏威夷 + Hawaii: { + left: -110, + top: 28, + width: 5 + }, + // 波多黎各 + 'Puerto Rico': { + left: -76, + top: 26, + width: 2 + } + }); + ``` -注：如果你在项目中使用了按需引入，从 v5.3.0 开始`registerMap`必须要在引入地图组件后才能使用。 +注：如果你在项目中使用了按需引入，从 v5.3.0 开始 `registerMap` 必须要在`MapChart` 或 `GeoComponent` 被 `import`（ES module import）后才能使用。 ## getMap(Function) ```ts --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
