API 参考

I18nErrorBase、setErrorMessage 及相关类型的规范。

`I18nErrorBase`

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

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

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

类型参数

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

静态属性

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

实例属性

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

构造函数

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

new MyError(meta, message, options?)

TMeta 为 undefined 时，可省略 meta。

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

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

解析顺序

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

`setErrorMessage`

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

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

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

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

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

类型

`ErrorMeta`

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

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

`ErrorOptions`

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

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

`MessageFactory<TMeta>`

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

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

`I18nErrorBaseParams<TMeta>`

构造函数参数重载。

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`

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

setErrorMessage 第一个参数的类型。

补充说明

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