软件简介

This plugin implements compareDocumentPosition in a cross-browser way and
provides some helper functions that allow filtering based on position in the
document’s source order.

Overview

The
compareDocumentPosition
function, part of the DOM standard, compares two nodes and returns a bitmask
identifying which comes first in the document source order. It also identifies
whether one node contains another node and can identify disconnected nodes.

At the time of this writing (August 2008), only Firefox and Opera implement
compareDocumentPosition natively. This plugin provides a way for other
browsers to benefit from the functionality of compareDocumentPosition.

If you just want to test whether one node contains another, you probably want
to write a selector or use the Ancestry
plugin.

Features

• Includes custom code for Firefox, IE, and other browsers to maximize speed. It uses native .compareDocumentPosition() and .contains() when appropriate.
• Handles text and other non-element nodes properly.
• The jQuery.fn.compareDocumentPosition function itself uses no jQuery-specific code, so it should be easy to extract if needed. You’d just need to rename “jQuery.fn.compareDocumentPosition” where it appears.

API

jQuery.fn.compareDocumentPosition

This function accepts exactly two DOM nodes ( not jQuery objects ) as
arguments. Sending anything else will most likely result in a Javascript
error.

This function is not chainable. It returns an integer, not a jQuery
object.

The function returns the relationship of the second node to the first node
using a bitmask:

• 1: Disconnected
• 2: Preceding
• 4: Following
• 8: Contains
• 16: Contained by

It returns 0 if the nodes are identical.

So, given the following document:

<div id="div1"><p id="p1">Hello, world</p><p id="p2"></p></div><p id="p3"></p>

Here are some results:

var div1 = $("#div1").get(0); var p1 = $("#p1").get(0), p2 = $("#p2").get(0), p3 = $("#p3").get(0); $.fn.compareDocumentPosition(div1, p1); //20 (4 + 16) $.fn.compareDocumentPosition(p1, div1); //10 (2 + 8) $.fn.compareDocumentPosition(p1.firstChild, div1); //10 (2 + 8) $.fn.compareDocumentPosition(p1, p2); //4 $.fn.compareDocumentPosition(p3, p1); //2 $.fn.compareDocumentPosition(p1, $("<br/>").get(0)); //1 (or 37 in Firefox); always check the bitmask (& operator) and not the actual return value $.fn.compareDocumentPosition(p1, p1); //0 if ($.fn.compareDocumentPosition(div1, p1) & 16) { /*do something*/ }

Other Functions

The plugin includes five other functions that act as filters for a jQuery node
list. They use the same terminology as the document position constants in
Firefox, which can seem backwards at first because you have to read them right
to left.

These functions are suitable for chaining.

Each function operates on a single node in the chain; if the result of the
preceding operation returns more than one node, then the function will use the
first node in the list as the basis for all comparisons.

Each function accepts a single argument—probably a selector, but it could be
anything that produces a node list.

The name of each function expresses the relationship of the argument to what
is being chained. For example:

$("#p1").cdpContains("div")

This code will return any