如何在Magento 1.x中实现jQuery UI Datepicker禁用特定配送日期的功能？

在Magento 1.x的配送场景中，允许顾客自主选择送达时间是常见需求。很多开发者第一反应是引入jQuery UI的Datepicker，写一个beforeShowDay回调把不允许配送的日期标灰。思路本身没错，但真正落地时会发现禁用日期的判断逻辑远比想象中复杂：后台管理员设置的是服务器时间，浏览器展示的是用户本地时间，Datepicker的星期计算又遵循JavaScript的规则，三者稍有不匹配，就会出现“周一该禁用却没禁、周日不该禁反而被禁”的怪现象。本文结合一个实际的Delivery Date模块改造过程，把禁用特定日期的完整逻辑梳理清楚。

一、beforeShowDay回调的工作机制

jQuery UI Datepicker提供了一个专门的钩子函数beforeShowDay，它会在渲染日历中的每一个日期格子之前被调用，接收一个Date对象作为参数，返回值是一个数组。数组第一个元素是布尔值，决定该日期是否可选；第二个元素是CSS类名，用于给格子附加样式；第三个元素是弹出的提示文字。

很多初学者在这里犯的第一个错误是返回值格式不对。返回false或者只返回一个布尔值是无效的，必须返回数组，例如[false]表示禁用，[true, 'highlight', '可选配送']表示可选并附加高亮样式。下面是一个最基础的配置示例：

jQuery(document).ready(function($) {
    var disabledDates = ['2024-05-01', '2024-05-03', '2024-05-10'];

    $('#delivery_date').datepicker({
        dateFormat: 'yy-mm-dd',
        minDate: 1,
        beforeShowDay: function(date) {
            var dateString = $.datepicker.formatDate('yy-mm-dd', date);
            if (disabledDates.indexOf(dateString) !== -1) {
                return [false, 'ui-state-disabled', '该日期暂停配送'];
            }
            return [true, 'delivery-available'];
        }
    });
});

这段代码的关键在于把Date对象格式化成与后端一致的yy-mm-dd字符串再做比对。如果不做格式化而直接比较Date对象，由于JavaScript中两个Date实例即使值相同也不相等，判断永远不成立。另外注意indexOf在旧版浏览器中的兼容性问题，Magento 1.x面向的客群如果还有IE8用户，建议改用jQuery.inArray()，它是jQuery自己实现的，兼容性更有保障。

二、Magento后台配置如何传递到前端脚本

硬编码禁用日期显然不现实，真正的需求是让管理员在Magento后台System -> Configuration里填写禁用日期，然后由模块读取并输出到页面。Magento 1.x的标准做法是在Block中准备数据，再通过Layout注入到模板。假设你已经在system.xml中定义了配置项，Block里可以这样取值：

class My_Module_Block_Delivery extends Mage_Core_Block_Template
{
    public function getDisabledDates()
    {
        $raw = Mage::getStoreConfig('delivery/general/disabled_dates');
        // 后台以逗号分隔存储，例如 2024-05-01,2024-05-03
        $dates = array_filter(array_map('trim', explode(',', $raw)));
        sort($dates);
        return $dates;
    }

    public function getDisabledWeekdays()
    {
        $raw = (int) Mage::getStoreConfig('delivery/general/disabled_weekdays');
        return $raw; // 二进制位掩码，每一位代表一个星期几
    }
}

位掩码是处理“禁用每周几”这类规则比较优雅的方式。约定星期日用第1位、星期一用第2位，依此类推，那么值5（二进制101）就表示周日和周二不可配送。前端JS拿到掩码后，用(mask >> date.getDay()) & 1即可判断当天是否命中，避免传一长串星期数组。

在模板文件中把数据输出成JSON，注意一定要用json_encode而不是手动拼接字符串，否则日期里混入特殊字符会直接破坏JS语法：

<script type="text/javascript">
var deliveryConfig = <?php echo Mage::helper('core')->jsonEncode(array(
    'disabledDates'    => $this->getDisabledDates(),
    'disabledWeekdays' => $this->getDisabledWeekdays(),
    'minDays'          => (int) Mage::getStoreConfig('delivery/general/min_lead_days'),
)); ?>;
</script>

