# @esri/calcite-components-react 中文文档

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

版本：5\.2\.1
npm 元数据更新时间：2026-11-04T22:32:37.510Z
中文译文更新时间：2026-11-13T22:47:00.032Z
软件包许可：SEE LICENSE\.md

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

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

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

- 包体积（解压后）：101 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react \>=18\.3，react-dom \>=18\.3
- 首次发布：2021-06-08T01:16:44.211Z
- 最新版本发布：2026-11-04T22:32:36.957Z
- 近 30 天下载量：21686（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：1229（近 12 个月 297 个）

## 中文简介

一套包裹钙质组件的回放组件

## 安装

```sh
npm install @esri/calcite-components-react
```

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

## README

# Calcite 组件反应

此软件包为 [Calcite 组件](https://developers.arcgis.com/calcite-design-system/components/)。参考 [反应示例](https://github.com/Esri/calcite-design-system/tree/dev/examples/components/react-18-and-below) 用于使用此软件包的最小应用程序.

## 折旧通知

> \[尖叫声\] Calcite Consult React自v 5.0起贬值.

这个 `@esri/calcite-components-react` 软件包最初是用React 18开发的,其中包装是使用自定义元素所必需的。 与 [React 19 的自定义元素支持](https://react.dev/blog/2024/12/05/react-19#support-for-custom-elements)这些包装已经不再需要了.

考虑升级到19+反应并使用 `@esri/calcite-components` 直接说.

## 安装

```sh
pnpm add @esri/calcite-components-react
```

此软件包包括标准的相容版本 `@esri/calcite-components` 软件包,所以不需要单独安装.

## 选择构建

由标准组件包提供的有两栋建筑.

### 自定义元素构建

[自定义元素](https://npmcn.com/package/%40esri/calcite-components-react/developers.arcgis.com/calcite-design-system/get-started#custom-elements) 是在使用前端框架时被推荐的构建,例如React。 CDN 的资产默认使用,但您可以指定本地资产路径 `setAssetPath`下一步将解释使用当地资产的额外设置.

```jsx
import { setAssetPath } from "@esri/calcite-components";

setAssetPath(window.location.href);
```

接下来,您需要从标准组件包自定义元素构建中导入您使用的每个组件. 这将自动定义窗口上的自定义元素 。 然后,从 `@esri/calcite-components-react`。 。 。 .

```jsx
import "@esri/calcite-components/dist/components/calcite-button";
import "@esri/calcite-components/dist/components/calcite-icon";
import "@esri/calcite-components/dist/components/calcite-slider";
import { CalciteButton, CalciteIcon, CalciteSlider } from "@esri/calcite-components-react";
```

### 盘点构建

使用时 [位点](https://npmcn.com/package/%40esri/calcite-components-react/developers.arcgis.com/calcite-design-system/get-started#distribution) 构建, 您需要手动定义窗口上的自定义元素 :

```jsx
import { defineCustomElements } from "@esri/calcite-components/dist/loader";

defineCustomElements();
```

由于您手动定义了窗口上的自定义元素, 您只需要从中导入单个组件 `@esri/calcite-components-react`。 。 。 .

```jsx
import { CalciteButton, CalciteIcon, CalciteSlider } from "@esri/calcite-components-react";
```

## 复制资产

有些组成部分(虹、取日期者)依赖于在特定路径上的资产。 如果在当地使用资产,你需要把这些复制到你的公开文件夹. 比如说:

```sh
cp -r node_modules/@esri/calcite-components/dist/cdn/assets/* ./public/assets/
```

## 为什么不直接使用网络组件?

使用 React 19+ 对自定义元素的本地支持, 您现在可以使用 `@esri/calcite-components` 直接说 见 [Calcite 组件重现折旧通知](https://npmcn.com/package/%40esri/calcite-components-react/#readme-deprecation-notice) 用于补充信息.

React 18及更早的版本使用合成事件系统,其中由 Calcite 组件所排放的自定义事件不会在React中与JSX一起运行. 例如,如果使用标准网络组件来更新当更改发生时的值 `<calcite-slider>`,您需要保存元素的引用并添加一个收听器:

```jsx
const sliderEl = useRef(null);
const [sliderValue, setSliderValue] = useState(50);

function onUpdate(event) {
  setSliderValue(event.target.value);
}

// need to access the DOM node to set custom event listeners for props that aren't strings or numbers
// lit.dev/docs/frameworks/react#why-are-wrappers-needed
useEffect(
  (_) => {
    sliderEl.current.addEventListener("calciteSliderUpdate", onUpdate);
  },
  [sliderEl],
);
```

使用 `@esri/calcite-components-react`,这些事件与你有关:

```jsx
const [sliderValue, setSliderValue] = useState(50);
<CalciteSlider onCalciteSliderUpdate={(e) => setSliderValue(e.target.value)} />;
```

如果使用TypeScript,也会为您的事件听众,道具等获得更高的类型安全.

## 捐款

我们欢迎为这一项目提供捐款。 见 [捐款额](https://github.com/Esri/calcite-design-system/blob/dev/CONTRIBUTING.md) 概述捐款准则.

## 许可证

骑警Esri - [https://js.arcgis.com/ 5.0/LICENSE.txt (英语)](https://js.arcgis.com/5.0/LICENSE.txt)

美国版权法和适用的国际法、条约和公约所保留的一切权利.

这些材料根据《埃斯里总许可证协定》获得使用许可,并受该协定条款的约束。 您可以不经修改而重新分配和使用此代码,但需遵守司法协助条款并包括此版权通知.

见使用限制 [http://www.esri.com/legal/pdfs/mla e204 e300/english (英语)](http://www.esri.com/legal/pdfs/mla_e204_e300/english)

关于补充资料,参见 [卡尔西特的许可证](https://developers.arcgis.com/calcite-design-system/resources/licensing) 联系人:美国加利福尼亚州纽约街380号合同和法律服务部

电子邮件 : [合同@esri.com](mailto:contracts@esri.com)

## 第三方通知

见 [第三次议会提名(md)](https://npmcn.com/package/%40esri/calcite-components-react/THIRD-PARTY-NOTICES.md)。 。 。 .

## 常见问题

### @esri/calcite-components-react 是什么？

一套包裹钙质组件的回放组件

### 如何安装 @esri/calcite-components-react？

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

### @esri/calcite-components-react 支持 TypeScript 吗？

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

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

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

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

@esri/calcite-components-react 使用 SEE LICENSE\.md 许可。声明的许可为 SEE LICENSE\.md，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

最新版本 5\.2\.1 发布于 2026/11/05（9 天前）；至今共发布 1229 个版本，其中过去 12 个月发布了 297 个；首次发布于 2021/06/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。