命令选项/标志

标志（flags）是带有双连字符（--）或单连字符（-）（称为标志别名）的命名参数。标志可以按任意顺序指定。

你必须将标志定义为类属性，并使用 @flags 装饰器对其进行装饰。在以下示例中，我们定义了 resource 和 singular 标志，两者都表示一个布尔值。

import { BaseCommand, flags } from '@adonisjs/core/ace'

export default class MakeControllerCommand extends BaseCommands {
  @flags.boolean()
  declare resource: boolean

  @flags.boolean()
  declare singular: boolean
}

标志类型

Ace 允许为以下类型之一定义标志。

布尔标志

布尔标志使用 @flags.boolean 装饰器定义。指定该标志会将其值设为 true。否则，标志值为 undefined。

make:controller --resource

# this.resource === true

make:controller

# this.resource === undefined

make:controller --no-resource

# this.resource === false

最后一个示例表明布尔标志可以使用 --no- 前缀进行取反。

默认情况下，取反的选项不会显示在帮助输出中。不过，你可以使用 showNegatedVariantInHelp 选项启用它。

export default class MakeControllerCommand extends BaseCommands {
  @flags.boolean({
    showNegatedVariantInHelp: true,
  })
  declare resource: boolean
}

字符串标志

字符串标志接受标志名称之后的一个值。你可以使用 @flags.string 方法定义一个字符串标志。

import { BaseCommand, flags } from '@adonisjs/core/ace'

export default class MakeControllerCommand extends BaseCommands {
  @flags.string()
  declare model: string
}

make:controller --model user

# this.model = 'user'

如果标志值包含空格或特殊字符，必须用引号 "" 包裹起来。

make:controller --model blog user
# this.model = 'blog'

make:controller --model "blog user"
# this.model = 'blog user'

如果指定了标志但没有提供值（即使该标志是可选的），也会显示错误。

make:controller
# 正常！未指定可选标志

make:controller --model
# 错误！缺少值

数字标志

数字标志的解析方式类似于字符串标志。不过，会对值进行校验以确保它是一个有效的数字。

你可以使用 @flags.number 装饰器创建一个数字标志。

import { BaseCommand, flags } from '@adonisjs/core/ace'

export default class MakeUserCommand extends BaseCommands {
  @flags.number()
  declare score: number
}

数组标志

数组标志允许在运行命令时多次使用该标志。你可以使用 @flags.array 方法定义一个数组标志。

import { BaseCommand, flags } from '@adonisjs/core/ace'

export default class MakeUserCommand extends BaseCommands {
  @flags.array()
  declare groups: string[]
}

make:user --groups=admin --groups=moderators --groups=creators

# this.groups = ['admin', 'moderators', 'creators']

标志名称与描述

默认情况下，标志名称是类属性名的 dash 格式（短横线分隔）表示。不过，你可以通过 flagName 选项定义一个自定义名称。

@flags.boolean({
  flagName: 'server'
})
declare startServer: boolean

标志描述会显示在帮助屏幕上。你可以使用 description 选项进行定义。

@flags.boolean({
  flagName: 'server',
  description: 'Starts the application server'
})
declare startServer: boolean

标志别名

别名是使用单连字符（-）指定的标志的简写名称。别名必须是单个字符。

@flags.boolean({
  alias: ['r']
})
declare resource: boolean

@flags.boolean({
  alias: ['s']
})
declare singular: boolean

运行命令时，标志别名可以组合使用。

make:controller -rs

# 等同于
make:controller --resource --singular

默认值

你可以使用 default 选项定义标志的默认值。当未指定标志或指定了但未带值时，会使用默认值。

@flags.boolean({
  default: true,
})
declare startServer: boolean

@flags.string({
  default: 'sqlite',
})
declare connection: string

处理标志值

使用 parse 方法，你可以在将标志值定义为类属性之前对其进行处理。

@flags.string({
  parse (value) {
    return value ? connections[value] : value
  }
})
declare connection: string

访问所有标志

你可以使用 this.parsed.flags 属性访问运行命令时提到的所有标志。flags 属性是一个键值对对象。

import { BaseCommand, flags } from '@adonisjs/core/ace'

export default class MakeControllerCommand extends BaseCommands {
  @flags.boolean()
  declare resource: boolean

  @flags.boolean()
  declare singular: boolean
  
  async run() {
    console.log(this.parsed.flags)
    
    /**
     * 指定但未
     * 被命令接受的标志名称
     */
    console.log(this.parsed.unknownFlags)
  }
}

Ace 命令

命令参数