进阶 oclif.io 2026-10-18 02:37:03 · 29 阅读

第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 该文件的位置即可:

{

"files": [
"/theme.json",
"/oclif.manifest.json",
"/dist",
],
"oclif": {
"theme": "theme.json"
}
}
务必将该文件添加到文件列表中,确保在发布到 npm 或使用 oclif pack 打包 CLI 时,该文件能随 CLI 一起打包。 覆盖主题​ 如果你的 CLI 已内置主题,用户可以通过在 CLI 配置目录(Unix 系统下为 ~/.config/,Windows 系统下为 %LOCALAPPDATA%\)中创建自定义的 theme.json 来覆盖默认主题。 用户可以在自己的 theme.json 中指定部分或全部主题属性,这意味着他们可以选择仅覆盖默认主题的某一项属性。 禁用主题​ 可以通过设置 _DISABLE_THEME 环境变量来禁用主题。 扩展主题​ 默认情况下,oclif 仅在帮助输出中使用主题,但你也可以将主题用于其他目的。例如,你可能希望在命令执行期间向用户记录带颜色的信息日志: import {Command, ux} from '@oclif/core'

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)
}
}

评论 (0)