@elementor/utils

中文文档
4.4.1发布于 2026/11/16GPL-3.0-or-laterTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 2.1万

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

中文使用文档
文档目录3 节
  1. 错误
  2. createError
  3. ensureError

用户

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

错误

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

createError

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

创建新错误类型

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

// 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;) (中文(简体) ). 如果需要传递更多关于错误的信息,请在上下文中附加.

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 } );
    }
}

丢弃您的自定义错误类型

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

基本实例:

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();
}

有原因的例子 :

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 包括抛出值.

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 共发布 1,105 个版本,首次发布于 2024/07/24;过去 12 个月发布了 858 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
4.4.1latest2026/11/16今天
4.5.0-1192build2026/11/16今天
4.5.0-11912026/11/16今天
4.5.0-11902026/11/16今天
4.5.0-11892026/11/16今天
4.5.0-11882026/11/151 天前

其他发布通道:manual → 4.1.0-manual,4.2-beta1 → 4.2.0-beta1,beta → 4.4.0-beta3,build → 4.5.0-1192。

关于 @elementor/utils 的常见问题

@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 和提交记录判断。