javascript pipe() 和 then() 文档与 jQuery 1.8 中的现实

pipe() and then() documentation vs reality in jQuery 1.8

提问by Adam Terlson

Update: This question is now out of date as the documentation is accurate and up to date.

更新：这个问题现在已经过时了，因为文档是准确和最新的。

I've been exploring the jQuery Deferred/Promise API for a bit and I'm very confused about the differences between pipe()and then()philosophically and in the jQuery documentation. I've found that pipe() is just an alias for then() as of jQuery 1.8.

我一直在探索 jQuery Deferred/Promise API，但我对 jQuery 文档pipe()和then()哲学上的差异感到非常困惑。我发现 pipe() 只是 jQuery 1.8 中 then() 的别名。

From jQuery source:

来自 jQuery 源代码：

// Keep pipe for back-compat
promise.pipe = promise.then;

Yet the documentation is completely different for pipe()and then()as they supposedly have entirely different uses.

然而，文档完全不同pipe()，then()因为它们据称具有完全不同的用途。

Description for then():

说明then()：

Description: Add handlers to be called when the Deferred object is resolved or rejected.

说明：添加要在解析或拒绝 Deferred 对象时调用的处理程序。

Description for pipe():

说明pipe()：

Description: Utility method to filter and/or chain Deferreds.

描述：过滤和/或链接延迟的实用方法。

I understand that historically they had slightly different behavior, but in the entirety of the documentation for pipeor the documentation for then, it doesn't even say that these two functions do the exact same thing now.

我知道从历史上看，它们的行为略有不同，但在整个pipe文档或then 文档中，它甚至没有说这两个函数现在做完全相同的事情。

So, here's my two part question:

所以，这是我的两部分问题：

1. Why does the documentation between pipe()and then()differ as of jQuery 1.8?
2. Why does then()return a newdeferred object? This behavior is completely undocumented (the docs just say it returns a Deferred, not that it's a new one). I understand that it has utility in doing so (namely to implement all of pipe()'s features), but philosophically why is it the case? It's unnecessary given the description of then()(to attach handlers).

1. 为什么jQuery 1.8pipe()和then()jQuery 1.8之间的文档有所不同？
2. 为什么会then()返回一个新的延迟对象？这种行为完全没有记录（文档只是说它返回一个延迟，而不是它是一个新的）。我知道它这样做具有实用性（即实现 的所有pipe()功能），但从哲学上讲，为什么会这样？鉴于then()（附加处理程序）的描述，这是不必要的。

Update

更新

I'll even go so far as to say the then()docs are misleading and inaccurate:

我什至会说这些then()文档具有误导性和不准确：

Since deferred.then returns the deferred object, other methods of the deferred object can be chained to this one, including additional .then() methods.

由于 deferred.then返回延迟对象，因此延迟对象的其他方法可以链接到这个方法，包括附加的 .then() 方法。

Maybe it's just vague, but it implies it returns the deferred object you called then()on for chaining, when in reality it returns an entirely new object....

也许它只是含糊不清，但它暗示它返回您调用的延迟对象then()进行链接，而实际上它返回一个全新的对象......

Update Again

再次更新

Seems the documentation is simply wrong/out of date! So that answers why the documentation makes no mention of them being the same thing. However, my second question still stands. Is the reason then()returns a newdeferred simply so that it and pipe()can be made equivalent?

似乎文档完全错误/过时了！所以这就回答了为什么文档没有提到它们是同一回事。但是，我的第二个问题仍然成立。原因是否只是简单地then()返回一个新的deferred 以便它和pipe()可以等效？

采纳答案by Frédéric Hamidi

The documentation update for jQuery 1.8 is not online yet.

jQuery 1.8 的文档更新尚未上线。

According to this recent blog post:

根据最近的这篇博客文章：

We're in the process of updating the API documentation for all the changes to 1.8, but for now you can refer back to the changelog in the jQuery 1.8 announcementto see what's changed.

我们正在为 1.8 的所有更改更新 API 文档，但现在您可以参考jQuery 1.8 公告中的更改日志 以查看更改的内容。

Update:Yes, then()returns a new Deferredbecause it is equivalent to pipe()now. I'm pretty confident the documentation update will clarify this soon.

更新：是的，then()返回一个 newDeferred因为它相当于pipe()now。我非常有信心文档更新将很快澄清这一点。

Further update for completeness:The documentation was recently updated and now says for pipe():

完整性的进一步更新：最近更新了文档，现在说pipe()：

Deprecation Notice:As of jQuery 1.8, the deferred.pipe()method is deprecated. The deferred.then()method, which replaces it, should be used instead.

弃用通知：从 jQuery 1.8 开始，该deferred.pipe()方法已弃用。deferred.then()应该使用替代它的方法。

And for then():

对于then()：

Prior to jQuery 1.8, the arguments could be a function or an array of functions.

[...]

As of jQuery 1.8, the deferred.then()method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated deferred.pipe()method. The doneFilterand failFilterfunctions filter the original deferred's resolved / rejected status and values. The progressFilterfunction filters any calls to the original deferred's notifyor notifyWithmethods. These filter functions can return a new value to be passed along to the promise's .done()or .fail()callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the promise's callbacks. If the filter function used is null, or not specified, the promise will be resolved or rejected with the same values as the original.

在 jQuery 1.8 之前，参数可以是函数或函数数组。

[...]

从 jQuery 1.8 开始，该deferred.then()方法返回一个新的 promise，它可以通过函数过滤延迟的状态和值，替换现在已弃用的deferred.pipe()方法。该 doneFilter和failFilter功能过滤原始推迟的解决/拒绝的状态和值。该progressFilter函数过滤对原始延迟notify或notifyWith方法的任何调用。这些过滤器函数可以返回一个新值传递给Promise.done()或.fail()回调，或者它们可以返回另一个可观察对象（Deferred、Promise 等），该对象将其已解决/拒绝的状态和值传递给 Promise 的回调。如果使用的过滤函数是null，或未指定，promise 将使用与原始值相同的值来解决或拒绝。