三、星期计算与时区错位问题

这是整个禁用逻辑中最容易出错的一环。PHP的date('w')返回0到6，其中0代表周日；JavaScript的Date.getDay()同样返回0到6且0代表周日。看起来一致，但如果后端用date('N')（1到7，周一为1）来生成掩码，前端用getDay()去解，错位就发生了：周日的判断会落到周一头上，整个星期规则整体偏移一天。

时区问题则更隐蔽。Magento后台的时间配置基于服务器时区，而$.datepicker.formatDate处理的是浏览器传入的Date对象，本身不涉及时区转换，真正出问题的是你从后端拼接日期字符串的方式。假如PHP端用date('Y-m-d')基于UTC生成“今天”，而服务器在中国但配置了UTC时区，凌晨八点之前生成的日期会比北京时间早一天，导致“至少提前一天下单”的最小可选日期算错。稳妥的做法是在生成动态日期时显式指定时区：

$date = new DateTime('now', new DateTimeZone(Mage::app()->getStore()->getConfig('general/locale/timezone')));
$today = $date->format('Y-m-d');

把店铺配置的时区取出来作为基准，保证无论服务器PHP时区是什么，输出的日期都和店铺展示给顾客的时间一致。

四、组合判断与提前期逻辑

实际业务中，禁用规则往往是多条叠加的：法定节假日禁用、每周固定休息日禁用、提前期不足禁用、超出可预约范围禁用。建议把这些规则封装成一个独立的校验函数，beforeShowDay只负责调用它，逻辑清晰且方便测试：

function isDeliverable(date) {
    var cfg = deliveryConfig;
    var str = $.datepicker.formatDate('yy-mm-dd', date);

    // 规则1：明确禁用的具体日期
    if ($.inArray(str, cfg.disabledDates) !== -1) return false;

    // 规则2：每周固定休息日（位掩码判断）
    if ((cfg.disabledWeekdays >> date.getDay()) & 1) return false;

    // 规则3：提前期不足
    var today = new Date();
    today.setHours(0, 0, 0, 0);
    var lead = (date - today) / 86400000;
    if (lead < cfg.minDays) return false;

    return true;
}

$('#delivery_date').datepicker({
    beforeShowDay: function(date) {
        return isDeliverable(date)
            ? [true, 'delivery-day']
            : [false, 'ui-state-disabled', '该日期不可配送'];
    }
});

注意提前期计算里用setHours(0,0,0,0)把时间部分清零，否则两个时间戳相除会出现小数天，lead < minDays的边界判断就会失真。清零后一天的差值正好是86400000毫秒，判断结果稳定可靠。

五、性能优化与几个易错细节

如果禁用日期来自数据库且数量较大（比如全年物流日历），不要每次渲染日历都发一次AJAX请求。beforeShowDay在每次切换月份时会对当月每天各调用一次，如果回调内部发起网络请求，性能会灾难性地放大。正确做法是页面加载时一次性取回全部规则缓存到变量里，回调只做纯内存计算。

另外还有三个细节值得留意：一是Datepicker默认周日排在最左列，如果店铺主要面向习惯周一开头的用户，可以通过firstDay: 1调整，但这只影响显示，不影响getDay()的返回值；二是Magento 1.x自带的Prototype和jQuery可能共存，务必确认$.noConflict()的处理顺序，避免$被Prototype占用导致脚本静默失败；三是禁用状态只是前端体验，提交后端时仍要在控制器里用PHP重新校验一遍日期合法性，防止用户绕过页面直接构造请求提交了不可配送的日期。

把以上几块逻辑组合起来，一个稳定可用的Delivery Date选择功能就基本成型了。核心原则只有一条：所有日期在生成、传输、比对三个环节必须使用同一格式和同一时区基准，规则判断集中在一个函数里，前后端各校验一次，问题就会少很多。

Magento Datepicker禁用日期jQuery UI修改时间：2026-09-08 10:45:19