node inquirer文档(译)

inquirer的目标和哲学

inquirer.js 努力打造一个易于嵌入和外形美观的node命令行界面(也许是'CLI'的世外桃源)。 inquirer.js 可以让下面这些事情变得更简单:

  • 提供错误反馈
  • 询问
  • 解析输入
  • 验证答案
  • 管理分层的 prompts

注意:inquirer.js为用户提供提供交互和查询会话流。如果您正在寻找一个完整的命令行程序,你可以检出commandervorpalargs等。

文档

安装

npm install inquirer  
var inquirer = require('inquirer');  
inquirer.prompt([/* 传入你要询问的问题*/]).then(function (answers) {  
    // 使用用户的反馈做任何你想做的事。
});

例子

https://github.com/SBoudrias/Inquirer.js/tree/master/examples

Methods

inquirer.prompt(questions)-> proise
启动提示接口(调查会话)

  • questions(Array),包含了问题对象(使用的是 reactive interface),你也可以传入一个Rx.Observable实例)。
  • 返回一个promise

inquire.registerPrompt(name,prompt)
注册一个prompt 插件到name下。

  • name(String)这个新的prompt的名称。(用于question 的type
  • prompt(Object) prompt 对象本身(插件)。

inquirer.createPromptModule() -> prompt function
创建一个自包含的inquirer模块。当你重写或者添加一个prmpt type的时候,如果你不想让它影响其它也依赖inquirer的库,可以调用这个。

var prompt = inquirer.createPromptModule();

prompt(questions).then(/* ... */);  

Objects

Questions

问题对象是包含与问题相关的值的hash:

  • type: (String) prompt 的类型。默认值:input,可能值: input,confirm, list,rawlist,expand,checkbox,password,editor;
  • name: (String) 将答案存储在答案 hash中所使用的名称。如果名称包含周期,则它会在答案hash中定义一个路径。
  • message: (String|Function) 要打印出来的问题。如果定义为一个函数,则第一个参数则是目前的询问会话的答案。
  • default:(String|Number|Array|Function) 如果用户没有输入的默认答案,或者一个返回默认值的函数。如果定义为一个函数,则第一个参数则是目前的询问会话的答案。
  • * choices*: (Array|Function)选择数组或者一个返回选择数组的函数。如果定义为一个函数,则第一个参数则是目前的询问会话的答案。数组的值可以是很简单的Strings 或者一个包含name(在列表中显示),value(用于保存在答案hash中)和short(选择后显示)这三个属性的Objects。选择数组还可以包含分隔符
  • validate: (Function) 接收用户输入和答案hash。如果答案验证通过,则应该返回true,否则返回一个错误消息(String),如果返回为false,则会提供一个默认的错误消息。
  • filter : (Function)接收用户输入并返回过滤后要在程序中使用的值。返回后的值将被添加的答案hash中。
  • when: (Function,Boolean) 接收当前的用户答案hash,根据这个问题是不是应该询问来返回true或者false。这个值也可以是简单的布尔类型。
  • pageSize: (Numer) 当使用list,rawList,expand或者checkbox时,更改要渲染的行数。
  • prefix: (String) 修改默认的前置 消息。
  • suffix: (String) 修改默认的后置 消息。

default,choices(如果定义为一个函数),validate,filterwhen 函数可以异步调用。无论返回一个promise或者使用this.async()来获取一个你要用它最终值来调用的回调函数。

{
  /* 优先方案: 使用promise*/
  filter: function () {
    return new Promise(/* 等等... */);
  },

  /* 传统方案: 使用this.async */
  validate: function (input) {
    // 将函数声明为异步,并保存完成的回调函数
    var done = this.async();

    // Do async stuff
    setTimeout(function () {
      if (typeof input !== 'number') {
        // 用完成的回调函数传递返回值。
        done('You need to provide a number');
        return;
      }
      // 用完成的回调函数传递返回值。
      done(null, true);
    }, 3000);
  }
}

Answers

一组 key/value hash 包含在每个询问中,客户端的答案。

  • Key : question对象的name属性。
  • Value : (由prompt来决定):
    • confirm: (Boolean),
    • input: 用户输入(如果定义了filter,则是被过滤后的值 )(String),
    • rawlist,list: 选择了的选项(如果没有指定值,则是名称)(String)。

Separator

可添加到choices数组的分隔符号:

//在问题对象中
choices: [ "Choice A", new inquirer.Separator(), "choice B" ]

// 将以这种方式显示
[?] What do you want to do?
 > Order a pizza
   Make a reservation
   --------
   Ask opening hours
   Talk to the receptionist

这个结构携带一个特许的String值,这个值会被用作分隔符。如果省略,则分隔符是--------

separator实例具有与separator相同的属性type

Prompt types


注意:允许在方括号([])中写的选项是可选的。否则是必须的。

list- {tyepe: 'list'}

接收 type,name,message,choices[,default,filter]属性。(注意 default 必须是数组中选择的index或者选择的value)。 inquirer

Raw List- {tyepe: 'rawlist'}

接收 type,name,message,choices[,default,filter]属性。(注意 default 必须是数组中选择的index)。 inquirer

Expand - {type: 'expand'}

接收type,name,message,choices[,default] 这些属性。(注意 default 必须是数组中选择的index)。如果default这个key没有提供,help会成为默认选择。

注意 choices对象,需要一个额外的参数key 提供给expand。这个参数必须是单个的(小写的)单词。h选项是prompt自己添加的,用户不用定义。

来看一个例子:

~/Document/oss/Inquirer.js
> node examples/expand.js
? Conflict on `file.js`:  (yadxH) y
>> Overwrite
~/Document/oss/Inquirer.js
> node examples/expand.js
? Conflict on `file.js`:  (yadxH) 
y) Overwrite  
a) Overwrite this one and all next  
d) Show diff  
-------------
x)  Abort  
h) Help.list all options  
Answer: d  

