---
title: API 参考
description: I18nErrorBase、setErrorMessage 及相关类型的规范。
---

## `I18nErrorBase` [#i18n-error-base]

用于继承 `Error` 的基类。`message` 根据 `lang` 解析。

```ts
import { I18nErrorBase } from "i18n-error-base";

class MyError extends I18nErrorBase<{ code: string }> {}
```

### 类型参数 [#type-params]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `TMeta` | `ErrorMeta \| undefined` | `ErrorMeta \| undefined` | `meta` 的类型。不使用时指定 `undefined`。 |

### 静态属性 [#static-props]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `prefix?` | `string` | `undefined` | 拼接到解析后消息的开头。 |

### 实例属性 [#instance-props]

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `meta` | `TMeta` | 构造函数的附带信息，可读写。 |
| `message` | `string` | 根据 `lang` 解析的消息，可枚举。 |
| `cause` | `unknown` | 经 `ErrorOptions` 传入的原因，`Error` 的标准属性。 |

### 构造函数 [#constructor]

`TMeta` 不包含 `undefined` 时，`meta` 为必填。

```ts
new MyError(meta, message, options?)
```

`TMeta` 为 `undefined` 时，可省略 `meta`。

```ts
new MyError(message, options?)
new MyError(meta, message, options?)
```

| 参数 | 类型 | 说明 |
| ------------ | -- | ---- |
| `meta` | `TMeta` | 用于消息生成的附带信息。 |
| `message` | `string \| MessageFactory<TMeta>` | 用于未注册语言的默认消息。为函数时接收 `meta`。 |
| `options` | `ErrorOptions` | 与 `Error` 第二个参数兼容的选项（例如 `{ cause }`）。 |

### 解析顺序 [#resolution-order]

1. 获取 `getGlobalConfig()` 的 `lang`（未设置时为 `"en"`）
2. 执行该类、该语言的注册函数，并传入 `meta`
3. 未注册时使用默认消息
4. 如有 `static prefix`，则拼接到开头

:::note
注册按类区分。父类的注册不会被子类继承，请按类分别注册。
:::

## `setErrorMessage` [#set-error-message]

注册各语言的消息生成函数。

```ts
import { setErrorMessage } from "i18n-error-base";

setErrorMessage(MyError, (meta) => `...: ${meta.code}`, "ja");
```

| 参数 | 类型 | 说明 |
| ------------ | -- | ---- |
| `reference` | `I18nErrorBaseConstructor` | 继承了 `I18nErrorBase` 的类。未继承的类是类型错误。 |
| `message` | `string \| (meta) => string` | 要注册的消息。`meta` 的类型从目标类推断。 |
| `lang` | `string \| Iterable<string>` | 目标语言。单个代码或可迭代对象（例如数组）。 |

同一类、同一语言的重新注册会覆盖。

## 类型 [#types]

### `ErrorMeta` [#error-meta]

```ts
type ErrorMeta = {
  readonly [prop: string]: unknown;
};
```

`TMeta` 的默认约束。具有任意属性的只读对象。

### `ErrorOptions` [#error-options]

```ts
type ErrorOptions =
  ConstructorParameters<typeof Error> extends [
    message?: unknown,
    options?: (infer TOptions) | undefined,
  ]
    ? TOptions
    : { readonly cause?: unknown };
```

从 `Error` 第二个参数推导的类型。可传入 `cause`。

### `MessageFactory<TMeta>` [#message-factory]

```ts
interface MessageFactory<TMeta extends ErrorMeta | undefined = ErrorMeta | undefined> {
  (meta: TMeta): string;
}
```

根据 `meta` 生成消息的函数。既可用于默认消息，也可用于注册值。

### `I18nErrorBaseParams<TMeta>` [#i18n-error-base-params]

构造函数参数重载。

```ts
type I18nErrorBaseParams<TMeta extends ErrorMeta | undefined = ErrorMeta | undefined> =
  [TMeta] extends [undefined]
    ?
        | [message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined]
        | [meta: undefined, message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined]
    : [meta: TMeta, message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined];
```

仅当 `TMeta` 为 `undefined` 时，才可省略 `meta`。

### `I18nErrorBaseConstructor` [#i18n-error-base-constructor]

```ts
interface I18nErrorBaseConstructor {
  new (...args: any): I18nErrorBase;
}
```

`setErrorMessage` 第一个参数的类型。

## 补充说明 [#notes]

- `lang` 默认值为 `"en"`，请通过 `setGlobalConfig({ lang })` 切换
- 不规范化语言代码，也没有回退链（例如 `en-US` → `en`）。未注册的语言使用默认消息