第45章 oclif 主题(Themes)详解
oclif 支持主题,你可以将其打包在 CLI 中分发,用户也可以根据需要自行覆盖默认设置。
默认情况下,主题仅作用于帮助信息和 JSON 输出,但你也可以根据需要扩展主题以实现自定义用途。详情见下方的"扩展主题"部分。
theme.json
主题文件采用以下结构:
{
"bin": "white",
"command": "cyan",
"commandSummary": "white",
"dollarSign": "white",
"flag": "white",
"flagDefaultValue": "blue",
"flagOptions": "white",
"flagRequired": "red",
"flagSeparator": "white",
"json": {
"brace": "magenta",
"bracket": "magenta",
"colon": "dim",
"comma": "dim",
"key": "yellow",
"string": "green",
"number": "green",
"boolean": "green",
"null": "red"
},
"sectionDescription": "white",
"sectionHeader": "underline",
"topic": "white",
"version": "white"
}
支持的主题属性
如前所述,默认情况下主题仅应用于帮助信息和 JSON 输出。以下属性可用:
alias:ALIASES 部分下的别名。
bin:CLI 可执行文件的名称(例如 sf、heroku)。
command:命令的名称。
commandSummary:命令的摘要。
dollarSign:打印在示例和用法之前的 $ 符号。
flag:标志的名称和短字符。
flagDefaultValue:带有默认值的标志中显示的 [default: X]。
flagOptions:标志的可选值列表。
flagRequired:必填标志旁显示的 (required)。
flagSeparator:分隔短字符和长标志名称的逗号(例如 -f, --foo)。
json:JSON 输出的主题,包含:
brace:方括号 [ 和 ]。
bracket:花括号 { 和 }。
colon:冒号 :。
comma:逗号 ,。
key:所有键名。
string:字符串值。
number:数值。
boolean:布尔值。
null:null 值。
sectionDescription:各部分内的文本(例如 DESCRIPTION 下的所有内容)。
sectionHeader:部分标题(例如 DESCRIPTION)。
topic:TOPICS 部分下的主题。
version:根帮助下方显示的 VERSION 部分(例如 sf --help)。
这些属性的取值必须是以下之一:
十六进制颜色代码,例如 #FF0000;
RGB 颜色值,例如 rgb(255,255,255);
标准 ANSI 颜色(参见 https://github.com/chalk/chalk/#styles)。
无效的值将被忽略。
分发主题
将主题与 CLI 一起分发非常简单。
首先,需要在 CLI 中创建一个主题文件(结构如上所示)。然后,在 package.json 中告知 oclif 该文件的位置即可:
{
"/theme.json",
"/oclif.manifest.json",
"/dist",
],
"oclif": {
"theme": "theme.json"
}
}
务必将该文件添加到文件列表中,确保在发布到 npm 或使用 oclif pack 打包 CLI 时,该文件能随 CLI 一起打包。 覆盖主题 如果你的 CLI 已内置主题,用户可以通过在 CLI 配置目录(Unix 系统下为 ~/.config/
export default class Hello extends Command {
public async run(): Promise
this.info('starting process!')
// do some stuff...
this.info('still making progress!')
// do some more stuff...
this.info('process complete!')
}
public info(msg: string): void {
this.log(ux.colorize(this.config.theme?.info, 'info:'), msg)
}
}