Checkbox - {type: 'checkbox'}

接收type,name,message,choices[,filter,validate,default] 属性。default预期是一个数组,包含选中的选项的值。

标记了{checked: true} 的选项默认会被选中。 标记了{disabled: true} 的选项将不能被选中。如果disabled 设置为string,则这个string会在临近这个不可选选项时输出,否则默认输出Disableddisabled属性还可以接受一个同步函数,这个函数接受的参数是用户已经选择的答案,返回一个布尔值或者字符串。

Confirm - {type: 'Confirm '}

接收type,name,message[,default] 属性。 如果用了的话default,它的期望值是一个boolean。

Input- {type: 'input'}

接收type,name,message[,default, filter, validate, transformer] 属性。

Password- {type: 'password'}

接收type,name,message[,default, filter, validate, transformer] 属性。

Editor - {type: 'editor '}

接收type,name,message[,default, filter, validate, transformer] 属性。 打开一个用户偏好的编辑器实例编辑一个临时文件。用户一旦退出这个编辑器,则临时文件的内容会被作为答案读入。这个编辑器是由读取到的$VISUAL或者$EDITOR 环境变量决定的。 如果两个都没读取到,则notepad(windows系统上)或者 Vim(Linux 或者Mac系统上)会被打。

用户界面和布局

和prompts一起,Inquirer 提供了一些基本的文本UI。

Bottom Bar- inquirer.ui.BottomBar

这个UI 在自由文本区下方呈现出一个固定的 text。在输出命令输出了较多内容时,怎么将一条消息固定到屏幕下方,这个东西就很有用了。

var ui = new inquirer.ui.BottomBar();

// pipe a Stream to the log zone
outputStream.pipe(ui.log);

// Or simply write output
ui.log.write('something just happened.');  
ui.log.write('Almost over, standby!');

// During processing, update the bottom bar content to display a loader
// or output a progress bar, etc
ui.updateBottomBar('new bottom bar content');  

Reactive界面

在Inquirer内部使用 JS reactive扩展 来处理事件和异步流。 这意味着您可以利用这个特性来提供更先进的流。例如,你可以动态地添加要问的问题:

var prompts = new Rx.Subject();  
inquirer.prompt(prompts);

// At some point in the future, push new questions
prompts.next({ /* question... */ });  
prompts.next({ /* question... */ });

// When you're done
prompts.complete();  

而且使用返回值process属性,你可以得到更精细粒度的回调:

inquirer.prompt(prompts).ui.process.subscribe(  
  onEachAnswer,
  onError,
  onComplete
);

平台支持(系统终端)

你应该很乐于看到inquirer对以下CLI支持得很好。这并不意味着我没有issue,如果发现问题,你可以提交给我们。

  • OS:
    • Terminal.app
    • iTerm
  • Windows:
    • ConEmu
    • cmd.exe
    • Powershell
    • Cygwin
  • Linux (Ubuntu, openSUSE, Arch Linux, etc):
    • gnome-terminal (Terminal GNOME)
    • konsole

更新动态(Release notes)

请参阅 Github 版本变更的部分

贡献

*Unit test * 单元测试用的Mocha.请为每个新特性添加单元测试或错误修复.npm test 运行测试。 *Documentation * 为每个API添加文档更新。 请即时发布错误修复和最新的文档!

我们希望为更多prompts和环境 提供良好的支持。如果你想提供帮助,我们愿意保留一份每个终端/操作系统的测试者名单,这样我们可以联系你,并在发布前得到反馈。如果你想成为测试员,请告诉我们。( tweet上找 @vaxilart)或者只用把你名字添加到wiki上。

License

版权(c)2016 Simon Boudrias(twitter:@vaxilart)MIT许可。

插件

Prompts

autocomplete: 展现用户输入后搜索到的options列表。 兼容其它包,例如 fuzzy.

checkbox-plus datetime inquirer-select-line command :简单的提示命令历史和动态自动补全。

inquirer-fuzzy-path inquirer-chalk-pipe inquirer-search-checkbox

查找 checkbox.

inquirer-prompt-suggest

licat

继续阅读此作者的更多文章