jQuery Mobile 移动开发中的日期插件Mobiscroll 2.3 使用说明
/******************HTML***********************/
<input id="demo" />
<button id="clear">Clear</button>
<button id="show">Show</button>
/*****************Javascript**********************/
$(function(){
$('#demo').mobiscroll().date({
theme: 'default',
lang: 'zh',
display: 'bottom',
mode: 'scroller',
invalid: [ 'w0', 'w6', '5/1', '12/24', '12/25' ]
});
$('#show').click(function(){
$('#demo').mobiscroll('show');
return false;
});
$('#clear').click(function () {
$('#demo').val('');
return false;
});
});
/***************初始化控件选项*******************/
//初始化日期控件
var opt = {
preset: 'date', //日期
theme: 'jqm', //皮肤样式
display: 'modal', //显示方式
mode: 'clickpick', //日期选择模式
dateFormat: 'yy-mm-dd', // 日期格式
setText: '确定', //确认按钮名称
cancelText: '取消',//取消按钮名籍我
dateOrder: 'yymmdd', //面板中日期排列格式
dayText: '日', monthText: '月', yearText: '年', //面板中年月日文字
endYear:2020 //结束年份
};
$('input:jqmData(role="datebox")').mobiscroll(opt);
/***************************************************************/
Mobiscroll Core Documentation
These are the core functions, options, events and methods that are available, if they are not overriden by a preset implementation.
Utility functions
| Name | Parameters | Description |
|---|---|---|
| setDefaults | function(settings) | Set settings for all scroller instances |
Localization
| Name | Type | Default value | Description |
|---|---|---|---|
| cancelText | String | 'Cancel' | Text for Cancel button. |
| clearText | String | 'Clear' | Text for Clear button. |
| setText | String | 'Set' | Text for Set button. |
| headerText | Mixed | '{value}' | Specifies a custom string which appears in the popup header. If the string contains '{value}' substring, it is replaced with the formatted value of the scroller. If it's set to false, the header is hidden. If a function is passed, it receives the formatted value as parameter and the returned value appears in the header |
| lang | String | 'en-US' | Language of the scroller. Based on the language string the scroller loads the language based default settings from the language modules. Supported languages:
|
Options
| Name | Type | Default value | Description |
|---|---|---|---|
| anchor | jQuery Object | undefined | Specifies the anchor element for positioning, if display is set to 'bubble'. If undefined, it defaults to the element on which the scroller was called. |
| animate | String | undefined | Animation to use for show/hide (if display is not inline). Possible values:
|
| buttons | Array | ['set', 'cancel'] | Buttons to display. Predefined buttons are: 'set', 'clear', 'cancel'. Custom buttons can also be specified: buttons: [ 'set', { text: 'Custom', handler: function (event, inst) { alert('Custom button clicked!'); } } 'cancel'] |
| closeOnOverlay | Boolean | true | If true, scroller is closed on overlay tap/click. |
| context | String | 'body' | Context in which mobiscroll is appended and positioned (if not inline). Can be a jQuery selector string or a jQuery object. |
| delay | Integer | 300 | Specifies the speed in milliseconds to change values in clickpick mode with tap & hold |
| disabled | Boolean | false | Disables (true) or enables (false) the scroller. Can be set when initialising the scroller |
| display | String | 'modal' | Controls the positioning of the scroller. Possible options:
|
| fixedWidth | Number or Array | undefined | Width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel sepparately. |
| height | Number | 40 | Height in pixels of one row on the wheel |
| maxWidth | Number or Array | undefined | Maximum width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel sepparately. |
| minWidth | Number or Array | undefined | Minimum width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel sepparately. |
| mode | String | 'scroller' | Option to choose between modes. Possible modes: 'scroller' - standard behaviour, 'clickpick' - '+' and '-' buttons |
| preset | String | '' | Load preset configurations. It is possible to write custom presets. |
| scrollLock | Boolean | true | Disables page scrolling on touchmove (if not in inline mode) At the time of 2.1-beta on Android 2.3 fast touchmoves sometimes causes pagescroll which may cause that the scroller gets out of the viewport. |
| readonly | Boolean or Array of Booleans | false | If true, the scroller is displayed, but wheels are not moveable. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - disables the first wheel. |
| rows | Number | 3 | Number of visible rows on the wheel |
| showLabel | Boolean | true | Show/hide labels above wheels |
| showOnFocus | Boolean | true | Pops up the scroller on input focus |
| showOnTap | Boolean | true | Pops up the scroller on element tap |
| tap | Boolean | true | Fire button actions on tap instead of click (on touch devices) |
| theme | String | '' | Sets the scroller's visual appearance. Supplied themes:
|
| wheels | Object | [] | Wheels configuration. If keys array is omitted, the values array is used for keys as well. Starting from 2.6.0 a new format was introduced for passing the wheels. The old format is still supported but it is considered deprecated and will be removed in the future. Below is an example with 2 wheel groups, each containing 2 wheels. wheels: [ // Wheel groups array [ // First wheel group { // Wheel object label: 'Label 1', keys: [1, 2, 3], values: ['x', 'y', 'z'], }, { // Wheel object label: 'Label 2', keys: [1, 2], values: ['a', 'b'], } ], [ // Second wheel group { // Wheel object label: 'Label 3', values: [1, 2], }, { // Wheel object label: 'Label 4', values: [4, 5], } ]] |
| width | Number | 80 | Minimum width in pixels of the wheels, expand to fit values and labels |
Theme options
| Name | Type | Default value | Description |
|---|---|---|---|
| jQuery Mobile Theme | |||
| jqmBorder | String | 'a' | Swatch for picker border. |
| jqmBody | String | 'c' | Swatch for picker body. |
| jqmHeader | String | 'b' | Swatch for picker header. |
| jqmWheel | String | 'd' | Swatch for wheel background (clickpick mode only). |
| jqmClickPick | String | 'c' | Swatch for clickpick buttons. |
| jqmSet | String | 'b' | Swatch for set button. |
| jqmCancel | String | 'c' | Swatch for cancel button. |
| Windows Phone Theme | |||
| accent | String | 'none' | Specifies the accent color of the theme. Possible values: 'lime', 'green', 'emerald', 'teal', 'cyan', 'cobalt', 'indigo', 'violet', 'pink', 'magenta', 'crimson', 'red', 'orange', 'amber', 'yellow', 'brown', 'olive', 'steel', 'mauve', 'sienna'. |
Setting options runtime
There are two ways to modify options after initalization
- Using the option method.
The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).
// Modify one option$('#scroller').mobiscroll('option', 'mode', 'clickpick');// Modify multiple options$('#scroller').mobiscroll('option', { mode: 'clickpick', rows: 5 });
- Modify directly the
inst.settingsobject.
Useful when changing dynamic settings, which do not need redraw (e.g. readonly, calendar marked days).
// Get instrance and modify a settingvar inst = $('#scroller').mobiscroll('getInst');inst.settings.readonly = true;// Modify settings in an event$('#scroller').mobiscroll({ onBeforeShow: function (inst) { inst.settings.readonly = true; }});
Conversion functions
| Name | Parameters | Description |
|---|---|---|
| formatResult | function(data) | Receives selected scroller values as an array and must return a string to set as the value of the input element. By default it concatenates the values to a string, or, if a preset is selected, formats the date/time according to dateFormat/timeFormat option |
| parseValue | function(valueText) | Receives a string as parameter and must return an array which represents the selected scroller values. |
Events
| Name | Parameters | Description |
|---|---|---|
| onBeforeShow | function(inst) | Gets called before the scroller appears. It is usefull if you want to modify the settings object before generating the markup (e.g. change the wheel values). The function receives the scroller instance as parameters |
| onCancel | function(valueText, inst) | Allows you to define your own event when cancel is pressed. The function receives the selected value as text and the scroller instance as parameters |
| onChange | function(valueText, inst) | Allows you to define your own event when a wheel value is changed. The function receives the selected value as text and the scroller instance as parameters |
| onClose | function(valueText, btn, inst) | Allows you to define your own event when the scroller is closed. The function receives the selected value as text, the button, which triggered the scroller to close ('set', or 'cancel') and the scroller instance as parameters. If returns false, close is prevented. |
| onDestroy | function(inst) | Gets called when the mobiscroll instance is destroyed. The function receives the scroller instance as parameter. |
| onMarkupReady | function(html, inst) | Allows you to define your own event when the html markup of the scroller is generated, but it is not yet shown. It is usefull, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs. The function receives the jQuery object containing the generated html and the scroller instance as parameters. If returns false, close is prevented. |
| onPosition | function(html, inst) | Gets called when the scroller is positioned (on initial show and resize / orientation change). The function receives the jQuery object containing the generated html and the scroller instance as parameters |
| onSelect | function(valueText, inst) | Allows you to define your own event when a scroller value is set. The function receives the selected value as text and the scroller instance as parameters |
| onShow | function(html, valueText, inst) | Gets called when the scroller appears. The function receives the jQuery object containing the generated html, the formatted value and the scroller instance as parameters |
| onValueTap | function(item, inst) | Gets called when the user taps on a value on the wheel. The function receives the jQuery object containing the html of the tapped item and the scroller instance as parameters |
| validate | function(html, index, inst) | Gets called on initialization and on every wheel change, can be used to validate the selected values. Has 3 parameters: html - jQuery object containing the generated html, index - index of the changed wheel (undefined on initial call), inst - mobiscroll instance |
Methods
| Name | Parameters | Description |
|---|---|---|
| cancel | .mobiscroll('cancel') | Hides the scroller and also invokes the onCancel event. |
| changeWheel | .mobiscroll('changeWheel', indexes, time) | Regenerates the wheel with the given indexes based on the option. Usefull if you want to change a wheel dinamically based on another wheel's currently selected value. The time parameter specifies the animation time to scroll the new wheel to the selected value. |
| destroy | .mobiscroll('destroy') | Remove the scroller functionality completely. This will return the element back to its pre-init state. |
| disable | .mobiscroll('disable') | Disables the scroller. |
| enable | .mobiscroll('enable') | Enables the scroller. |
| getInst | .mobiscroll('getInst') | Returns the object instance. |
| getValue | .mobiscroll('getValue') | Returns the selected scroller values as an array. |
| getValues | .mobiscroll('getValues') | Returns the list of selected values if multiple selection is implemented in the preset. |
| hide | .mobiscroll('hide', prevAnim, btn) | Hides the scroller. If prevAnim is true, hide will not be animated. The optional btn parameter specifies which button caused the scroller to hide, and it's passed to the onClose event. |
| init | .mobiscroll('init', settings) | Initializes the scroller. Gets called when creating a new scroller instance, or updating the options of an existing scroller instance with the settings parameter. |
| isVisible | .mobiscroll('isVisible') | Returns a boolean indicating whether the scroller is visible or not. |
| option | .mobiscroll('option', optionName, value) or .mobiscroll('option', options) | Set scroller options |
| position | .mobiscroll('position', check) | Recalculates scroller position (if not inline). If check is true, the function checks if window size changed after last position call, if false or ommitted, position is recalculated anyway. |
| select | .mobiscroll('select') | Hides the scroller and also invokes the onSelect event. |
| setValue | .mobiscroll('setValue', values, fill, time, temp) | Sets the scroller values from the values parameter passed as array. If the fill parameter is true, the associated input field is also updated with the new value. The time parameter specifies the duration of the animation in seconds to scroll the wheels to the new values. There is no animation, if time is omitted or 0. If temp is true, only temporary values are set. |
| show | .mobiscroll('show', prevAnim) | Shows the scroller. If prevAnim is true, show will not be animated. |
| tap | .mobiscroll('tap', el, handler) | Attaches the handler function to the tap event of element el. If the action was initiated with touch event, handler is called on touchend, otherwise on click. |
| trigger | .mobiscroll('trigger', name, params) | Calls the name event with params (Array) as parameters, if it is defined in preset, theme or user settings. The instance is always added to the end of the parameter list. |
