--- title: 上下文 --- # 上下文 在 `handler` 和 `interceptor` 中,接收到的第一个参数均为一个上下文对象。这两种情况下的上下文键均相同,只有部分值会有所不同。 ## 类型 ```ts export interface BaseContext< C extends Command = Command, GF extends ClercFlagsDefinition = {}, > { resolved: boolean; command?: C; calledAs?: string; parameters: InferParameters>; flags: InferFlagsWithGlobal; ignored: string[]; rawParsed: ParsedResult>; store: Partial; } ``` - `resolved`:一个布尔值,指示是否找到了匹配的命令。 - `command`:当前解析的命令对象,如果没有匹配的命令则为 `undefined`。 - `calledAs`:用户调用的命令名称(可能是别名)。 - `parameters`:一个对象,包含解析后的参数值。如果没有匹配到命令,则为空对象。 - `flags`:一个对象,包含解析后的选项值。如果没有匹配到命令,则为空对象。 - `ignored`:一个字符串数组,包含未被解析的参数。 - `rawParsed`:包含解析器原始解析结果的对象。这对于需要访问简化上下文属性未公开的信息的高级用例非常有用。 - `store`:一个共享存储对象,可用于在 CLI 应用程序的不同部分之间存储数据。 ### rawParsed `rawParsed` 属性的类型为 `ParsedResult`,包含解析器的完整解析结果。请参见 [API Reference](https://clerc.so1ve.dev/reference/api/parser/Interface.ParsedResult)。 `handler` 的上下文是 `BaseContext` 的一个特化。它的 `resolved` 属性始终为 `true`,并且 `command` 属性始终为当前命令对象,`calledAs` 也始终有值。 ## 存储 API `ctx.store` 和 `cli.store` 都提供对共享存储对象的访问,该对象可用于在 CLI 应用程序的不同部分之间存储数据。它们是等价的 - `ctx.store` 是在构建上下文时创建的 `cli.store` 的副本。 ### 使用方法 ```ts const cli = Clerc.create() .scriptName("my-cli") .description("我的 CLI 应用程序") .version("1.0.0") .use(helpPlugin()) .command("config", "配置应用程序") .on("config", (ctx) => { // 存储配置数据 ctx.store.config = { apiUrl: "https://api.example.com", timeout: 5000, }; console.log("配置已保存"); }) .command("status", "显示应用程序状态") .on("status", (ctx) => { // 访问存储的配置数据 const config = ctx.store.config; if (config) { console.log(`API URL: ${config.apiUrl}`); console.log(`超时时间: ${config.timeout}ms`); } else { console.log("未找到配置"); } }) .parse(); // 也可以通过 cli.store 访问存储 const config = cli.store.config; ``` ### 存储与上下文存储的区别 - `cli.store`:附加到 CLI 实例的主存储对象。在此处所做的更改在所有命令执行之间保持持久。 - `ctx.store`:为每个命令执行创建的 `cli.store` 副本。在此处所做的更改仅限于该特定执行。 ### 插件扩展 插件可以扩展 `ContextStore` 接口以添加自己的存储属性: ```ts // 在插件中 declare module "@clerc/core" { export interface ContextStore { help: { addGroup: (options: GroupsOptions) => void; }; } } cli.store.help.addGroup({ commands: [["custom", "自定义命令"]], }); ``` 这允许插件提供自己的存储 API,可以通过存储对象访问。