Appearance
步骤类型参考
这一页适合写步骤时随手查阅
直接使用 defineStep.*() helper 时，不需要手写 type
只有在使用原始 DSL 对象时，才需要声明 type 字段，值使用驼峰格式，例如 autocompleteMultiselect
源码、事件和日志里看到的则是内部归一化后的 kind
所有步骤共享的基础字段
| 字段 | 作用 |
|---|---|
| id | 可选的结果 key，省略时会自动生成唯一 ID |
| defaultValue | 当前步骤的默认值 |
| when | 条件执行函数，支持异步；可读取 context.values、context.results 与 context.tools.commandExists() |
所有输入类、展示类和命令类步骤都支持这些基础字段
如果当前步骤的值或结果需要在后续逻辑、CLI 参数映射或外部代码里稳定引用，仍然建议显式写 id
输入类步骤
文本、路径与日期
| helper | type（DSL） | 常见字段 |
|---|---|---|
| defineStep.text | text | message、placeholder、required、validate、withGuide |
| defineStep.password | password | message、mask、required、validate |
| defineStep.path | path | message、placeholder、required、validate |
| defineStep.date | date | message、format、locale、minDate、maxDate、validate |
适合自由输入、敏感输入、文件路径选择和日期输入
单选
| helper | type（DSL） | 常见字段 |
|---|---|---|
| defineStep.select | select | message、options、maxItems、validate |
| defineStep.selectKey | selectKey | message、options、maxItems、validate |
| defineStep.autocomplete | autocomplete | message、options、placeholder、filter、maxItems |
适合选一个结果
- select 适合短列表
- autocomplete 适合长列表和可搜索列表
- selectKey 适合需要快捷键的短列表
多选
| helper | type（DSL） | 常见字段 |
|---|---|---|
| defineStep.multiselect | multiselect | message、options、required、validate |
| defineStep.autocompleteMultiselect | autocompleteMultiselect | message、options、placeholder、required |
| defineStep.groupMultiselect | groupMultiselect | message、options、required |
适合选多个结果
- multiselect 适合普通多选
- autocompleteMultiselect 适合长列表多选
- groupMultiselect 适合分组展示
布尔确认
| helper | type（DSL） | 常见字段 |
|---|---|---|
| defineStep.confirm | confirm | message、defaultValue |
适合 yes or no 这种分支入口
展示类步骤
| helper | type（DSL） | 常见字段 |
|---|---|---|
| defineStep.note | note | message、title |
| defineStep.box | box | message、title、width |
| defineStep.log | log | message、level |
这三类步骤主要负责输出，不会像输入类步骤那样把值写进 values
命令类步骤
| helper | kind | 常见字段 |
|---|---|---|
| defineStep.command | command | title、renderer、tty、parallel、retry、allowFailure、command、scriptFile、run |
command 步骤有三种主写法
- command 直接写命令字符串
- scriptFile 执行脚本文件
- run(context, io) 在 TypeScript 中手动控制
options 字段的形状
select、autocomplete 和 multiselect 相关步骤都支持两种写法
ts
options: ['react', 'vue', 'svelte']ts
options: [
{ label: 'React', value: 'react' },
{ label: 'Vue', value: 'vue', hint: '适合模板驱动场景' },
]第二种写法适合需要禁用状态、提示文案和更明确标签的场景
validate 的使用时机
输入类步骤通常都支持 validate
ts
defineStep.text({
id: 'version',
message: '版本号',
validate(value) {
return /^v?\d+\.\d+\.\d+$/.test(value) ? undefined : '版本号格式应为 x.y.z';
},
});校验函数适合处理单个字段约束，不适合承接整条 workflow 的业务规则
选择步骤的经验用法
| 需求 | 更合适的步骤 |
|---|---|
| 短列表单选 | select |
| 长列表单选 | autocomplete |
| 短列表多选 | multiselect |
| 长列表多选 | autocompleteMultiselect |
| 有分组的大列表 | groupMultiselect |
| 二元确认 | confirm |