进阶 oclif.io 2026-10-18 02:37:03 · 23 阅读
第30章 oclif 帮助类:自定义 CLI 帮助输出指南
Help Classes
oclif 开箱即用地为 CLI 提供出色的帮助体验。用户可通过 --help 标志调用帮助。
$ my-cli login --help
若希望 CLI 拥有显式的 help 命令,请在配置中将 @oclif/plugin-help 添加为 oclif 插件。 $ my-cli help
自定义帮助 首先,在 package.json 的 oclif 配置中定义帮助类的文件路径。此路径为相对路径,不含文件扩展名。 在本例中,帮助类将创建于 “[项目根目录]/src/help.ts” 文件。 { "oclif": { "helpClass": "./dist/help" } }
接下来有两条路径:自行实现 HelpBase 抽象类,或重写默认 Help 类中需自定义的部分(例如命令用法的显示方式)。我们推荐后者,但下文将涵盖两种方法。 扩展 HelpBase 类 HelpBase 抽象类提供了起点,仅要求实现与 oclif 兼容所需的最少方法。 import {Command, HelpBase} from '@oclif/core'; export default class CustomHelp extends HelpBase { showHelp(args: string[]) { console.log('This will be displayed in multi-command CLIs') } showCommandHelp(command: Command.Loadable) { console.log('This will be displayed in single-command CLIs') } }
oclif 调用 showHelp 方法在多命令 CLI 中显示帮助,而单命令 CLI 则直接调用 showCommandHelp。 该类实例化时带有一个 config 属性,提供构建自定义输出所需的有用上下文。 要了解更多可能性,请参阅 @oclif/core 导出的默认 Help 类的源代码。 扩展默认 Help 类 默认 Help 类提供许多方法“钩子”,便于重写帮助输出中需自定义的特定部分。 import {Command, Help, Interfaces} from '@oclif/core' export default class MyHelpClass extends Help { // acts as a "router" // and based on the args it receives // calls one of showRootHelp, showTopicHelp, // the formatting for an individual command formatCommand(command: Command.Loadable): string {} // the formatting for a list of commands formatCommands(commands: Command.Loadable[]): string {} // displayed for the root help formatRoot(): string {} // the formatting for an individual topic
formatTopic(topic: Interfaces.Topic): string {}
// showRootHelp、showTopicHelp 和 showCommandHelp 的默认实现
// 会调用各种 format 方法,
// 为对应的帮助区块生成格式化内容;
// 这些方法同样可以被覆盖
// 负责标题部分的格式化
// 负责主题列表的格式化
protected formatTopics(topics: Interfaces.Topic[]): string {}
// 显示某个命令的帮助
showCommandHelp(command: Command.Loadable): void {}
// 或 showCommandHelp
showHelp(args: string[]): void {}
// 显示 CLI 的根帮助
showRootHelp(): void {}
// 显示某个主题的帮助
showTopicHelp(topic: Interfaces.Topic): void {}
}
想查看这些方法的默认实现,可以看 @oclif/core 导出的默认 Help 类。 想动手试试的话,可以在自定义 help 类中定义 showCommandHelp 并修改输出内容。 import {Command, Help} from '@oclif/core';
export default class MyHelpClass extends Help {
public showCommandHelp(command: Command.Loadable) {
console.log('Display my custom command help!')
}
}
然后对任意命令运行 help。 $ my-cli login --help
Display my custom command help!
若希望 CLI 拥有显式的 help 命令,请在配置中将 @oclif/plugin-help 添加为 oclif 插件。 $ my-cli help
自定义帮助 首先,在 package.json 的 oclif 配置中定义帮助类的文件路径。此路径为相对路径,不含文件扩展名。 在本例中,帮助类将创建于 “[项目根目录]/src/help.ts” 文件。 { "oclif": { "helpClass": "./dist/help" } }
接下来有两条路径:自行实现 HelpBase 抽象类,或重写默认 Help 类中需自定义的部分(例如命令用法的显示方式)。我们推荐后者,但下文将涵盖两种方法。 扩展 HelpBase 类 HelpBase 抽象类提供了起点,仅要求实现与 oclif 兼容所需的最少方法。 import {Command, HelpBase} from '@oclif/core'; export default class CustomHelp extends HelpBase { showHelp(args: string[]) { console.log('This will be displayed in multi-command CLIs') } showCommandHelp(command: Command.Loadable) { console.log('This will be displayed in single-command CLIs') } }
oclif 调用 showHelp 方法在多命令 CLI 中显示帮助,而单命令 CLI 则直接调用 showCommandHelp。 该类实例化时带有一个 config 属性,提供构建自定义输出所需的有用上下文。 要了解更多可能性,请参阅 @oclif/core 导出的默认 Help 类的源代码。 扩展默认 Help 类 默认 Help 类提供许多方法“钩子”,便于重写帮助输出中需自定义的特定部分。 import {Command, Help, Interfaces} from '@oclif/core' export default class MyHelpClass extends Help { // acts as a "router" // and based on the args it receives // calls one of showRootHelp, showTopicHelp, // the formatting for an individual command formatCommand(command: Command.Loadable): string {} // the formatting for a list of commands formatCommands(commands: Command.Loadable[]): string {} // displayed for the root help formatRoot(): string {} // the formatting for an individual topic
formatTopic(topic: Interfaces.Topic): string {}
// showRootHelp、showTopicHelp 和 showCommandHelp 的默认实现
// 会调用各种 format 方法,
// 为对应的帮助区块生成格式化内容;
// 这些方法同样可以被覆盖
// 负责标题部分的格式化
// 负责主题列表的格式化
protected formatTopics(topics: Interfaces.Topic[]): string {}
// 显示某个命令的帮助
showCommandHelp(command: Command.Loadable): void {}
// 或 showCommandHelp
showHelp(args: string[]): void {}
// 显示 CLI 的根帮助
showRootHelp(): void {}
// 显示某个主题的帮助
showTopicHelp(topic: Interfaces.Topic): void {}
}
想查看这些方法的默认实现,可以看 @oclif/core 导出的默认 Help 类。 想动手试试的话,可以在自定义 help 类中定义 showCommandHelp 并修改输出内容。 import {Command, Help} from '@oclif/core';
export default class MyHelpClass extends Help {
public showCommandHelp(command: Command.Loadable) {
console.log('Display my custom command help!')
}
}
然后对任意命令运行 help。 $ my-cli login --help
Display my custom command help!