1 line
12 KiB
JSON
1 line
12 KiB
JSON
{"name":"attr","type":"method","title":".attr()","deprecated":null,"removed":null,"desc":"Get the value of an attribute for the first element in the set of matched elements or set one or more attributes for every matched element.","categories":["attributes","manipulation/general-attributes","version/1.0","version/1.1","version/1.6"],"entries":[{"return":"String","signatures":{"added":"1.0","argument":{"desc":"The name of the attribute to get.","name":"attributeName","type":"String"}},"examples":[{"desc":"Display the checked attribute and property of a checkbox as it changes.","code":"\n$( \"input\" )\n .change(function() {\n var $input = $( this );\n $( \"p\" ).html( \".attr( 'checked' ): <b>\" + $input.attr( \"checked\" ) + \"</b><br>\" +\n \".prop( 'checked' ): <b>\" + $input.prop( \"checked\" ) + \"</b><br>\" +\n \".is( ':checked' ): <b>\" + $input.is( \":checked\" ) + \"</b>\" );\n })\n .change();\n","css":"\n p {\n margin: 20px 0 0;\n }\n b {\n color: blue;\n }\n","html":"\n<input id=\"check1\" type=\"checkbox\" checked=\"checked\">\n<label for=\"check1\">Check me</label>\n<p></p>\n"},{"desc":"Find the title attribute of the first <em> in the page.","code":"\nvar title = $( \"em\" ).attr( \"title\" );\n$( \"div\" ).text( title );\n","css":"\n em {\n color: blue;\n font-weight: bold;\n }\n div {\n color: red;\n }\n","html":"\n<p>Once there was a <em title=\"huge, gigantic\">large</em> dinosaur...</p>\n\nThe title of the emphasis is:<div></div>\n"}],"desc":"Get the value of an attribute for the first element in the set of matched elements.","longdesc":"\n <p>The <code>.attr()</code> method gets the attribute value for only the <em>first</em> element in the matched set. To get the value for each element individually, use a looping construct such as jQuery's <code>.each()</code> or <code>.map()</code> method.</p>\n <p>Using jQuery's <code>.attr()</code> method to get the value of an element's attribute has two main benefits:</p>\n <ol>\n <li><strong>Convenience</strong>: It can be called directly on a jQuery object and chained to other jQuery methods.</li>\n <li><strong>Cross-browser consistency</strong>: The values of some attributes are reported inconsistently across browsers, and even across versions of a single browser. The <code>.attr()</code> method reduces such inconsistencies.</li>\n </ol>\n <div class=\"warning\">\n <p><strong>Note:</strong> Attribute values are strings with the exception of a few attributes such as value and tabindex.</p>\n </div>\n <div class=\"warning\">\n <p><strong>Note:</strong> Attempting to change the <code>type</code> attribute (or property) of an <code>input</code> element created via HTML or already in an HTML document will result in an error being thrown by Internet Explorer 6, 7, or 8.</p>\n </div>\n <p>As of jQuery 1.6, the <code>.attr()</code> method returns <code>undefined</code> for attributes that have not been set. <strong>To retrieve and change DOM properties such as the <code>checked</code>, <code>selected</code>, or <code>disabled</code> state of form elements, use the <a href=\"/prop/\">.prop()</a> method.</strong></p>\n\n <h4>Attributes vs. Properties</h4>\n <p>The difference between <em>attributes</em> and <em>properties</em> can be important in specific situations. <strong>Before jQuery 1.6</strong>, the <code>.attr()</code> method sometimes took property values into account when retrieving some attributes, which could cause inconsistent behavior. <strong>As of jQuery 1.6</strong>, the <code>.prop()</code> method provides a way to explicitly retrieve property values, while <code>.attr()</code> retrieves attributes.</p>\n <p>For example, <code>selectedIndex</code>, <code>tagName</code>, <code>nodeName</code>, <code>nodeType</code>, <code>ownerDocument</code>, <code>defaultChecked</code>, and <code>defaultSelected</code> should be retrieved and set with the <code><a href=\"/prop/\">.prop()</a></code> method. Prior to jQuery 1.6, these properties were retrievable with the <code>.attr()</code> method, but this was not within the scope of <code>attr</code>. These do not have corresponding attributes and are only properties.</p>\n <p>Concerning boolean attributes, consider a DOM element defined by the HTML markup <code><input type=\"checkbox\" checked=\"checked\" /></code>, and assume it is in a JavaScript variable named <code>elem</code>:</p>\n <table>\n <tr>\n <th>\n <code>elem.checked</code>\n </th>\n <td><code>true</code> (Boolean) Will change with checkbox state</td>\n </tr>\n <tr>\n <th>\n <code>$( elem ).prop( \"checked\" )</code>\n </th>\n <td><code>true</code> (Boolean) Will change with checkbox state</td>\n </tr>\n <tr>\n <th>\n <code>elem.getAttribute( \"checked\" )</code>\n </th>\n <td><code>\"checked\"</code> (String) Initial state of the checkbox; does not change</td>\n </tr>\n <tr>\n <th>\n <code>$( elem ).attr( \"checked\" )</code>\n <em>(1.6)</em>\n </th>\n <td><code>\"checked\"</code> (String) Initial state of the checkbox; does not change</td>\n </tr>\n <tr>\n <th>\n <code>$( elem ).attr( \"checked\" )</code>\n <em>(1.6.1+)</em>\n </th>\n <td><code>\"checked\"</code> (String) Will change with checkbox state</td>\n </tr>\n <tr>\n <th>\n <code>$( elem ).attr( \"checked\" )</code>\n <em>(pre-1.6)</em>\n </th>\n <td><code>true</code> (Boolean) Changed with checkbox state</td>\n </tr>\n </table>\n <br/>\n <p>According to the <a href=\"http://www.w3.org/TR/html401/interact/forms.html#h-17.4\">W3C forms specification</a>, the <code>checked</code> attribute is a <em><a href=\"http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.3.4.2\">boolean attribute</a></em>, which means the corresponding property is <strong>true</strong> if the attribute is present at all—even if, for example, the attribute has no value or is set to empty string value or even \"false\". This is true of all boolean attributes.</p>\n <p>Nevertheless, the most important concept to remember about the <code>checked</code> attribute is that it does not correspond to the <code>checked</code> property. The attribute actually corresponds to the <code>defaultChecked</code> property and should be used only to set the <em>initial</em> value of the checkbox. The <code>checked</code> attribute value does not change with the state of the checkbox, while the <code>checked</code> property does. Therefore, the cross-browser-compatible way to determine if a checkbox is checked is to use the property:</p>\n <ul>\n <li>\n <code>if ( elem.checked )</code>\n </li>\n <li>\n <code>if ( $( elem ).prop( \"checked\" ) )</code>\n </li>\n <li>\n <code>if ( $( elem ).is( \":checked\" ) )</code>\n </li>\n </ul>\n <p>The same is true for other dynamic attributes, such as <code>selected</code> and <code>value</code>.</p>\n "},{"return":"jQuery","signatures":[{"added":"1.0","argument":[{"desc":"The name of the attribute to set.","name":"attributeName","type":"String"},{"type":[{"name":"String"},{"name":"Number"}],"desc":"A value to set for the attribute.","name":"value"}]},{"added":"1.0","argument":{"desc":"An object of attribute-value pairs to set.","name":"attributes","type":"PlainObject"}},{"added":"1.1","argument":[{"desc":"The name of the attribute to set.","name":"attributeName","type":"String"},{"desc":"A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old attribute value as arguments.","name":"function(index, attr)","type":"Function"}]}],"examples":[{"desc":"Set some attributes for all <img>s in the page.","code":"\n$( \"img\" ).attr({\n src: \"/resources/hat.gif\",\n title: \"jQuery\",\n alt: \"jQuery Logo\"\n});\n$( \"div\" ).text( $( \"img\" ).attr( \"alt\" ) );\n","css":"\n img {\n padding: 10px;\n }\n div {\n color: red;\n font-size: 24px;\n }\n","html":"\n<img>\n<img>\n<img>\n\n<div><b>Attribute of Ajax</b></div>\n"},{"desc":"Set the id for divs based on the position in the page.","code":"\n$( \"div\" )\n .attr( \"id\", function( arr ) {\n return \"div-id\" + arr;\n })\n .each(function() {\n $( \"span\", this ).html( \"(id = '<b>\" + this.id + \"</b>')\" );\n});\n","css":"\n div {\n color: blue;\n }\n span {\n color: red;\n }\n b {\n font-weight: bolder;\n }\n","html":"\n<div>Zero-th <span></span></div>\n<div>First <span></span></div>\n<div>Second <span></span></div>\n"},{"desc":"Set the src attribute from title attribute on the image.","code":"\n$( \"img\" ).attr( \"src\", function() {\n return \"/resources/\" + this.title;\n});\n","html":"\n<img title=\"hat.gif\">\n"}],"desc":"Set one or more attributes for the set of matched elements.","longdesc":"\n <p>The <code>.attr()</code> method is a convenient way to set the value of attributes—especially when setting multiple attributes or using values returned by a function. Consider the following image:</p>\n <pre><code><img id=\"greatphoto\" src=\"brush-seller.jpg\" alt=\"brush seller\"></code></pre>\n <h4 id=\"setting-simple-attr\">Setting a simple attribute</h4>\n <p>To change the <code>alt</code> attribute, simply pass the name of the attribute and its new value to the <code>.attr()</code> method:</p>\n <pre><code>\n$( \"#greatphoto\" ).attr( \"alt\", \"Beijing Brush Seller\" );\n </code></pre>\n <p><em>Add</em> an attribute the same way:</p>\n <pre><code>\n$( \"#greatphoto\" ).attr( \"title\", \"Photo by Kelly Clark\" );\n </code></pre>\n <h4 id=\"setting-several-attrs\">Setting several attributes at once</h4>\n <p>To change the <code>alt</code> attribute and add the <code>title</code> attribute at the same time, pass both sets of names and values into the method at once using a plain JavaScript object. Each key-value pair in the object adds or modifies an attribute:</p>\n <pre><code>\n$( \"#greatphoto\" ).attr({\n alt: \"Beijing Brush Seller\",\n title: \"photo by Kelly Clark\"\n});\n </code></pre>\n <p>When setting multiple attributes, the quotes around attribute names are optional.</p>\n <p><strong>WARNING</strong>: When setting the 'class' attribute, you must always use quotes!</p>\n <p><strong>Note</strong>: jQuery prohibits changing the <code>type</code> attribute on an <code><input></code> or <code><button></code> element and will throw an error in all browsers. This is because the <code>type</code> attribute cannot be changed in Internet Explorer.</p>\n <h4 id=\"computed-attr-values\">Computed attribute values</h4>\n <p>By using a function to set attributes, you can compute the value based on other properties of the element. For example, to concatenate a new value with an existing value:</p>\n <pre><code>\n$( \"#greatphoto\" ).attr( \"title\", function( i, val ) {\n return val + \" - photo by Kelly Clark\";\n});\n </code></pre>\n <p>This use of a function to compute attribute values can be particularly useful when modifying the attributes of multiple elements at once.</p>\n <p><strong>Note: </strong>If nothing is returned in the setter function (ie. <code>function(index, attr){})</code>, or if <code>undefined</code> is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.</p>\n "}]} |