3.yargs框架使用（常用API）

yargs框架使用（常用API）

常用API

• 初始化使用

  const yargs = require('yargs/yargs');
  const { hideBin } = require('yargs/helpers'); // hideBin用于做输入命令的参数解析
  const arg = hideBin(process.argv); // 得到命令参数
  const cli = yargs(arg);
  cli
    .argv; //调用.argv，完成yargs初始化，这时候，输入hahayh --help 或 hahayh --version就能显示帮助信息或版本了
  

  • hideBin(process.argv)
    • 会得到命令的参数，相当于:
      • require("process").argv.slice(2)

• 展示用法：

  • usage()

  cli
    .usage('Usage: hahayh [command] <options>') 
     // 展示用法,当我们使用--help的时候展示，或者使用了strict()时，命令输入错误，展示错误提示的时候展示。
     // 这里可以使用$0来标识命令名称，也就是package.json中的bin的属性
    .argv;
  

• 启用严格模式

  • strict()

  cli
    .strict()  // 启用严格模式，这个代表输入的参数不对的时候，会给我们一个错误提示。如果没有这条，那么输入错误是没有任何反馈的。
  

• 设置最少命令个数

  • demandCommand(个数，描述)

  cli
    .demandCommand(1, "A command is required. Pass --help to see all available commands and options.") // 需要输入的参数个数设定,当我们使用--help的时候展示，或者使用了strict()时，命令输入错误，展示错误提示的时候展示。
  

• 提示近似命令

  • .recommendCommands()

  cli
    .recommendCommands() // 当用户输错命令的时候，会提示近似命令
  

• 输入错误命令的处理

  • fail((err, msg) => {})

  cli
    .fail((err, msg) => { // 输入错误命令的时候进行处理，有了这个后，demandCommand无效,recommendCommands无效，其实就是--help的帮助信息看板无效
      // err是错误信息
      console.log(err)
      // 一般只需要打印err信息
    })
  

• 设置命令提示的宽度

  • wrap(列数)
    • 参数列数为Number
    • 如果跟控制台同宽，则可以使用：cli.terminalWidth()

  cli
    .wrap(cli.terminalWidth()) 
    // 设置命令提示的宽度，可以尝试输入-h看下，展示出来界面的一行文字的宽度是不一样的。
    // 参数是数字，比如100，表示列数
    // 如果宽度为终端的宽度，那么可以使用方法cli.terminalWidth(),这里的cli就是yargs(hideBin(process.argv))
  

• 自定义结尾

  • epilogue()
    • 参数为String
    • 可以使用dedent库去掉首尾缩进(不论是几个空格的缩进，都可以去除)

  const dedent = require('dedent');
  cli // 来自初始化的cli
    .epilogue(dedent`  111
  
   1 11  ` + '222')
  // 最终会显示如下
  /*
  111
  
  1 11222
  */
  
  // 自定义结尾，结尾加上我们想说的话,string类型
  // 这里可以使用一个很有意思的库dedent，能够去掉每行首位的所有空格，但是不去空行，也就是去掉缩进(任何数目空格的缩进都去掉)，注意去掉的是每行的收尾哦
  
  

