1 line
7.1 KiB
JSON
1 line
7.1 KiB
JSON
{"name":"jQuery.cssHooks","type":"property","title":"jQuery.cssHooks","deprecated":null,"removed":null,"desc":"Hook directly into jQuery to override how particular CSS properties are retrieved or set, normalize CSS property naming, or create custom properties.","categories":["css","version/1.4.3"],"entries":[{"return":"Object","signatures":{"added":"1.4.3"},"examples":null,"longdesc":"\n <p>The <code>$.cssHooks</code> object provides a way to define functions for getting and setting particular CSS values. It can also be used to create new cssHooks for normalizing CSS3 features such as box shadows and gradients. </p>\n <p>For example, some versions of Webkit-based browsers require <code>-webkit-border-radius</code> to set the <code>border-radius</code> on an element, while earlier Firefox versions require <code>-moz-border-radius</code>. A css hook can normalize these vendor-prefixed properties to let <code>.css()</code> accept a single, standard property name (<code>border-radius</code>, or with DOM property syntax, <code>borderRadius</code>).</p>\n <p>In addition to providing fine-grained control over how specific style properties are handled, <code>$.cssHooks</code> also extends the set of properties available to the <code>.animate()</code> method.</p>\n <p>Defining a new css hook is straight-forward. The skeleton template below can serve as a guide to creating your own. </p>\n <pre><code>\n(function( $ ) {\n\n// First, check to see if cssHooks are supported\nif ( !$.cssHooks ) {\n // If not, output an error message\n throw( new Error( \"jQuery 1.4.3 or above is required for this plugin to work\" ) );\n}\n\n// Wrap in a document ready call, because jQuery writes\n// cssHooks at this time and will blow away your functions\n// if they exist.\n$(function () {\n $.cssHooks[ \"someCSSProp\" ] = {\n get: function( elem, computed, extra ) {\n // Handle getting the CSS property\n },\n set: function( elem, value ) {\n // Handle setting the CSS value\n }\n };\n});\n\n})( jQuery );\n </code></pre>\n <h4 id=\"feature-testing\">Feature Testing</h4>\n <p>Before normalizing a vendor-specific CSS property, first determine whether the browser supports the standard property or a vendor-prefixed variation. For example, to check for support of the <code>border-radius</code> property, see if any variation is a member of a temporary element's <code>style</code> object.</p>\n <pre><code>\n(function( $ ) {\n\nfunction styleSupport( prop ) {\n var vendorProp, supportedProp,\n\n // Capitalize first character of the prop to test vendor prefix\n capProp = prop.charAt( 0 ).toUpperCase() + prop.slice( 1 ),\n prefixes = [ \"Moz\", \"Webkit\", \"O\", \"ms\" ],\n div = document.createElement( \"div\" );\n\n if ( prop in div.style ) {\n\n // Browser supports standard CSS property name\n supportedProp = prop;\n } else {\n\n // Otherwise test support for vendor-prefixed property names\n for ( var i = 0; i < prefixes.length; i++ ) {\n vendorProp = prefixes[ i ] + capProp;\n if ( vendorProp in div.style ) {\n supportedProp = vendorProp;\n break;\n }\n }\n }\n\n // Avoid memory leak in IE\n div = null;\n\n // Add property to $.support so it can be accessed elsewhere\n $.support[ prop ] = supportedProp;\n return supportedProp;\n}\n\n// Call the function, e.g. testing for \"border-radius\" support:\nstyleSupport( \"borderRadius\" );\n\n})( jQuery );\n </code></pre>\n <h4 id=\"defining-complete-csshook\">Defining a complete css hook</h4>\n <p>To define a complete css hook, combine the support test with a filled-out version of the skeleton template provided in the first example:</p>\n <pre><code>\n(function( $ ) {\n\nif ( !$.cssHooks ) {\n throw( new Error( \"jQuery 1.4.3+ is needed for this plugin to work\" ) );\n}\n\nfunction styleSupport( prop ) {\n var vendorProp, supportedProp,\n capProp = prop.charAt( 0 ).toUpperCase() + prop.slice( 1 ),\n prefixes = [ \"Moz\", \"Webkit\", \"O\", \"ms\" ],\n div = document.createElement( \"div\" );\n\n if ( prop in div.style ) {\n supportedProp = prop;\n } else {\n for ( var i = 0; i < prefixes.length; i++ ) {\n vendorProp = prefixes[ i ] + capProp;\n if ( vendorProp in div.style ) {\n supportedProp = vendorProp;\n break;\n }\n }\n }\n\n div = null;\n $.support[ prop ] = supportedProp;\n return supportedProp;\n}\n\nvar borderRadius = styleSupport( \"borderRadius\" );\n\n// Set cssHooks only for browsers that support a vendor-prefixed border radius\nif ( borderRadius && borderRadius !== \"borderRadius\" ) {\n $.cssHooks.borderRadius = {\n get: function( elem, computed, extra ) {\n return $.css( elem, borderRadius );\n },\n set: function( elem, value) {\n elem.style[ borderRadius ] = value;\n }\n };\n}\n\n})( jQuery );\n </code></pre>\n <p>You can then set the border radius in a supported browser using either the DOM (camelCased) style or the CSS (hyphenated) style:</p>\n <pre><code>\n$( \"#element\" ).css( \"borderRadius\", \"10px\" );\n$( \"#another\" ).css( \"border-radius\", \"20px\" );\n </code></pre>\n <p>If the browser lacks support for any form of the CSS property, vendor-prefixed or not, the style is not applied to the element. However, if the browser supports a proprietary alternative, it can be applied to the cssHooks instead. </p>\n <pre><code>\n(function( $ ) {\n\n// Feature test for support of a CSS property\n// and a proprietary alternative\n// ...\nif ( $.support.someCSSProp && $.support.someCSSProp !== \"someCSSProp\" ) {\n\n // Set cssHooks for browsers that\n // support only a vendor-prefixed someCSSProp\n $.cssHooks.someCSSProp = {\n get: function( elem, computed, extra ) {\n return $.css( elem, $.support.someCSSProp );\n },\n set: function( elem, value) {\n elem.style[ $.support.someCSSProp ] = value;\n }\n };\n} else if ( supportsProprietaryAlternative ) {\n $.cssHooks.someCSSProp = {\n get: function( elem, computed, extra ) {\n // Handle crazy conversion from the proprietary alternative\n },\n set: function( elem, value ) {\n // Handle crazy conversion to the proprietary alternative\n }\n }\n}\n\n})( jQuery );\n </code></pre>\n <h4 id=\"special-units\">Special units</h4>\n <p>By default, jQuery adds a \"px\" unit to the values passed to the <code>.css()</code> method. This behavior can be prevented by adding the property to the <code>jQuery.cssNumber</code> object</p>\n <pre><code>\n$.cssNumber.someCSSProp = true;\n </code></pre>\n <h4 id=\"animating\">Animating with cssHooks</h4>\n <p>A css hook can also hook into jQuery's animation mechanism by adding a property to the <code>jQuery.fx.step</code> object:</p>\n <pre><code>\n$.fx.step.someCSSProp = function( fx ) {\n $.cssHooks.someCSSProp.set( fx.elem, fx.now + fx.unit );\n};\n </code></pre>\n <p>Note that this works best for simple numeric-value animations. More custom code may be required depending on the CSS property, the type of value it returns, and the animation's complexity.</p>\n "}]} |