jQuery-Timepicker-Addon 时间选择器插件使用教程

概述

jQuery-Timepicker-Addon 是一个功能强大的时间选择器插件，它为 jQuery UI 的日期选择器(Datepicker)添加了时间选择功能。本教程将详细介绍该插件的各种使用方法和配置选项。

基础初始化

简单日期时间选择器

最基本的初始化方式是为输入框添加日期和时间选择功能：

$('#basic_example_1').datetimepicker();

仅时间选择器

如果只需要时间选择功能，可以使用 timepicker() 方法：

$('#basic_example_2').timepicker();

时间格式设置

可以通过 timeFormat 选项自定义时间显示格式：

$('#basic_example_3').datetimepicker({
    timeFormat: "hh:mm tt"  // 12小时制，带AM/PM
});

本地化支持

插件内置了多语言支持，可以轻松实现本地化：

$('#basic_example_4').timepicker(
    $.timepicker.regional['es']  // 使用西班牙语配置
);

时区功能

基本时区使用

在时间格式中添加 'z' 可以显示时区：

$('#timezone_example_1').datetimepicker({
    timeFormat: 'hh:mm tt z'
});

自定义时区选项

可以自定义可选的时区列表：

$('#timezone_example_2').datetimepicker({
    timeFormat: 'HH:mm z',
    timezoneList: [ 
        { value: -300, label: 'Eastern'}, 
        { value: -360, label: 'Central' },
        { value: -420, label: 'Mountain' },
        { value: -480, label: 'Pacific' } 
    ]
});

滑块控件定制

添加网格线

可以为小时和分钟滑块添加网格线：

$('#slider_example_1').timepicker({
    hourGrid: 4,        // 小时滑块每4小时一个网格
    minuteGrid: 10,     // 分钟滑块每10分钟一个网格
    timeFormat: 'hh:mm tt'
});

设置滑块步长

可以自定义滑块的变化步长：

$('#slider_example_2').datetimepicker({
    timeFormat: 'HH:mm:ss',
    stepHour: 2,        // 小时步长为2
    stepMinute: 10,     // 分钟步长为10
    stepSecond: 10      // 秒钟步长为10
});

触摸设备支持

添加 sliderAccess 插件以支持触摸设备：

$('#slider_example_3').datetimepicker({
    addSliderAccess: true,
    sliderAccessArgs: { touchonly: false }
});

使用下拉菜单替代滑块

可以使用下拉菜单代替滑块：

$('#slider_example_4').datetimepicker({
    controlType: 'select',  // 使用下拉菜单
    timeFormat: 'hh:mm tt'
});

单行下拉菜单

将下拉菜单显示为单行：

$('#slider_example_4andHalf').datetimepicker({
    controlType: 'select',
    oneLine: true,       // 单行显示
    timeFormat: 'hh:mm tt'
});

辅助字段功能

基本辅助字段

可以将选择的日期时间同步到另一个输入框：

$('#alt_example_1').datetimepicker({
    altField: "#alt_example_1_alt"  // 辅助字段ID
});

自定义辅助字段格式

可以自定义辅助字段的显示格式：

$('#alt_example_3').datetimepicker({
    altField: "#alt_example_3_alt",
    altFieldTimeOnly: false,
    altFormat: "yy-mm-dd",     // 日期格式
    altTimeFormat: "h:m t",    // 时间格式
    altSeparator: " @ "        // 日期时间分隔符
});

时间输入功能

允许直接输入时间

启用时间输入框，允许用户直接输入时间：

$('#input_example_1').datetimepicker({
    timeInput: true,        // 启用时间输入
    timeFormat: "hh:mm tt"
});

仅显示时间输入框

隐藏滑块，只显示时间输入框：

$('#input_example_2').datetimepicker({
    timeInput: true,
    timeFormat: "hh:mm tt",
    showHour: false,       // 隐藏小时滑块
    showMinute: false      // 隐藏分钟滑块
});

时间限制功能

设置小时范围

限制可选择的小时范围：

$('#rest_example_1').timepicker({
    hourMin: 8,    // 最早8点
    hourMax: 16    // 最晚16点
});

设置日期范围

限制可选择的日期范围：

$('#rest_example_2').datetimepicker({
    numberOfMonths: 2,  // 显示2个月
    minDate: 0,        // 最早今天
    maxDate: 30        // 最晚30天后
});

使用Date对象设置范围

使用Date对象精确设置日期时间范围：

$('#rest_example_3').datetimepicker({
    minDate: new Date(2010, 11, 20, 8, 30),  // 2010年12月20日8:30
    maxDate: new Date(2010, 11, 31, 17, 30)  // 2010年12月31日17:30
});

时间范围选择

关联开始和结束时间

创建关联的开始和结束时间选择器：

var startDateTextBox = $('#range_example_1_start');
var endDateTextBox = $('#range_example_1_end');

startDateTextBox.datetimepicker({ 
    timeFormat: 'HH:mm z',
    onClose: function(dateText, inst) {
        // 确保结束时间不小于开始时间
        if (endDateTextBox.val() != '') {
            var testStartDate = startDateTextBox.datetimepicker('getDate');
            var testEndDate = endDateTextBox.datetimepicker('getDate');
            if (testStartDate > testEndDate)
                endDateTextBox.datetimepicker('setDate', testStartDate);
        }
    },
    onSelect: function (selectedDateTime){
        // 设置结束时间的最小值为开始时间
        endDateTextBox.datetimepicker('option', 'minDate', 
            startDateTextBox.datetimepicker('getDate'));
    }
});

endDateTextBox.datetimepicker({ 
    timeFormat: 'HH:mm z',
    onClose: function(dateText, inst) {
        // 确保开始时间不大于结束时间
        if (startDateTextBox.val() != '') {
            var testStartDate = startDateTextBox.datetimepicker('getDate');
            var testEndDate = endDateTextBox.datetimepicker('getDate');
            if (testStartDate > testEndDate)
                startDateTextBox.datetimepicker('setDate', testEndDate);
        }
    },
    onSelect: function (selectedDateTime){
        // 设置开始时间的最大值为结束时间
        startDateTextBox.datetimepicker('option', 'maxDate', 
            endDateTextBox.datetimepicker('getDate'));
    }
});

使用内置范围方法

插件提供了简化范围选择的方法：

$.timepicker.datetimeRange(
    startDateTextBox,
    endDateTextBox,
    {
        minInterval: (1000*60*60), // 最小间隔1小时
        dateFormat: 'dd M yy', 
        timeFormat: 'HH:mm',
        start: {}, // 开始时间选择器选项
        end: {}    // 结束时间选择器选项
    }
);

实用工具方法

获取和设置日期时间

// 设置日期时间
$('#utility_example_1_setdt').click(function(){
    ex13.datetimepicker('setDate', (new Date()));
});

// 获取日期时间
$('#utility_example_1_getdt').click(function(){
    alert(ex13.datetimepicker('getDate'));
});

时间格式化工具

$.datepicker.formatTime('HH:mm z', 
    { hour: 14, minute: 36, timezone: '+2000' }, 
    {}
);

时间解析工具

$.datepicker.parseTime('HH:mm:ss:l z', "14:36:21:765 +2000", {})

总结

jQuery-Timepicker-Addon 提供了丰富的功能和灵活的配置选项，可以满足各种日期时间选择的需求。通过本教程的学习，您应该能够掌握该插件的基本用法和高级功能，为您的Web应用添加专业的时间选择功能。