• 选项options

  • 批量注册选项

    • options()

    cli  .options({  	debug: {      type: 'boolean',      describe: 'Bootstrap debug mode',      alias: 'd', // --debug的缩写-d，也可以使用上面的alias      hidden: false, // 这个options存在，但是可以控制--help的时候是否显示，一般用作内部开发用    },    rename: {      type: 'string',      describe: 'Bootstrap rename mode',      aliases: ['rn', 'yhrn'], // 别名可以写成数组形式,-rn 或 -yhrn      hidden: false,    }  })
    

  • 单个注册选项

    • option()

    cli  .option('register', { // 跟options的区别是options可以批量注册options，而option只能单个注册    type: 'string',    describe: 'define global registry',    alias: 'r',    hidden: false, // 这个options存在，但是可以控制--help的时候是否显示，一般用作内部开发用  })
    

• 给options分类

  • group([option1，option2，...]， 当前类别名称)

  cli  .group(['debug'], 'Dev Options')  .group(['version', 'help'], 'Cli Options')
  

• 命令command

  • 第一种：.command('init [name]', 'Do init a project', (yargs) => {}, (argv) => {})

    • 参数（4个）:

      • 第一个参数：命令格式

        • 命令格式中的[option]，在builder函数中注册

      • 第二个参数：描述

      • 第三个参数：builder函数

        • 参数为yargs
        • 当前函数常用于注册option

      • 第四个参数：handler函数

        • 参数为argv，命令输入时的参数

    cli  .command(    'init [name]',    'Do init a project',    (yargs) => {        yargs.option('name', {          type: 'string',          describe: 'Name of a project',          alias: 'n'        })    },    (argv) => {    	console.log(argv)        /*          如果你输入的命令是hahayh init -d -r npm -n yh-test          则得到的argv是：          {             _: [ 'init' ],            d: true,            debug: true,            r: 'npm',            register: 'npm',            n: 'yh-test',            name: 'yh-test',             '$0':'..\\..\\..\\AppData\\Roaming\\npm\\node_modules\\haha-cli\\bin\\index.js'           }        */      }  )
    

  • 第二种：

    • 参数(1个)：对象类型

    cli  .command({     command: 'list',     aliases: ['ls', 'la', 'll'],     describe: 'list local packages',     builder: (yargs) => {},     handler: (argv) => {       console.log(argv)     }  })
    

• 别名

  • 用alias()注册别名

    cli  .alias('h', 'help')
    

  • 用属性注册别名(options中、option中、command中、builder中，凡是用对象注册的，都可以用)

    • 单个别名alias，值为字符串
    • 多个别名aliases，值为数组

    cli .command({    command: 'list',    aliases: ['ls', 'la', 'll'], // 多别名    describe: 'list local packages',    builder: (yargs) => {},    handler: (argv) => {        console.log(argv)    }}) .command({    command: 'mark',    alias: 'mk',                 // 单别名    describe: 'mark aomthng',    builder: (yargs) => {},    handler: (argv) => {        console.log(argv)    }})
    

• 混入自定义属性

  • parse()

  const pkg = require("../package.json");const context = {  hahaVersion: pkg.version}const arg = hideBin(process.argv); // 得到命令参数cli // 初始化时的cli  // .argv;     // 调用.argv，完成yargs初始化，这时候，输入hahayh --help 或 hahayh --version就能显示帮助信息或版本了  // 最后也可以不用.argv，改成parse方法  .parse(arg, context) // 这个parse作用是将参数arg和context合并，注入到yargs中,当你输入hahayh ls 的时候，argv中（handler函数中）就有hahaVersion了，这个hahaVersion就来自于context
  

完整举例

#!/usr/bin/env node
const yargs = require('yargs/yargs');
const { hideBin } = require('yargs/helpers'); // hideBin用于做输入命令的参数解析
// console.log(hideBin(process.argv)); // 会得到命令的参数，相当于require("process").argv.slice(2)，这里的require("process")可以直接写成process，不用require也可以，一模一样的
// console.log(process.argv.slice(2)); 
const dedent = require('dedent');
const pkg = require("../package.json");

const context = {
  hahaVersion: pkg.version
}


const arg = hideBin(process.argv); // 得到命令参数
const cli = yargs(arg);
// yargs初始化
cli// yargs函数传入参数
  .usage('Usage: hahayh [command] <options>') // 展示用法,当我们使用--help的时候展示，或者使用了strict()时，命令输入错误，展示错误提示的时候展示。
  .demandCommand(1, "A command is required. Pass --help to see all available commands and options.") // 需要输入的参数个数设定,当我们使用--help的时候展示，或者使用了strict()时，命令输入错误，展示错误提示的时候展示。
                                                                                                     // 有了fail()后，此项无效
  .recommendCommands() // 当用户输错命令的时候，会提示近似命令
  .strict()  // 启用严格模式，这个代表输入的参数不对的时候，会给我们一个错误提示。如果没有这条，那么输入错误是没有任何反馈的。
  .fail((err, msg) => { // 输入错误命令的时候进行处理，有了这个后，demandCommand无效,recommendCommands无效，其实就是--help的帮助信息看板无效
    // 这个函数会执行2遍，第一遍err会是近似词提示，第二遍是错误信息
    // console.log('msg', msg)
    console.log('err', err)
    // 一般只需要打印err信息
  })
  .alias("h", "help")    // 别名，alias书写的顺序怎么样，那么展示就是怎么样的顺序
  .alias("v", "version")
  .wrap(cli.terminalWidth()) // 设置命令提示的宽度，可以尝试输入-h看下，展示出来界面的一行文字的宽度是不一样的。
             // 参数是数字，比如100，表示列数
             // 如果宽度为终端的宽度，那么可以使用方法cli.terminalWidth(),这里的cli就是yargs(hideBin(process.argv))
  .epilogue(dedent`
  When a command fails, all logs are written to lerna-debug.log in the current working directory.

  For more information, find our manual at https://github.com/lerna/lerna
`)        // 自定义结尾，结尾加上我们想说的话,string类型
             // 这里可以使用一个很有意思的库dedent，能够去掉每行首位的所有空格，但是不去空行，也就是去掉缩进(任何数目空格的缩进都去掉)，注意去掉的是每行的收尾哦
  .options({ // 增加选项
    debug: { // 相当于增加了一个--debug选项，类型是布尔，描述是'Bootstrap debug mode'
      type: 'boolean',
      describe: 'Bootstrap debug mode',
      alias: 'd', // --debug的缩写-d，也可以使用上面的alias
      hidden: false, // 这个options存在，但是可以控制--help的时候是否显示，一般用作内部开发用
    }
  })
  .option('register', { // 跟options的区别是options可以批量注册options，而option只能单个注册
    type: 'string',
    describe: 'define global registry',
    alias: 'r',
    hidden: false, // 这个options存在，但是可以控制--help的时候是否显示，一般用作内部开发用
  })
  .group(['debug'], 'Dev Options:')        // 对已经注册的options进行分类
  .group(['register'], 'Publish Options:')
  // 以上主要是注册option
  // 以下主要是注册command
  /*
    注册命令使用command方法有2两种
      第一种：.command('init [name]', 'Do init a project', (yargs) => {}, (argv) => {})
        参数(4个):
          第一个参数：命令格式
            命令格式中的[option]，在builder函数中注册
          第二个参数：描述
          第三个参数：builder函数
            参数为yargs
          第四个参数：handler函数
            参数为argv，命令输入时的参数
      第二种：
        参数(1个)：对象类型
        .command({
          command: 'list',
          aliases: ['ls', 'la', 'll'],
          describe: 'list local packages',
          builder: (yargs) => {},
          handler: (argv) => {
            console.log(argv)
          }
        })
  */
  .command('init [name]', 'Do init a project', (yargs) => {
    yargs.option('name', {
      type: 'string',
      describe: 'Name of a project',
      alias: 'n'
    })
  }, (argv) => {
    console.log(argv)
    /*
      如果你输入的命令是hahayh init -d -r npm -n yh-test
      则得到的argv是：
      { _: [ 'init' ],
        d: true,
        debug: true,
        r: 'npm',
        register: 'npm',
        n: 'yh-test',
        name: 'yh-test',
        '$0':
        '..\\..\\..\\AppData\\Roaming\\npm\\node_modules\\haha-cli\\bin\\index.js' }
    */
  })
  .command({
    command: 'list',
    aliases: ['ls', 'la', 'll'],
    describe: 'list local packages',
    builder: (yargs) => {},
    handler: (argv) => {
      console.log(argv)
    }
  })
  // .argv;     // 调用.argv，完成yargs初始化，这时候，输入hahayh --help 或 hahayh --version就能显示帮助信息或版本了
  // 最后也可以不用.argv，改成parse方法
  .parse(arg, context) // 这个parse作用是将参数arg和context合并，注入到yargs中,当你输入hahayh ls 的时候，argv中（handler函数中）就有hahaVersion了，这个hahaVersion就来自于context

  // 定义脚手架的时候，别名不能重复，否则会覆盖
  // 别名可以单数alias，单数时为字符串；也可以复数aliases，复数时为数组