如何解释可选JavaScript参数的文档 [英] How to interpret documentation for optional JavaScript parameters

问题描述

来自 addEventListener的文档 我看到以下模式：

From the documentation for addEventListener I see the following pattern:

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

现在我明白 useCapture 是可选的参数。为什么 [然后在逗号（，）之前开始，而不是在逗号位于侦听器参数之后？除了 useCapture 之外， [] 的封闭对是什么？我在jQuery文档中也看到了类似的文档模式，例如： on（）方法文档。

Now I understand that useCapture is an optional parameter. Why does the [ then start before the comma (,) and not immediately after the comma that follows the listener parameter? What does the enclosing pair of [] actually suggest apart from the fact that useCapture is optional? I have also seen similar documentation patterns in jQuery documentation, e.g. the on () method documentation.

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

推荐答案

方括号表示其中的内容是可选的–要么你拥有它，要么你没有。这是列出有效调用表单的简明方法。

Square brackets mean the thing inside them is optional – either you have it or you don't. It is a concise way of listing the valid invocation forms.

目标。 addEventListener（type，listener [，useCapture]）;

有两种有效形式：

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

如果逗号在方括号之外，则两个表格将是

If the comma was outside the square brackets the two forms would be

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

jQuery示例

.on（events [，selector] [，data]，handler）;

这个有点棘手。选择器和数据是可选的，因此有四种有效形式：

This one is a bit tricky. The selector and data are optional so there are four valid forms:

.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根据中间参数的类型决定：如果它是一个字符串，则选择第三种形式;否则选择第二种形式。

The problem is that the second and third forms both have three parameters, so it's not obvious how the arguments will be interpreted. It appears that jQuery decides based on the type of the middle argument: if it's a string the third form is chosen; otherwise the second form is chosen.

所以以下将选择hi作为选择器而不是data参数：

So the following will have "hi" as the selector and nothing as the data argument:

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

强制jQuery使用hi作为数据参数，必须为选择器提供 null ：

To force jQuery to use "hi" as the data argument, null must be given for the selector:

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

这是明确的第四种形式，文档说的是a null 选择器被视为省略的选择器。

This is unambiguously the fourth form, and the docs say that a null selector is treated the same an omitted selector.

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

In documentation you'll often see nested square brackets. Here is a simplified example from the documentation for the Unix command man:

man [--warnings [= type]] page

这意味着以下表单有效：

This means the following forms are valid:

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?

这篇关于如何解释可选JavaScript参数的文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！