compareDocumentPosition

compareDocumentPosition
 点击下载

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 <div>s that contain the “#p1” element. It can be counterintuitive, but it matches the DOM spec.

Here are the functions:

  • cdpContains
  • cdpIsContained
  • cdpPreceding
  • cdpFollowing
  • cdpDisconnected

Given the same document as above, here are some results:

$("#p1").cdpContains("div"); //#div1
$("#div1").cdpIsContained("p"); //[#p1, #p2]; it would be easier to use $("#div1 p"), however
$("#p1").cdpPreceding("p"); //nothing
$("#p1").cdpFollowing("p"); //[#p2, #p3]; they don’t have to be siblings

Supported Browsers

Tested in Firefox 3, IE7, and Safari 3.1. It should work in other browsers, however.

Credits

Other people wrote all the hard bits; a special thanks to John Resig and Dean Edwards, whose code this plugin incorporates.

 

转载请注明:代码家园 » compareDocumentPosition

评论列表(网友评论仅供网友表达个人看法,并不表明本站同意其观点或证实其描述)