1 line
6.8 KiB
JSON
1 line
6.8 KiB
JSON
{"name":"closest","type":"method","title":".closest()","deprecated":null,"removed":null,"desc":"For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.","categories":["traversing/tree-traversal","version/1.3","version/1.4","version/1.6"],"entries":[{"return":"jQuery","signatures":[{"added":"1.3","argument":{"desc":"A string containing a selector expression to match elements against.","name":"selector","type":"Selector"}},{"added":"1.4","argument":[{"desc":"A string containing a selector expression to match elements against.","name":"selector","type":"Selector"},{"desc":"A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.","name":"context","optional":"true","type":"Element"}]},{"added":"1.6","argument":{"desc":"A jQuery object to match elements against.","name":"jQuery object","type":"jQuery"}},{"added":"1.6","argument":{"desc":"An element to match elements against.","name":"element","type":"Element"}}],"examples":[{"desc":"Show how event delegation can be done with closest. The closest list element toggles a yellow background when it or its descendent is clicked.","code":"\n$( document ).on( \"click\", function( event ) {\n $( event.target ).closest( \"li\" ).toggleClass( \"hilight\" );\n});\n","css":"\n li {\n margin: 3px;\n padding: 3px;\n background: #EEEEEE;\n }\n li.hilight {\n background: yellow;\n }\n","html":"\n<ul>\n <li><b>Click me!</b></li>\n <li>You can also <b>Click me!</b></li>\n</ul>\n"},{"desc":"Pass a jQuery object to closest. The closest list element toggles a yellow background when it or its descendent is clicked.","code":"\nvar listElements = $( \"li\" ).css( \"color\", \"blue\" );\n$( document ).on( \"click\", function( event ) {\n $( event.target ).closest( listElements ).toggleClass( \"hilight\" );\n});\n","css":"\n li {\n margin: 3px;\n padding: 3px;\n background: #EEEEEE;\n }\n li.hilight {\n background: yellow;\n }\n","html":"\n<ul>\n <li><b>Click me!</b></li>\n <li>You can also <b>Click me!</b></li>\n</ul>\n"}],"desc":"For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.","longdesc":"\n <p>Given a jQuery object that represents a set of DOM elements, the <code>.closest()</code> method searches through these elements and their ancestors in the DOM tree and constructs a new jQuery object from the matching elements. The <a href=\"/parents/\"><code>.parents()</code></a> and <code>.closest()</code> methods are similar in that they both traverse up the DOM tree. The differences between the two, though subtle, are significant:</p>\n <table>\n <thead>\n <tr>\n <th>\n <code>.closest()</code>\n </th>\n <th>\n <a href=\"/parents/\">\n <code>.parents()</code>\n </a>\n </th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td>Begins with the current element</td>\n <td>Begins with the parent element</td>\n </tr>\n <tr>\n <td>Travels up the DOM tree until it finds a match for the supplied selector</td>\n <td>Travels up the DOM tree to the document's root element, adding each ancestor element to a temporary collection; it then filters that collection based on a selector if one is supplied </td>\n </tr>\n <tr>\n <td>The returned jQuery object contains zero or one element for each element in the original set, in document order</td>\n <td>The returned jQuery object contains zero or more elements for each element in the original set, in reverse document order</td>\n </tr>\n </tbody>\n </table>\n <pre><code>\n<ul id=\"one\" class=\"level-1\">\n <li class=\"item-i\">I</li>\n <li id=\"ii\" class=\"item-ii\">II\n <ul class=\"level-2\">\n <li class=\"item-a\">A</li>\n <li class=\"item-b\">B\n <ul class=\"level-3\">\n <li class=\"item-1\">1</li>\n <li class=\"item-2\">2</li>\n <li class=\"item-3\">3</li>\n </ul>\n </li>\n <li class=\"item-c\">C</li>\n </ul>\n </li>\n <li class=\"item-iii\">III</li>\n</ul>\n </code></pre>\n <p>Suppose we perform a search for <code><ul></code> elements starting at item A:</p>\n <pre><code>\n$( \"li.item-a\" )\n .closest( \"ul\" )\n .css( \"background-color\", \"red\" );\n </code></pre>\n <p>This will change the color of the level-2 <code><ul></code>, since it is the first encountered when traveling up the DOM tree.</p>\n <p>Suppose we search for an <code><li></code> element instead:</p>\n <pre><code>\n$( \"li.item-a\" )\n .closest( \"li\" )\n .css( \"background-color\", \"red\" );\n </code></pre>\n <p>This will change the color of list item A. The <code>.closest()</code> method begins its search <em>with the element itself</em> before progressing up the DOM tree, and stops when item A matches the selector.</p>\n <p>We can pass in a DOM element as the context within which to search for the closest element.</p>\n <pre><code>\nvar listItemII = document.getElementById( \"ii\" );\n$( \"li.item-a\" )\n .closest( \"ul\", listItemII )\n .css( \"background-color\", \"red\" );\n$( \"li.item-a\" )\n .closest( \"#one\", listItemII )\n .css( \"background-color\", \"green\" );\n </code></pre>\n <p>This will change the color of the level-2 <code><ul></code>, because it is both the first <code><ul></code> ancestor of list item A and a descendant of list item II. It will not change the color of the level-1 <code><ul></code>, however, because it is not a descendant of list item II.</p>\n "},{"return":"Array","signatures":{"added":"1.4","argument":[{"desc":"An array or string containing a selector expression to match elements against (can also be a jQuery object).","name":"selectors","type":"Array"},{"desc":"A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.","name":"context","optional":"true","type":"Element"}]},"examples":null,"desc":"Get an array of all the elements and selectors matched against the current element up through the DOM tree.","longdesc":"\n <div class=\"warning\"><strong>This signature (only!) is deprecated as of jQuery 1.7 and <em>removed</em> in jQuery 1.8</strong>. It was primarily meant to be used internally or by plugin authors.</div>\n "}]} |