# optionator 中文文档

规范地址：https://npmcn.com/package/optionator/

版本：0\.9\.4
npm 元数据更新时间：2024-04-26T22:17:51.588Z
中文译文更新时间：2026-11-04T23:14:43.875Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/optionator
原文对照：https://npmcn.com/package/optionator/?lang=original
项目主页：https://github.com/gkz/optionator
源码仓库：https://github.com/gkz/optionator

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：50.2 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>= 0\.8\.0
- 运行依赖：6 个
- 首次发布：2013-11-02T01:40:11.286Z
- 最新版本发布：2024-04-26T22:17:51.408Z
- 近 30 天下载量：591763831（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 0 个）

## 中文简介

选项解析和帮助生成

## 安装

```sh
npm install optionator
```

也可以使用：`pnpm add optionator`、`yarn add optionator`、`bun add optionator`

## README

# Optionator

Optionator是一个JavaScript/Node.js选项解析和帮助生成库 [eslint](http://eslint.org/)， [掌握](http://graspjs.com/)， [LiveScript](http://livescript.net/)， [esmangle](https://github.com/estools/esmangle)， [escodegen](https://github.com/estools/escodegen), [更多的](https://www.npmjs.com/browse/depended/optionator)。

有关在线演示，请查看 [掌握在线演示](http://www.graspjs.com/#demo)。

[关于](https://npmcn.com/package/optionator/#readme-about) · [用法](https://npmcn.com/package/optionator/#readme-usage) · [设置格式](https://npmcn.com/package/optionator/#readme-settings-format) · [参数格式](https://npmcn.com/package/optionator/#readme-argument-format)

## 为什么?

其他选项解析器的问题，例如 `yargs` 或 `minimist`他们只是接受所有输入，不管有效与否。 使用Optionator，如果你输错了一个选项，它会给你一个错误（对你的意思有一个建议）。 如果您为某个选项提供了错误类型的参数，它将给您一个错误，而不是向您的应用程序提供错误的输入。

```
$ cmd --halp
Invalid option '--halp' - perhaps you meant '--help'?

$ cmd --count str
Invalid value for option 'count' - expected type Int, received value: str.
```

其他有用的功能包括根据控制台的大小重新格式化帮助文本，以便它适合即使控制台很窄，并接受不仅仅是一个数组(例如。的过程。Argv)，但也可以是字符串或对象，使测试之类的事情更容易。

## 关于

Optionator使用 [类型检查](https://github.com/gkz/type-check) 和 [levn](https://github.com/gkz/levn) 在后台根据指定的类型投射和验证输入。

麻省理工学院的许可。版本0.9.4

```
npm install optionator
```

有关Optionator的更新，请 [在twitter上关注我](https://twitter.com/gkzahariev)。

Optionator是一个Node.js模块，但如果打包了webpack/browserify，也可以在浏览器中使用。

## 用法

`require('optionator');` 返回一个函数。它有一个性质， `VERSION`，以字符串形式表示库的当前版本。此函数使用指定选项和其他信息的对象调用，请参阅 [设置格式部分](https://npmcn.com/package/optionator/#readme-settings-format)． 这反过来返回一个具有三个属性的对象， `parse`， `parseArgv`， `generateHelp`, `generateHelpForOption`，都是函数。

```js
var optionator = require('optionator')({
    prepend: 'Usage: cmd [options]',
    append: 'Version 1.0.0',
    options: [{
        option: 'help',
        alias: 'h',
        type: 'Boolean',
        description: 'displays help'
    }, {
        option: 'count',
        alias: 'c',
        type: 'Int',
        description: 'number of things',
        example: 'cmd --count 2'
    }]
});

var options = optionator.parseArgv(process.argv);
if (options.help) {
    console.log(optionator.generateHelp());
}
...
```

### parseOptions解析(输入)

`parse` 处理 `input` 根据您的设置，并返回一个带有结果的对象。

##### 参数

-   输入- `[String] | Object | String` -要解析的输入
-   parseOptions - `{slice: Int}` -所有选项可选
    -   `slice` 指定如果输入是数组或字符串（默认情况下），从开始切片的长度 `0` 对于字符串, `2` For数组(与 `process.argv`）

##### 返回

`Object` -解析的选项，每个键是选项名称的驼峰大小写版本（用破折号指定），每个值是该选项的处理值。下的数组中包含位置值 `_` 关键。

##### 例子

```js
parse(['node', 't.js', '--count', '2', 'positional']); // {count: 2, _: ['positional']}
parse('--count 2 positional');                         // {count: 2, _: ['positional']}
parse({count: 2, _:['positional']});                   // {count: 2, _: ['positional']}
```

### parseArgv(输入)

`parseArgv` 工作原理完全一样 `parse`，但只针对数组输入，它会分割前两个元素。

##### 参数

-   输入- `[String]` -要解析的输入

##### 返回

参见“parse”中的“returns”部分

##### 例子

```js
parseArgv(process.argv);
```

### generateHelp (helpOptions)

`generateHelp` 根据您的设置生成帮助文本。

##### 参数

-   helpOptions - `{showHidden: Boolean, interpolate: Object}` -所有选项可选
    -   `showHidden` 指定是否显示选项 `hidden: true` 指定，默认为 `false`
    -   `interpolate` 指定要插入的数据 `prepend` 和 `append` 文本, `{{key}}` 是格式-例如。 `generateHelp({interpolate:{version: '0.4.2'}})`我将改变这一点 `append` 文本: `Version {{version}}` 来 `Version 0.4.2`

##### 返回

`String` -生成的帮助文本

##### 例子

```js
generateHelp(); /*
"Usage: cmd [options] positional

  -h, --help       displays help
  -c, --count Int  number of things

Version  1.0.0
"*/
```

### generateHelpForOption (optionName)

`generateHelpForOption` 为指定的控件生成展开的帮助文本 `optionName` 选择。如果一个 `example` 为该选项指定，它将被显示，如果是 `longDescription` 时，它将显示该值而不是 `description`。

##### 参数

-   optionName - `String` -要显示的选项名称

##### 返回

`String` -该选项生成的帮助文本

##### 例子

```js
generateHelpForOption('count'); /*
"-c, --count Int
description: number of things
example: cmd --count 2
"*/
```

## 设置格式

当你的 `require('optionator')`，你会得到一个函数，它接受一个设置对象。这个对象的类型是：

```
{
  prepend: String,
  append: String,
  options: [{heading: String} | {
    option: String,
    alias: [String] | String,
    type: String,
    enum: [String],
    default: String,
    restPositional: Boolean,
    required: Boolean,
    overrideRequired: Boolean,
    dependsOn: [String] | String,
    concatRepeatedArrays: Boolean | (Boolean, Object),
    mergeRepeatedObjects: Boolean,
    description: String,
    longDescription: String,
    example: [String] | String
  }],
  helpStyle: {
    aliasSeparator: String,
    typeSeparator: String,
    descriptionSeparator: String,
    initialIndent: Int,
    secondaryIndent: Int,
    maxPadFactor: Number
  },
  mutuallyExclusive: [[String | [String]]],
  concatRepeatedArrays: Boolean | (Boolean, Object), // deprecated, set in defaults object
  mergeRepeatedObjects: Boolean, // deprecated, set in defaults object
  positionalAnywhere: Boolean,
  typeAliases: Object,
  defaults: Object
}
```

所有属性都是可选的 `Maybe` （为了简单起见被排除在外），除了有任何一个 `heading: String` 或 `option: String` 中的每个对象 `options` 数组中。

### 顶级属性

-   `prepend` 是否要在帮助文本中的选项之前放置一个可选字符串
-   `append` 是否要在帮助文本中的选项之后放置一个可选字符串
-   `options` 是否需要一个指定选项和标题的数组，选项和标题将按照指定的顺序显示
-   `helpStyle` 是一个可选对象，使您能够更改帮助文本某些方面的默认外观
-   `mutuallyExclusive` 是字符串数组或字符串数组的可选数组。顶层数组是一个规则列表，每个规则是一个元素列表——每个元素可以是一个字符串（一个选项的名称），也可以是一个字符串列表（一组选项名称）——如果存在多个元素，将会出现错误
-   `concatRepeatedArrays` 参见“选项属性”标题下的描述-不建议在顶层使用，如果您想为所有选项设置此属性，请使用 `defaults` 财产
-   `mergeRepeatedObjects` 参见“选项属性”标题下的描述-不建议在顶层使用，如果您想为所有选项设置此属性，请使用 `defaults` 财产
-   `positionalAnywhere` 是一个可选的布尔值(默认为 `true`) -何时 `true` 它允许位置参数在任何时间 `false`，在第一个位置参数之后的所有参数也被视为位置参数，即使它们看起来像一个标志。例如， `positionalAnywhere: false`，论点 `--flag --boom 12 --crack` 将有两个位置参数： `12` 和 `--crack`
-   `typeAliases` 是一个可选对象，它允许您为类型设置别名，例如。 `{Path: 'String'}` 会允许你使用这种类型吗 `Path` 作为类型的别名 `String`
-   `defaults` 是遵循选项属性格式的可选对象，它为所有选项指定默认值。如果手动设置，默认值将被覆盖。例如，你可以这样做 `default: { type: "String" }` 将所有选项的默认类型设置为 `String`，然后在单个选项中通过设置 `type` 财产

#### 标题属性

-   `heading` 必需的字符串，标题的名称

#### 选择属性

-   `option` 选项的必需名称——使用破折号，不带前导破折号
-   `alias` 是一个可选的字符串或字符串数组，其中指定了该选项的任何别名
-   `type` 中是否有必需的字符串 [类型检查](https://github.com/gkz/type-check) [格式](https://github.com/gkz/type-check#type-format)，这将用于强制转换输入值并对其进行验证
-   `enum` 是一个可选的字符串数组，每个字符串会被解析吗 [levn](https://github.com/gkz/levn) -参数值必须是结果值之一-每个潜在值必须对指定的值进行验证 `type`
-   `default` 是一个可选字符串，它将被解析 [levn](https://github.com/gkz/levn) 如果没有设置，则用作默认值-该值必须针对指定的值进行验证 `type`
-   `restPositional` 是否可选的布尔值- if设置为 `true`选项之后的所有内容都将被视为位置参数，即使它看起来像一个命名参数
-   `required` 是否可选的布尔值- if设置为 `true`，如果未定义选项，则选项解析将失败
-   `overrideRequired` 是否可选的布尔值- if设置为 `true` 这个选项被使用了，还有另一个选项是必需的，但没有设置，它会覆盖对必需选项的需要，并且不会出现错误——如果你有必需的选项并且想要使用，这是有用的 `--help` 或 `--version` 旗帜
-   `concatRepeatedArrays` 是一个可选的布尔值或具有布尔值和选项的元组对象(默认为 `false`) -当设置为时 `true` 如果一个选项包含一个数组值并且重复，则该标志的后续值将被附加，而不是覆盖原始值。选项 `g` 类型的 `[String]`： `-g a -g b -g c,d` 会导致 `['a','b','c','d']`

你可以通过给出以下值来提供一个options对象： `[true, options]`． 目前支持的选项是 `oneValuePerFlag`，这只允许每个标志一个数组值。如果潜在值包含逗号，这很有用。

-   `mergeRepeatedObjects` 是一个可选的布尔值(默认为 `false`) -当设置为时 `true` 如果一个选项包含一个对象值并且被重复，则该标志的后续值将被合并，而不是覆盖原始值。选项 `g` 类型的 `Object`： `-g a:1 -g b:2 -g c:3,d:4` 会导致 `{a: 1, b: 2, c: 3, d: 4}`
-   `dependsOn` 是一个可选的字符串或字符串数组-如果只是一个字符串（另一个选项的名称），它将确保设置其他选项，如果是字符串数组，取决于是否 `'and'` 或 `'or'` 首先，它将检查是否所有(`['and', 'option-a', 'option-b']`)，或至少一个(`['or', 'option-a', 'option-b']`)设置其他选项
-   `description` 是一个可选字符串，它将显示在帮助文本中的选项旁边
-   `longDescription` 是一个可选字符串，它将代替 `description` 当 `generateHelpForOption` 使用
-   `example` 是一个可选的字符串或字符串数组，其中包含该选项的示例-这些将在何时显示 `generateHelpForOption` 使用

#### 帮助样式属性

-   `aliasSeparator` 是一个可选字符串，用于分隔多个名称-默认值：‘,’
-   `typeSeparator` 是一个可选字符串，将类型与名称分开-默认值：‘ ’
-   `descriptionSeparator` 是一个可选字符串，将描述与填充的名称和类型分开-默认值：‘ ’
-   `initialIndent` 是可选的int -选项的缩进量-默认：2
-   `secondaryIndent` 是否一个可选的int -如果完全包装缩进的量（除了初始缩进）-默认：4
-   `maxPadFactor` 是一个可选的数字-影响名称/类型的默认填充级别，它乘以名称/类型长度的平均值-默认：1.5

## 参数格式

在最高级别上有两种类型的参数：命名参数和位置参数。

任何长度的名称参数都以 `--` (如。 `--go`)，一个字符的前缀可以是 `--` 或 `-` (如。 `-g`）.

有两种类型的命名参数：布尔标志(例如； `--problemo`， `-p`)，它不带值，结果是a `true` 如果它们存在，则假的 `undefined` 如果他们不在场，或者 `false` 如果出现并明确地以 `no` (如。 `--no-problemo`）. 带值的命名参数(例如。 `--tseries 800`， `-t 800`)是另一种类型。如果该选项具有类型 `Boolean` 它将自动变成一个布尔标志。任何其他类型都会产生一个带值的命名参数。

有关如何正确设置类型以获得所需值的更多信息，请参阅 [类型检查](https://github.com/gkz/type-check) 和 [levn](https://github.com/gkz/levn) 页面。

您可以对使用单个 `-`但是，除了最后一个之外，其他都必须是布尔标志（不带值）。最后一个可以是布尔标志，也可以是带值的参数。 `-ba 2` 等于 `-b -a 2`。

位置参数是不属于上述范围的所有值-它们可以在任何地方，而不仅仅是在末尾。例如，在 `cmd -b one -a 2 two` 在 `b` 是布尔标志，和 `a` 有类型 `Number`有两个位置参数， `one` 和 `two`。

a之后的所有内容 `--` 是位置参数，即使它看起来像一个命名参数。

您可以选择使用 `=` 将选项名与值分开，例如： `--count=2`。

如果您指定了选项 `NUM`，则使用单个参数的任何参数 `-` 后面跟着一个数字将是有效的，并将设置的值 `NUM`． 如。 `-2` 将被解析为 `NUM: 2`。

如果存在重复的命名参数，则取最后一个。

## 技术对

`optionator` 写在 [LiveScript](http://livescript.net/) -一种编译成JavaScript的语言。它使用 [levn](https://github.com/gkz/levn) 将参数强制转换为其指定类型，并使用 [类型检查](https://github.com/gkz/type-check) 验证值。它还使用 [prelude.ls](http://preludels.com/) 图书馆。

## 常见问题

### optionator 是什么？

选项解析和帮助生成

### 如何安装 optionator？

在项目目录运行 npm install optionator，或使用 pnpm add / yarn add / bun add。

### optionator 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/optionator 是否存在。

### optionator 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### optionator 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 0\.8\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### optionator 可以商用吗？

optionator 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### optionator 的下载量有多少？

根据 npm 官方下载统计，optionator 在 2026/10/06 – 2026/11/04 这 30 天内被下载 591,763,831 次，日均约 19,725,461 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### optionator 还在维护吗？

最新版本 0\.9\.4 发布于 2024/04/27（2 年前）；至今共发布 20 个版本，其中过去 12 个月发布了 0 个；首次发布于 2013/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。