# @elementor/utils 中文文档

规范地址：https://npmcn.com/package/%40elementor/utils/

版本：4\.4\.1
npm 元数据更新时间：2026-11-16T15:18:54.406Z
中文译文更新时间：2026-11-16T15:19:17.527Z
软件包许可：GPL-3\.0-or-later

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

原始 npm 页面：https://www.npmjs.com/package/%40elementor/utils
原文对照：https://npmcn.com/package/%40elementor/utils/?lang=original
项目主页：https://elementor.com/
源码仓库：https://github.com/elementor/elementor

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

- 包体积（解压后）：79.3 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.3\.1
- 首次发布：2024-07-24T11:24:34.599Z
- 最新版本发布：2026-11-16T15:18:54.111Z
- 近 30 天下载量：20610（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：1105（近 12 个月 858 个）

## 中文简介

此软件包包含正在跨元素包使用的功能

## 安装

```sh
npm install @elementor/utils
```

也可以使用：`pnpm add @elementor/utils`、`yarn add @elementor/utils`、`bun add @elementor/utils`

## README

# 用户

此软件包包含跨 Elementor 软件包使用的功能 .

## 错误

本模块包含一个用于创建元素包自定义错误类的标准 API.

### `createError`

为了确保元素包的一致性,我们建议创建一个新的错误类,以扩展 `ElementorError` 使用 `createError` 函数可以帮助您.

#### 创建新错误类型

为了方便 我们暴露了 `createError` 用于为您创建自定义错误类型的工具函数. 此函数将强制您的错误代码和消息为静态( 按我们的准则), 并会缩短您的代码 :

```ts
// errors.ts
import { createError } from '@elementor/utils';

export const CannotRender = createError<{ id: string; }>( 'cannot-render', 'Cannot render element' );
export const CannotSave = createError<{ id: number; status: string; }>( 'cannot-save', 'Cannot save document' );
export const ElementNotFound = createError<{ id: string; }>( 'element-not-found', 'Element not found' );
```

#### 手动创建新错误类型

如果您更愿意手动创建新错误类型,则可以扩展 `ElementorError` 课.

在你的班级内,你需要定义一个独特的错误代码和消息,这些代码和消息应该传递给母建构者.

我们建议给代码和信件都设置静态字符串值,这样就更容易过滤到 错误跟踪工具(例如:. `message = 'cannot render element';` 而不是说 `message = 'Cannot render element' + id;`) (中文(简体) ). 如果需要传递更多关于错误的信息,请在上下文中附加.

```ts
import { ElementorError, type ElementorErrorOptions } from '@elementor/utils';

type CannotRenderContext = {
    id: string;
};

type CannotRenderOptions = {
    context: CannotRenderContext;
    cause?: ElementorErrorOptions['cause'];
};

class CannotRender extends ElementorError {
    constructor( { context, cause }: CannotRenderOptions ) {
        const code = 'cannot-render';
        const message = 'Cannot render element';

        super( message, { cause, context, code } );
    }
}
```

#### 丢弃您的自定义错误类型

在创建自定义错误类型( 如上所描述)后, 您可以将其丢入您的代码 :

基本实例:

```ts
export const ElementNotFound = createError<{ id: string; }>( 'element-not-found', 'Element not found' );

function renderElement( id: string ): string {
    const element = findElementById( id );

    if ( ! element ) {
        throw new ElementNotFound({ context: { id } });
    }

    return element.render();
}
```

有原因的例子 :

```ts
export const CannotSave = createError<{ id: number; status: string; }>( 'cannot-save', 'Cannot save document' );

try {
     thirdPartyService.save( id );
} catch ( error ) {
    throw new CannotSave({ context: { id, status: error.status }, cause: error });
}
```

### `ensureError`

这个 `ensureError` 函数是一个工具函数,可以确保给定值是一个错误. 如果该值已经是错误, 将按原样返回 . 如果值不是错误, 则用 `Error` 包括抛出值.

```ts
import { ensureError } from '@elementor/utils';

const CannotUpdate = createError<{ id: number; }>( 'cannot-update', 'Cannot update document' );

try {
    thirdPartyService.update( id );
} catch ( error ) {
    const errorInstance = ensureError( error );

    throw new CannotUpdate({ context: { id }, cause: errorInstance });
}
```

## 常见问题

### @elementor/utils 是什么？

此软件包包含正在跨元素包使用的功能

### 如何安装 @elementor/utils？

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

### @elementor/utils 支持 TypeScript 吗？

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

### @elementor/utils 支持 ESM 还是 CommonJS？

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

### @elementor/utils 可以商用吗？

@elementor/utils 使用 GPL-3\.0-or-later 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @elementor/utils 的下载量有多少？

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

### @elementor/utils 还在维护吗？

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

