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

第20章 命令标志约束

命令标志约束 除了使用 exclusive、exactlyOne 等属性在标志级别声明约束外,还可以使用与 chai 或 jest 用户非常熟悉的语法,在命令级别声明标志约束。 举个例子,以下是如何声明一个带有布尔标志 foo、bar 和 baz 的命令,并规定必须恰好使用其中两个。例如,MyCLI --foo --baz 是合法的,但 MyCLI --foo 或 MyCLI --foo --bar --baz 会抛出错误。 import {Command, Flags, Constraints} from '@oclif/core'

export class MyCLI extends Command {
static flags = {
foo: Flags.boolean(),
bar: Flags.boolean(),
baz: Flags.boolean()
}

static constraints = [
Constraints.flags('foo', 'bar', 'baz').are.requiredExactlyN(2)
]

async run() {
const {flags} = await this.parse(MyCLI)
// ...
}
}
约束 API 参考 ​ 顶层函数 ​ flag(name)/flags(name1, name2, ...) ​ flag() 和 flags() 是作为约束语句“起始器”的方法。前者只接受一个标志,后者接受多个标志。 combinationOf(name1, name2, ...) ​ 可用于 .dependentOn() 或 .exclusiveWith() 的参数中,表示一组标志将被整体评估,而不是分别评估。 可链接属性 ​ .is/.are ​ 这些可选的链接属性允许你以更自然的阅读方式编写约束。 这两个约束是等价的,但你可能会觉得其中一种更容易阅读。 Constraint.flags('foo', 'bar').requiredAny()
Constraints.flags('foo', 'bar').are.requiredAny()
约束函数 ​ 这些函数作用于在 flag() 或 flags() 中指定的标志。 .dependentOn(name1, name2, ...) ​ 指示被约束的标志要求至少存在另一个标志。 在这个例子中,要使用 foo,必须同时使用 bar 或 baz: Constraints.flag('foo').is.dependentOn('bar', 'baz')
使用 combinationOf() 来声明一组标志以便一起评估,而不是分开评估。 考虑这个例子,它指示 foo 仅在使用了 bar,或者同时使用了 baz1 和 baz2 的情况下才可以使用: Constraints.flag('foo').is.dependentOn('bar', Constraints.combinationOf('baz1', 'baz2'))
.exclusiveWith(name1, name2, ...)​ 表示受约束的标志不能与这里指定的任何一个标志同时使用。 在下面的示例中,foo 不能与 bar 或 baz 同时使用。注意,bar 和 baz 之间并不互相约束。 Constraints.flag('foo').is.exclusiveWith('bar', 'baz')
可以组合 combinationOf(),声明一组需要整体评估而不是逐一评估的标志。 请看下面的例子:只要使用了 bar,或者同时使用了 baz1 和 baz2,就不能使用 foo: Constraints.flag('foo').is.exclusiveWith('bar', Constraints.combinationOf('baz1', 'baz2'))
.mutuallyDependent()​ 表示受约束的标志要么必须一起使用,要么都不使用。 在下面的示例中,foo 和 bar 必须一起使用,或者都不使用: Constraints.flags('foo', 'bar').are.mutuallyDependent()
.mutuallyExclusive()​ 表示受约束的标志中最多只能使用一个。 在下面的示例中,foo 和 bar 不能同时使用: Constraints.flags('foo', 'bar').are.mutuallyExclusive()
.requiredAll()​ 表示所有受约束的标志都必须使用。 在下面的示例中,foo 和 bar 都是必需的标志。 Constraints.flags('foo', 'bar').are.requiredAll()
.requiredAny()​ 表示受约束的标志中至少要使用一个。 在下面的示例中,foo、bar、baz 这几个标志中至少要使用一个: Constraints.flags('foo', 'bar', 'baz').are.requiredAny()
.requiredAtLeastN(n)​ 表示受约束的标志中至少要使用 N 个。 在下面的示例中,foo、bar、baz 这几个标志中至少要使用两个: Constraints.flags('foo', 'bar', 'baz').are.requiredAtLeastN(2)
.requiredAtMostN(n)​ 表示受约束的标志中最多只能使用 N 个。 在下面的示例中,foo、bar、baz 这几个标志中最多只能使用两个: Constraints.flags('foo', 'bar', 'baz').are.requiredAtMostN(2)
.requiredExactlyN(n)​ 表示受约束的标志中必须恰好使用 N 个。 在下面的示例中,foo、bar、baz 这几个标志中必须恰好使用两个: Constraints.flags('foo', 'bar', 'baz').are.requiredExactlyN(2)
Conditionals(条件约束)​ 可以给约束加上条件,只在满足特定条件时才生效。 .when/.unless​ 用作约束条件的引导词。.unless 等价于"当条件不成立时"。 Constraints.flag('foo').is.requiredAll().when.thisIsTrue(someFn)
Constraints.flag('bar').is.requiredAll().unless.thisIsTrue(someOtherFn)
.and/.or 逻辑运算符,用于定义条件。 默认情况下,逻辑条件从左到右求值,如下例所示,可将其理解为 $(fn1 || fn2) \&\& fn3$: Constraints.flag('foo').is.requiredAll().when.thisIsTrue(fn1).or.thisIsTrue(fn2).and.thisIsTrue(fn3)
不过,可以添加更多的 .when 或 .unless 子句来定义表达式中的分组,如下例所示,可将其理解为 $fn1 || (fn2 \&\& fn3)$: Constraints.flag('foo').is.requiredAll().when.thisIsTrue(fn1).or.when.thisIsTrue(fn2).and.thisIsTrue(fn3)
.allFlagCriteriaSatisfied(flagTester) 接受一个对象,其键为标志名称,属性为接收标志值并返回布尔值的方法。 当所有方法均返回 true 时,约束即被满足。 在下例中,若 baz1 等于 5 且 baz2 等于 7,则 foo 和 bar 互斥: Constraints.flags('foo', 'bar').are.mutuallyExclusive().when.allFlagCriteriaSatisfied({
baz1: (v) => v === 5,
baz2: (v) => v === 7
})
.anyFlagCriterionSatisfied(flagTester) 接受一个对象,其键为标志名称,属性为接收标志值并返回布尔值的方法。 当任意一个方法返回 true 时,约束即被满足。 在下例中,若 baz1 等于 5 或 baz2 等于 7,则 foo 和 bar 互斥: Constraints.flags('foo', 'bar').are.mutuallyExclusive().when.anyFlagCriterionSatisfied({
baz1: (v) => v === 5,
baz2: (v) => v === 7
})
.thisIsTrue(flagTester) 接受一个方法,该方法接收一个从标志名称映射到值的对象,并返回布尔值。若方法返回 true,则约束被满足。 在下例中,若 baz1 等于 baz2,则 foo 和 bar 互斥: Constraints.flags('foo', 'bar').are.mutuallyExclusive().when.thisIsTrue((flags) => flags.baz1 === flags.baz2)

评论 (0)