155 lines
5.4 KiB
Markdown
155 lines
5.4 KiB
Markdown
<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
|
|
更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/registry.md` 重新记录配对。 -->
|
|
|
|
# 注册表
|
|
|
|
[English](registry.md) | 中文
|
|
|
|
插件加载与依赖注入。
|
|
|
|
### ctx.inject(deps, callback)
|
|
|
|
```ts cordis-catalog
|
|
/**
|
|
* Run a callback once the requested services are available.
|
|
*
|
|
* Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
|
|
* is unloaded and re-run whenever a required service changes.
|
|
*
|
|
* @param deps — required services, as an array or a name → config map.
|
|
* @param callback — plugin body called with `(ctx, config)`.
|
|
* @returns the fiber; awaiting it settles once loading finished.
|
|
*/
|
|
inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
|
|
```
|
|
|
|
当请求的服务可用后，运行一次回调。
|
|
|
|
这是 `ctx.plugin({ inject, apply: callback })` 的简写形式：每当某个必需服务发生变化时，系统都会卸载并重新运行该回调。
|
|
|
|
- `deps`：必需服务，形式可以是数组，也可以是从名称到配置的映射。
|
|
- `callback`：以 `(ctx, config)` 调用的插件主体。
|
|
|
|
**返回** fiber；对其执行 await 会在加载完成后结束等待。
|
|
|
|
[源码](../../vendor/cordis/src/registry.ts#L176)
|
|
|
|
### ctx.plugin(plugin, ...args)
|
|
|
|
```ts cordis-catalog
|
|
/**
|
|
* Load a plugin in the current context.
|
|
*
|
|
* @param plugin — a function, class, or `{ apply }` object plugin.
|
|
* @param args — the plugin config, validated against its `Config` schema.
|
|
* @returns the fiber; awaiting it settles once loading finished
|
|
* (rejecting on config or startup errors).
|
|
*/
|
|
plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
|
|
```
|
|
|
|
在当前上下文中加载插件。
|
|
|
|
- `plugin`：函数、类或 `{ apply }` 对象形式的插件。
|
|
- `args`：插件配置，会根据其 `Config` schema 进行校验。
|
|
|
|
**返回** fiber；对其执行 await 会在加载完成后结束等待（如果发生配置错误或启动错误，则会被拒绝）。
|
|
|
|
[源码](../../vendor/cordis/src/registry.ts#L185)
|
|
|
|
## Plugin
|
|
|
|
支持的插件入口点形式。
|
|
|
|
```ts cordis-catalog
|
|
/** Supported plugin entrypoint shapes. */
|
|
type Plugin<T = any> =
|
|
| Plugin.Function<T>
|
|
| Plugin.Constructor<T>
|
|
| Plugin.Object<T>
|
|
|
|
/** Types associated with plugin entrypoints and runtime records. */
|
|
namespace Plugin {
|
|
/** Shared metadata understood by the plugin registry and related tooling. */
|
|
export interface Base<T = any> {
|
|
/** Display name used for fiber diagnostics and logger names. */
|
|
name?: string
|
|
/** Standard-schema validator applied to config before the plugin starts. */
|
|
Config?: StandardSchemaV1<any, T>
|
|
/** Services the plugin requires; it only loads while all are available. */
|
|
inject?: Inject
|
|
/** Service name(s) the plugin provides (read by `Service` and by loaders). */
|
|
provide?: string | string[]
|
|
/** Service names whose intercept config the plugin declares it consumes. */
|
|
intercept?: Dict<boolean>
|
|
}
|
|
|
|
export interface Transform<S, T> {
|
|
/** Marks the transform object as a schema/config transform. */
|
|
schema?: true
|
|
/** Convert user-facing config to runtime config. */
|
|
Config: (config: S) => T
|
|
}
|
|
|
|
/** Function plugin called with `(ctx, config)`. */
|
|
export interface Function<T = any> extends Base<T> {
|
|
(ctx: Context, config: T): any
|
|
}
|
|
|
|
/** Class plugin constructed with `(ctx, config)`. */
|
|
export interface Constructor<T = any> extends Base<T> {
|
|
new (ctx: Context, config: T): any
|
|
}
|
|
|
|
/** Object plugin with an `apply(ctx, config)` method. */
|
|
export interface Object<T = any> extends Base<T> {
|
|
apply(ctx: Context, config: T): any
|
|
}
|
|
|
|
/** Mutable registry record shared by all fibers of one plugin callback. */
|
|
export interface Runtime {
|
|
/** Display name copied from the first registered plugin shape. */
|
|
name?: string
|
|
/** Every live fiber of this plugin (one per `ctx.plugin()` call). */
|
|
fibers: DisposableList<Fiber>
|
|
/** The executable entrypoint all fibers share (registry identity key). */
|
|
callback: globalThis.Function
|
|
/** Standard-schema validator applied to each fiber's config. */
|
|
Config?: StandardSchemaV1
|
|
}
|
|
}
|
|
```
|
|
|
|
[源码](../../vendor/cordis/src/registry.ts#L92)
|
|
|
|
## Inject
|
|
|
|
插件和 `@Inject` 装饰器接受的服务依赖声明。
|
|
|
|
数组形式请求不带拦截配置的服务。对象形式将每个服务名称映射到插件上下文中可选的拦截配置。
|
|
|
|
```ts cordis-catalog
|
|
/**
|
|
* Service dependency declaration accepted by plugins and the `@Inject`
|
|
* decorator.
|
|
*
|
|
* Array form requests services without intercept config. Object form maps each
|
|
* service name to optional intercept config for the plugin context.
|
|
*/
|
|
type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
|
|
|
|
/** Utilities for normalizing plugin dependency declarations. */
|
|
namespace Inject {
|
|
/**
|
|
* Convert array/object/class-inherited inject metadata into a plain map.
|
|
*
|
|
* @param inject — the declaration to normalize; `null`/`undefined` add nothing.
|
|
* @param result — the map to fill (service name → intercept config or `null`).
|
|
* @returns `result`.
|
|
*/
|
|
export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
|
|
}
|
|
```
|
|
|
|
[源码](../../vendor/cordis/src/registry.ts#L19)
|