如何解释可选JavaScript参数的文档

Question

从文档中addEventListener我看到以下模式:

target.addEventListener(type, listener[, useCapture]);

现在我明白这useCapture是一个可选参数.为什么[然后在逗号(,)之前启动,而不是在参数后面的逗号后面listener？[]除了useCapture可选的事实之外,实际建议的封闭对是什么？我还在jQuery文档中看到了类似的文档模式,例如on ()方法文档.

.on( events [, selector ] [, data ], handler(eventObject) )

Answer 1

方括号意味着它们内部的东西是可选的 - 要么你拥有它,要么你没有.它是列出有效调用表单的简明方法.

基本的例子

target.addEventListener(type,listener [,useCapture]);

有两种有效形式:

target.addEventListener(type, listener            ); // without
target.addEventListener(type, listener, useCapture); // with

如果逗号在方括号之外,则表示两种形式

target.addEventListener(type, listener,           ); // without (syntax error)
target.addEventListener(type, listener, useCapture); // with

jQuery示例

.on(events [,selector] [,data],handler);

这个有点棘手.选择器和数据是可选的,因此有四种有效形式:

.on( events                , handler ); // without both
.on( events          , data, handler ); // without selector, with data
.on( events, selector      , handler ); // with selector, without data
.on( events, selector, data, handler ); // with both

问题是第二种和第三种形式都有三个参数,因此参数的解释方式并不明显.似乎jQuery根据中间参数的类型决定:如果它是一个字符串,则选择第三种形式; 否则选择第二种形式.

所以以下将"hi"作为选择器而没有作为数据参数:

.on( events          , "hi", handler ); // "hi" is the selector (!)

要强制jQuery "hi"用作数据参数,null必须为选择器指定:

.on( events, null    , "hi", handler ); // "hi" is the data argument

这明确地是第四种形式,并且文档说null选择器被视为省略的选择器.

嵌套示例

在文档中,您经常会看到嵌套的方括号.以下是Unix命令文档中的简化示例man:

男人[--warnings [= type]]页面

这意味着以下表格有效:

man                   javac    # without outer
man --warnings        javac    # with outer (without inner)
man --warnings=number javac    # with outer (with inner)

但以下内容无效:

man           =number javac    # is this with or without outer?