# @esri/react-arcgis 中文文档

规范地址：https://npmcn.com/package/%40esri/react-arcgis/

版本：5\.2\.0
npm 元数据更新时间：2025-10-31T20:21:09.478Z
中文译文更新时间：2026-11-13T22:48:19.699Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40esri/react-arcgis
原文对照：https://npmcn.com/package/%40esri/react-arcgis/?lang=original
项目主页：https://github.com/Esri/react-arcgis#readme
源码仓库：https://github.com/Esri/react-arcgis

弃用说明：Use @arcgis/core or esri-loader directly in your React application

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：110 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^16 \|\| ^17 \|\| ^18，react-dom ^16 \|\| ^17 \|\| ^18，esri-loader ^2\.14
- 首次发布：2019-01-09T22:44:16.746Z
- 最新版本发布：2022-05-20T18:10:12.408Z
- 近 30 天下载量：11159（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

帮助您开始使用 JavaScript 和 esri-loader 的 ArcGIS API 组件

## 安装

```sh
npm install @esri/react-arcgis
```

也可以使用：`pnpm add @esri/react-arcgis`、`yarn add @esri/react-arcgis`、`bun add @esri/react-arcgis`

## README

# 反应-参数

[![Version](https://img.shields.io/npm/v/@esri/react-arcgis.svg?style=flat-square)](https://www.npmjs.com/package/@esri/react-arcgis) [![build status](https://img.shields.io/travis/Esri/react-arcgis/master.svg?style=flat-square)](https://travis-ci.org/Esri/react-arcgis) [![Test Coverage](https://api.codeclimate.com/v1/badges/940f84ed55f223c0bea8/test_coverage)](https://codeclimate.com/github/Esri/react-arcgis/test_coverage)

该项目提供了一个图书馆,其中有几个可以使用React组件(`<Map />`, (中文(简体) ), `<Scene />`, (中文(简体) ), `<WebMap />`,以及 `<WebScene />`要让你开始使用 [用于 JavaScript 的 ArcGIS API](https://developers.arcgis.com/javascript/) 在您的反应应用程序中。 这些组件使用 [装填器](https://github.com/Esri/esri-loader) 在引擎盖下到懒惰地装入ArcGIS API模块.

**_重要性_: 确实 _没有_ 需求 `react-arcgis` 在您的 React 应用程序中使用 ArcGIS API 。 如果以上通用组件不适合您的需要, 您可以很容易地 [创建您自己为 JavaScript 装入 ArcGIS API 的 React 组件](https://developers.arcgis.com/javascript/latest/guide/react) 使用 [装填器](https://developers.arcgis.com/javascript/latest/guide/esri-loader)。或者,您可以从此库中的组件开始,然后 [添加自己的组件](https://npmcn.com/package/%40esri/react-arcgis/#readme-creating-your-own-components) 视需要而定.**

## 安装

1.  运行 `npm i --save esri-loader @esri/react-arcgis` 在您的反应应用程序中

_如果您需要支持浏览器缺少本地承诺执行, 您必须添加全局 `Promise` 工程的构造器多填充, 因为反应- arcgis 不包括一个 。 见 [埃斯里装填器文档](https://github.com/Esri/esri-loader#promises) 更多细节._

## 基本用途

**_关键是:_ 你个 _必须_ 在使用此库中的组件之前加载 ArcGIS API 样式 。 下面的片段假设 你已经使用了其中之一 [方式 `esri-loader` 提供您加载 ArcGIS API CPS](https://github.com/Esri/esri-loader#loading-styles)。 。 。 .**

在 React 中绘制一个简单的映射 :

```js
import React from 'react';
import * as ReactDOM from 'react-dom';
import { Map } from '@esri/react-arcgis';

ReactDOM.render(
  <Map />,
  document.getElementById('container')
);
```

![map](https://user-images.githubusercontent.com/16542714/27751340-a9e440b4-5d90-11e7-84bc-6281f2a2f59b.jpg)

或者,制作一个3D网络场景:

```js
import React from 'react';
import * as ReactDOM from 'react-dom';
import { Scene } from '@esri/react-arcgis';

ReactDOM.render(
  <Scene />,
  document.getElementById('container')
);
```

您也可以从 ArcGIS Online 中加入 Webmaps 和 Webscenes :

```js
import React from 'react';
import * as ReactDOM from 'react-dom';
import { WebMap, WebScene } from '@esri/react-arcgis';

ReactDOM.render(
    <div style={{ width: '100vw', height: '100vh' }}>
        <WebMap id="6627e1dd5f594160ac60f9dfc411673f" />
        <WebScene id="f8aa0c25485a40a1ada1e4b600522681" />
    </div>,
  document.getElementById('container')
);
```

![webmap](https://user-images.githubusercontent.com/16542714/27751438-26e02b78-5d91-11e7-8e5d-9198cd390e57.jpg)

如果你想改变风格 `Map` 或者说 `Scene`给它一个课:

```js
import React from 'react';
import * as ReactDOM from 'react-dom';
import { Scene } from '@esri/react-arcgis';

ReactDOM.render(
  <Scene className="full-screen-map" />,
  document.getElementById('container')
);
```

您也可以将属性传递到 `Map`, (中文(简体) ), `MapView`,或 `SceneView` 通过视图 Properties 或 map Properties 道具 :

```js
import React from 'react';
import { Map } from '@esri/react-arcgis';

export default (props) => (
    <Map
        class="full-screen-map"
        mapProperties={{ basemap: 'satellite' }}
    />
)
```

![map-properties](https://user-images.githubusercontent.com/16542714/27751672-3e31bcc8-5d92-11e7-8e2b-3afab88c7154.jpg)

这些属性直接传递给相应的可用属性 [ArcGIS API 类](https://developers.arcgis.com/javascript/latest/api-reference/index.html)数字 :

```js
import React from 'react';
import { Scene } from '@esri/react-arcgis';

export default (props) => (
    <Scene
        style={{ width: '100vw', height: '100vh' }}
        mapProperties={{ basemap: 'satellite' }}
        viewProperties={{
            center: [-122.4443, 47.2529],
            zoom: 6
        }}
    />
)
```

![scene](https://user-images.githubusercontent.com/16542714/27750977-088b94ac-5d8f-11e7-997a-088a3c717cf6.jpg)

如果你想访问 `map` 财务报告和审定财务报表 `view` 直接在加载后通过 `onLoad` 处理器 :

```js
import React from 'react';
import { Map } from '@esri/react-arcgis';

export default class MakeAMap extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            map: null,
            view: null
        };

        this.handleMapLoad = this.handleMapLoad.bind(this)
    }

    render() {
        return <Map className="full-screen-map" onLoad={this.handleMapLoad} />;
    }

    handleMapLoad(map, view) {
        this.setState({ map, view });
    }
}
```

别忘了一个 `onFail` 处理器以防出事:

```js
import React from 'react';
import { WebScene } from '@esri/react-arcgis';

export default class MakeAScene extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            status: 'loading'
        };

        this.handleFail = this.handleFail.bind(this);
    }

    render() {
        return <WebScene className="full-screen-map" id="foobar" onFail={this.handleFail} />;
    }

    handleFail(e) {
        console.error(e);
        this.setState({ status: 'failed' });
    }
}
```

## 高级使用

### 配置 `esri-loader`

默认情况下, 此库中的组件将使用 `esri-loader`默认选项, 表示它们会懒惰地从CDN版本的ArcGIS API中为 JavaScript 添加模块, 用于 JavaScript 版本 `esri-loader` 您已经安装。 见 [页:1 `esri-loader` 配置文档](https://github.com/Esri/esri-loader/#configuring-esri-loader) 以获取如何自定义的信息 `esri-loader`行为.

#### 使用 `setDefaultOptions()`

最简单的方法是打电话 `esri-loader`是因为 `setDefaultOptions()` 应用程序启动时, 此库中的任何组件才会被打开 .

```jsx
import React from 'react';
import * as ReactDOM from 'react-dom';
import { setDefaultOptions } from 'esri-loader';
// app contains react-arcgis components
import { App } from './components/App.js';

// configure esri-loader to lazy load the CSS
// the fisrt time any react-arcgis components are rendered
setDefaultOptions({ css: true });

ReactDOM.render(
  <App />,
  document.getElementById('app')
);
```

这需要 `esri-loader@^2.12.0`。如果您使用旧版的 Esri 装填器,您也许应该升级.

#### 使用 `loaderOptions`

如果你无法使用 `setDefaultOptions()`,可以使用 `loaderOptions` 此库中每个组件提供的道具 。 这将是 [以 `options` 改为 `loadModules()`](https://github.com/Esri/esri-loader/#without-setdefaultoptions)。记住,如果你使用 `loaderOptions`,您必须通过同样的选项 _全部_ `react-arcgis` 应用程序中的组件,以及应用程序调用的地方 `loadModules()` 直接说.

### 创建自有组件

通过 [用于 JavaScript 的 ArcGIS API](https://developers.arcgis.com/javascript/) 如果你的应用程序需要用地图做更多的工作, 而不是简单地显示地图, 你很可能需要从ArcGIS API 中加载和使用额外的类, 并为这些类提供引用您用此库中组件创建的地图的例子.

幸好你已经安装好了 `esri-loader`,允许您 [装入应用程序可能需要的任何额外的ArcGIS API模块](https://github.com/Esri/esri-loader#loading-modules-from-the-arcgis-api-for-javascript)此外, `react-arcgis` 抚养子女 `<Map />`, (中文(简体) ), `<Scene />`, (中文(简体) ), `<WebMap />`,以及 `<WebScene />` 进入父母的 `map` 财务报告和审定财务报表 `view` 实例通过道具.

例如,让我们将百慕大三角图形从 [此示例](https://developers.arcgis.com/javascript/latest/sample-code/sandbox/index.html?sample=intro-graphics) 变成反应组件 :

```js
import { useState, useEffect } from 'react';
import { loadModules } from 'esri-loader';

const BermudaTriangle = (props) => {

    const [graphic, setGraphic] = useState(null);
    useEffect(() => {

        loadModules(['esri/Graphic']).then(([Graphic]) => {
            // Create a polygon geometry
            const polygon = {
                type: "polygon", // autocasts as new Polygon()
                rings: [
                    [-64.78, 32.3],
                    [-66.07, 18.45],
                    [-80.21, 25.78],
                    [-64.78, 32.3]
                ]
            };

            // Create a symbol for rendering the graphic
            const fillSymbol = {
                type: "simple-fill", // autocasts as new SimpleFillSymbol()
                color: [227, 139, 79, 0.8],
                outline: { // autocasts as new SimpleLineSymbol()
                    color: [255, 255, 255],
                    width: 1
                }
            };

            // Add the geometry and symbol to a new graphic
            const graphic = new Graphic({
                geometry: polygon,
                symbol: fillSymbol
            });
            setGraphic(graphic);
            props.view.graphics.add(graphic);
        }).catch((err) => console.error(err));

        return function cleanup() {
            props.view.graphics.remove(graphic);
        };
    }, []);

    return null;

}

export default BermudaTriangle;
```

现在我们可以使用 `<BermudaTriangle />` 我们内部的组成部分 `<Map />`, (中文(简体) ), `<Scene />`, (中文(简体) ), `<WebMap />`,或 `<WebScene />`,则 `map` 财务报告和审定财务报表 `view` 道具将自动由反应-arcgis提供:

```js
import * as React from 'react';
import { Scene } from '@esri/react-arcgis';
import BermudaTriangle from './BermudaTriangle'; // The Graphic component we just made

export default (props) => (
    <Scene class="full-screen-map">
        <BermudaTriangle />
    </Scene>
)
```

![bermuda-triangle](https://user-images.githubusercontent.com/16542714/27752141-5f000034-5d94-11e7-83bc-c88428f99053.jpg)

### 使用 ArcGIS 类型

见 [`esri-loader` 关于ArcGIS类型工作的文档](https://github.com/Esri/esri-loader#4x-types)。 。 。 .

## 移动

### 从v4到v5

首先,确保 Esri 装填器被安装为您的应用程序的依赖性 :

```shell
npm install --save esri-loader
```

然后,更新任何 `import` 报表 `loadModules()`数字 :

```js
// Replace old `loadModules` imports...
// import { Map, loadModules } from '@esri/react-arcgis';

// With a new, separate esri-loader import:
import { Map } from '@esri/react-arcgis';
import { loadModules } from 'esri-loader';
```

## 捐款

欢迎任何人对这一一揽子计划作出贡献。 然而,我们不打算在这个图书馆再增加任何组成部分。 如果您已经创建了您想要共享的组件, 我们鼓励您通过 [代码框](https://codesandbox.io/) 或一个 [属性](https://gist.github.com/)一旦你做了,你觉得自由 打开一个问题 我们会帮助传播这个词.

我们高兴地欢迎对文件进行错误修正或改进.

以下是一些可能有助于发展的命令:

-   `npm test`: 进行单元测试
-   `npm run build`: 构建应用程序

要对照您正在开发的代码运行演示应用程序,您需要运行这些命令:

```bash
npm link
npm run build
cd demo
npm i
npm link @esri/react-arcgis
npm start
```

记住 `start` 脚本只监视演示应用中代码的修改. 你必须重新运行 `npm run build` 每次您对库进行修改, 并想要在演示应用程序中验证它们 .

### 许可证

版权: 2017-2019 Esri

根据Apache许可证第2.0版("License"); 您不得使用此文件,除非符合许可证. 您可在下列地点获得许可证副本:

> [http://www.apache.org/licenses/LICENSE-2.0 (中文(简体) )](http://www.apache.org/licenses/LICENSE-2.0)

除非适用的法律要求或书面同意,否则软件 根据许可证发放的是在“AS IS”BASIS上发放的, 没有任何明示或暗示的警告或条件. 有关许可的特定语言的许可证 许可证的限制.

许可证副本可到存放处索取 [自由主义](https://npmcn.com/package/%40esri/react-arcgis/LICENSE) 文档.

## 常见问题

### @esri/react-arcgis 是什么？

帮助您开始使用 JavaScript 和 esri-loader 的 ArcGIS API 组件注意：该包已被作者标记为弃用——Use @arcgis/core or esri-loader directly in your React application

### 如何安装 @esri/react-arcgis？

在项目目录运行 npm install @esri/react-arcgis，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16 \|\| ^17 \|\| ^18）、react-dom（^16 \|\| ^17 \|\| ^18）、esri-loader（^2\.14）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @esri/react-arcgis 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @esri/react-arcgis 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @esri/react-arcgis 可以商用吗？

@esri/react-arcgis 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @esri/react-arcgis 的下载量有多少？

根据 npm 官方下载统计，@esri/react-arcgis 在 2026/10/14 – 2026/11/12 这 30 天内被下载 11,159 次，日均约 372 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @esri/react-arcgis 还在维护吗？

最新版本 5\.2\.0 发布于 2022/05/21（4 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/01/10。作者已将其标记为弃用，新项目建议寻找替代方案。