第6章 自定义 oclif 的帮助输出
第6章:自定义 oclif 中的帮助功能
2020年5月5日 · 2分钟阅读
oclif 开箱即用地为 CLI 提供了极佳的帮助体验。但作为 oclif 开发者,如果你想定制部分或全部输出,该怎么办?现在你可以通过实现 HelpBase 抽象类来定制 CLI 的帮助输出。
开始使用自定义帮助
如果尚未操作,请先更新 @oclif/core。
$ yarn add --latest @oclif/core
要开始动手,首先在 package.json 中 oclif 的配置部分定义帮助类的文件路径。这是一个相对于项目根目录的路径,无需包含文件扩展名。
在本例中,帮助类将创建在 "[项目根目录]/src/help.ts" 文件中。
{ // ... "oclif": { "helpClass": "./lib/help" // ... } // ... }
接下来有两条路径可选:要么自己实现 HelpBase 抽象类,要么重写默认 Help 类中你想要定制的部分(例如:如何显示命令用法)。我们推荐采用后一种方法,但新的帮助类文档中涵盖了这两种方式。
在新的默认 Help 类中分离 TOPICS 与 COMMANDS
以往,主题(topics)和子命令(child commands)在帮助输出中混合在同一个名为 "COMMANDS" 的列表标题下。但我们发现这可能会造成轻微混淆。有些主题本身也是命令(即 topic-commands),而另一些仅仅是用于组织命名空间的结构名称(直接运行时仅显示其帮助)。
新的默认 Help 类将子项列表拆分为 "TOPICS" 和 "COMMANDS" 两个独立列表;如果一个条目既是主题又是命令,它会同时出现在这两个列表中。这使得查看帮助输出时更加清晰:哪些是预期要运行的命令("COMMANDS"),哪些是提供结构层级的主题("TOPICS")。
VERSION plugin-help-example/0.0.0 darwin-x64 node-v12.12.0
USAGE $ plugin-help-example [COMMAND]
TOPICS topic this is a topic and has child topics or commands
COMMANDS hello describe the command here help display help for plugin-help-example
期待看到你们利用这一新功能在 oclif CLI 中实现的各种自定义帮助特性!