jQuery Mobile Data 属性
jQuery Data Property
jQuery Mobile uses HTML5 data-* attributes to create a more touch-friendly and attractive appearance for mobile devices.
In the reference list below, the values shown in bold are the default values.
button
Deprecated after version 1.4. Use CSS classes instead. Hyperlinks with data-role="button". Button elements, links in toolbars, and input fields will be automatically rendered into button styles without adding data-role="button".
| Data-properties | value | describe |
|---|---|---|
| data-corners | true | false | Specifies whether the button has rounded corners |
| data-icon | Icon Reference Manual | Specifies the button's icon. There is no icon by default. |
| data-iconpos | left | right | top | bottom | notext | Specifies the location of the icon |
| data-iconshadow | true | false | Specifies whether the button icon has a shadow |
| data-inline | true | false | Specifies whether the button is inline |
| data-mini | true | false | Specifies whether the button is small or regular size |
| data-shadow | true | false | Specifies whether the button has a shadow |
| data-theme | Letters (a-z) | Specifies the theme color for the button |
|
To combine multiple buttons, use a container with data-role="controlgroup" attributes and data-type="horizontal|vertical" to specify whether to combine buttons horizontally or vertically. |
|---|
checkbox
Paired label and input with type="checkbox". They are automatically rendered with button styles, and the data-role is not required.
| Data-properties | value | describe |
|---|---|---|
| data-mini | true | false | Specifies whether the checkbox is small or regular size |
| data-role | none | Prevent jQuery Mobile from rendering checkboxes as buttons |
| data-theme | Letters (a-z) | Specifies the theme color of the checkbox |
|
To group multiple checkboxes, use a container with the data-role="controlgroup" attribute and data-type="horizontal|vertical" to specify whether to group the checkboxes horizontally or vertically. |
|---|
Collapsible blocks
A title element followed by any HTML tag inside a container with data-role="collapsible".
| Data-properties | value | describe |
|---|---|---|
| data-collapsed | true | false | Specifies whether the content is collapsed or expanded |
| data-collapsed-icon | Icon Reference Manual | Specifies the icon for the collapsible button. Default is "plus" |
| data-content-theme | Letters (a-z) | Specifies the theme color for collapsible content. Whether to add rounded corners to collapsible content |
| data-expanded-icon | Icon Reference Manual | Specifies the icon for the collapsible button when the content is expanded.Default is "minus" |
| data-iconpos | left | right | top | bottom | Specifies the location of the icon |
| data-inset | true | false | Specifies whether the collapsible button is rendered with rounded corners and margins |
| data-mini | true | false | Specifies whether the collapsible button is small or regular size |
| data-theme | Letters (a-z) | Specifies the theme color for the collapsible button |
Collapsible collection
A collapsible content block inside a container with data-role="collapsible-set".
| Data-properties | value | describe |
|---|---|---|
| data-collapsed-icon | Icon Reference Manual | Specifies the icon for the collapsible button. Default is "plus" |
| data-content-theme | Letters (a-z) | Specifies the theme color for the collapsible button |
| data-expanded-icon | Icon Reference Manual | Specifies the icon for the collapsible button when the content is expanded.Default is "minus" |
| data-iconpos | left | right | top | bottom | notext | Specifies the location of the icon |
| data-inset | true | false | Specifies whether the collapsible block is rendered with rounded corners and margins |
| data-mini | true | false | Specifies whether the collapsible button is small or regular size |
| data-theme | Letters (a-z) | Specifies the theme color for a collapsible collection |
content
Deprecated in version 1.4 and no longer supported after version 1.5. Containers using data-role="content".
| Data-properties | value | describe |
|---|---|---|
| data-theme | Letters (a-z) | Specifies the theme color for the content. |
control group
A <div> or <fieldset> container with data-role="controlgroup". Combining multiple button-style inputs of a single type (link-based button, radio button, checkbox, select element). For combined form checkboxes and radio buttons, it is recommended to use a <fieldset> container inside a <div> with data-role="fieldcontain" to improve label styling.
| Data-properties | value | describe |
|---|---|---|
| data-mini | true | false | Specifies whether the control group is small or regular size |
| data-type | horizontal | vertical | Specifies whether the control group is displayed horizontally or vertically |
dialog box
A container with data-role="dialog" or a link with data-rel="dialog".
| Data-properties | value | describe |
|---|---|---|
| data-close-btn-text | sometext | Specifies the text of the dialog box close button |
| data-dom-cache | true | false | Specifies whether to clear the jQuery DOM cache for individual pages (if set to true, you must manage the DOM yourself and test on all mobile devices) |
| data-overlay-theme | Letters (a-z) | Specifies the mask (background) color of the dialog page |
| data-theme | Letters (a-z) | Specifies the theme color of the dialog page |
| data-title | sometext | Specifies the title of the dialog page |
Enhance
Containers with data-enhance="false" or data-ajax="false".
| Data-properties | value | describe |
|---|---|---|
| data-enhance | true | false | If set to "true" (default), jQuery Mobile will automatically render the page to make it more suitable for mobile devices. If set to "false", the framework will not render the page |
| data-ajax | true | false | Specifies whether to load the page via ajax |
Note: data-enhance="false" must be used together with $.mobile.ignoreContentEnabled=true" to prevent jQuery Mobile from automatically rendering the page.
When $.mobile.ignoreContentEnabled is set to true, any links or form elements within a data-ajax="false" container will be ignored by the frame's navigation functionality.
domain container
Deprecated after version 1.4 and no longer supported after version 1.5, class="ui-fieldcontain will be used instead". A container wrapped in a label/form element pair with data-role="fieldcontain".
Fixed toolbar
A container with data-role="header" or data-role="footer" and with the data-position="fixed" attribute.
| Data-properties | value | describe |
|---|---|---|
| data-disable-page-zoom | true | false | Specifies whether the user can zoom the page |
| data-fullscreen | true | false | Specifies whether the toolbar is always docked at the top or bottom |
| data-tap-toggle | true | false | Specifies whether the user can change the visibility of the toolbar by clicking on it |
| data-transition | slide | fade | none | Specifies the transition effect when a click occurs |
| data-update-page-padding | true | false | Specifies whether the top and bottom padding of the page is updated when the resize, transition and "updatelayout" events occur (jQuery Mobile always updates the padding when the "pageshow" event occurs) |
| data-visible-on-page-show | true | false | Specifies the visibility of the toolbar when the parent page is displayed |
flip toggle switch
One <select> element with data-role="slider" and two <option> elements.
| Data-properties | value | describe |
|---|---|---|
| data-mini | true | false | Specifies whether the switch is small or regular size |
| data-role | none | Prevent jQuery Mobile from rendering toggle switches as buttons |
| data-theme | Letters (a-z) | Specifies the theme color for the toggle switch |
| data-track-theme | Letters (a-z) | Specifies the theme color of the track |
tail bar
Containers with data-role="footer".
| Data-properties | value | describe |
|---|---|---|
| data-id | sometext | Specifies a unique ID. Required for persistent tailbar |
| data-position | inline | fixed | Specifies whether the footer bar should be inline with the page content or remain fixed at the bottom |
| data-fullscreen | true | false | Specifies whether the footer bar is fixed at the bottom or covers the page content (wider viewing range) |
| data-theme | Letters (a-z) | Specifies the theme color of the footer bar. Default is "a" |
Note: To enable full-screen positioning, please use data-position="fixed", and then add the data-fullscreen attribute to the element.
header bar
Containers with data-role="header".
| Data-properties | value | describe |
|---|---|---|
| data-id | sometext | Specifies a unique ID. Required for persistent header bar |
| data-position | inline | fixed | Specifies whether the header bar should be inline with page content or remain fixed at the top |
| data-fullscreen | true | false | Specifies whether the header bar is fixed at the top or covers the page content (wider viewing range) |
| data-theme | Letters (a-z) | Specifies the theme color of the header bar. Default is "a" |
Note: To enable full-screen positioning, please use data-position="fixed", and then add the data-fullscreen attribute to the element.
Link
All links, including those with data-role="button" and form submit buttons.
| Data-properties | value | describe |
|---|---|---|
| data-ajax | true | false | Specifies whether to load pages via ajax to improve user experience and interaction. If set to false, jQuery Mobile will perform a normal page request. |
| data-direction | reverse | Reverse transition animation (only for pages and dialog boxes) |
| data-dom-cache | true | false | Specifies whether to clear the jQuery DOM cache for individual pages (if set to true, you must manage the DOM yourself and test on all mobile devices) |
| data-prefetch | true | false | Specifies whether to pre-read pages into the DOM so they are available when the user accesses them |
| data-rel | back | dialog | external | popup | Options that specify link behavior. Back - Go back to the previous page in history. Dialog - Opens the link as a dialog box without saving it to history. External - used to link to another domain. Popup - Opens a popup window. |
| data-transition | fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none | Specifies the effect of switching from one page to the next page.Check out our jQuery Mobile Page Switching chapter. |
| data-position-to | origin | jQuery selector | window | Specifies the position of the popup box. Origin - Default. Position the popup on the link that opened it. jQuery selector - Position the pop-up window on the specified element. Window - Positions the popup in the center of the window screen. |
list
<ol> or <ul> with data-role="listview".
| Data-properties | value | describe |
|---|---|---|
| data-autodividers | true | false | Specifies whether to automatically divide list items |
| data-count-theme | Letters (a-z) | Specifies the theme color for counting bubbles. |
| data-divider-theme | Letters (a-z) | Specifies the theme color for list separators. |
| data-filter | true | false | Specifies whether to add a search box to the list |
| data-filter-placeholder | sometext | Deprecated after version 1.4. Use the HTML placeholder attribute instead. Specifies the text in the search box. The default is "Filter items..." |
| data-filter-theme | Letters (a-z) | Specifies the theme color for search filtering. |
| data-icon | Icon Reference Manual | Specify list icon |
| data-inset | true | false | Specifies whether the list is rendered with rounded corners and margins |
| data-split-icon | Icon Reference Manual | Specifies a chart for split buttons. Default is "arrow-r" |
| data-split-theme | Letters (a-z) | Specifies the theme color for the split button. |
| data-theme | Letters (a-z) | Specifies the theme color for the list |
list item
<ol> with data-role="listview" or <li> inside <ul>.
| Data-properties | value | describe |
|---|---|---|
| data-filtertext | sometext | Specifies the text to search for when filtering elements. This text will be filtered instead of the actual list item text |
| data-icon | Icon Reference Manual | Specify list item icon |
| data-role | list-divider | Specify separation of list items |
| data-theme | Letters (a-z) | Specifies the theme color for list items |
Note: The data-icon attribute only works on list items with links.
Navigation Bar
A <li> element inside a container with data-role="navbar".
| Data-properties | value | describe |
|---|---|---|
| data-icon | Icon Reference Manual | Specifies the icon for a list item |
| data-iconpos | left | right | top | bottom | notext | Specifies the location of the icon |
|
Navigation bars inherit the theme sample from their parent container. It is not possible to set the data-theme attribute for the navigation bar. The data-theme attribute can be set individually for each link in the navigation bar. |
|---|
page
Container with data-role="page".
| Data-properties | value | describe |
|---|---|---|
| data-add-back-btn | true | false | Automatically add back button, header bar only |
| data-back-btn-text | sometext | Specifies some text for the back button |
| data-back-btn-theme | Letters (a-z) | Specifies the theme color for the back button |
| data-close-btn-text | Letters (a-z) | Specifies some text for the close button on the dialog box |
| data-dom-cache | true | false | Specifies whether to clear the jQuery DOM cache for individual pages (if set to true, you must manage the DOM yourself and test on all mobile devices) |
| data-overlay-theme | Letters (a-z) | Specifies the mask (background) color of the dialog page |
| data-theme | Letters (a-z) | Specifies the theme color of the page. |
| data-title | sometext | Specify page title |
| data-url | url | Update the value of URL other than the URL used to request the page |
Pop-ups
Containers with data-role="popup".
| Data-properties | value | describe |
|---|---|---|
| data-corners | true | false | Specifies whether the pop-up window has rounded corners |
| data-overlay-theme | Letters (a-z) | Specifies the mask (background) color of the popup box. Default is transparent background (none) |
| data-shadow | true | false | Specifies whether the pop-up box has a shadow |
| data-theme | Letters (a-z) | Specifies the theme color of the popup box. The default is inherited, "none" sets the pop-up window to be transparent |
| data-tolerance | 30, 15, 30, 15 | Specifies the distance between the window edges (top, right, bottom, left) |
Anchor with data-rel="popup":
| Data-properties | value | describe |
|---|---|---|
| data-position-to | origin | jQuery selector | window | >Specifies the position of the pop-up box. Origin - Default. Position the popup on the link that opened it. jQuery selector - Position the pop-up window on the specified element. Window - Positions the popup in the center of the window screen. |
| data-rel | popup | Used to open a popup box |
| data-transition | fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none | Specifies the effect of switching from one page to the next page. Check out our jQuery Mobile Page Switching chapter. |
single button
Paired label and input with type="radio". They are automatically rendered with button styles, and the data-role is not required.
| Data-properties | value | describe |
|---|---|---|
| data-mini | true | false | Specifies whether the button is small or regular size |
| data-role | none | Prevent jQuery Mobile from rendering a radio button styled as an enhanced state button so that the element is displayed in its native HTML state |
| data-theme | Letters (a-z) | Specifies the theme color for radio buttons |
|
|
To group multiple radio buttons, use a container with the data-role="controlgroup" attribute and data-type="horizontal|vertical" to specify whether the radio buttons should be grouped horizontally or vertically. |
|---|
choose
All <select> elements. These will be automatically rendered as button styles, the date-role is not required.
| Data-properties | value | describe |
|---|---|---|
| data-icon | Icon Reference Manual | Specifies the icon for the select element.Default is "arrow-d" |
| data-iconpos | left | right | top | bottom | notext | Specifies the location of the icon |
| data-inline | true | false | Specifies whether the select element is inline |
| data-mini | true | false | Specifies whether the select element is small or regular size |
| data-native-menu | true | false | When set to false, it uses the custom selection menu that comes with jQuery (recommended if you want the selection menu to appear the same on all mobile devices) |
| data-overlay-theme | Letters (a-z) | Specifies the theme color of the custom selection menu that comes with jQuery (used with data-native-menu="false") |
| data-placeholder | true | false | Can be set on the <option> element of a non-native selection menu |
| data-role | none | Prevent jQuery Mobile from rendering select elements into button styles |
| data-theme | Letters (a-z) | Specifies the theme color of the select element |
|
|
To combine multiple select elements, use a container with data-role="controlgroup" attributes and data-type="horizontal|vertical" to specify whether to combine select elements horizontally or vertically. |
|---|
slider
Input box with type="range". These will be automatically rendered as button styles, the date-role is not required.
| Data-properties | value | describe |
|---|---|---|
| data-highlight | true | false | Specifies whether the sliding track is highlighted |
| data-mini | true | false | Specifies whether the slider is small or regular size |
| data-role | none | Prevent jQuery Mobile from rendering the slider control as a button style |
| data-theme | Letters (a-z) | Specifies the theme color for slider controls (input boxes, handles, and tracks) |
| data-track-theme | Letters (a-z) | Specifies the theme color for the slider track |
Text input box & text input field
An input or textarea element with type="text|search|etc.". These will be automatically rendered as button styles, the date-role is not required.
| Data-properties | value | describe |
|---|---|---|
| data-mini | true | false | Specifies whether the input box is small or regular size |
| data-role | none | Prevent jQuery Mobile from rendering input boxes/fields into button styles |
| data-theme | Letters (a-z) | Specifies the theme color for the input field |
