kknongchang_2506/docs/GridHelper-columnDateTime使用示例.md

GridHelper columnDateTime 使用示例

概述

在UCore的GridHelper类中新增了columnDateTime方法，用于统一格式化后台列表中的时间显示为"年-月-日 时:分:秒"格式。

方法签名

public function columnDateTime($field, $label = ''): Grid\Column

功能特性

• 统一格式: 将时间统一格式化为 Y-m-d H:i:s 格式（如：2023-12-25 14:30:45）
• 多类型支持: 支持时间戳、Carbon实例、DateTime对象、字符串等多种时间格式
• 空值处理: 空值显示为 -
• 自动排序: 自动添加sortable()功能
• 错误容错: 字符串转换失败时返回原值

支持的输入类型

1. 时间戳 (int): 1640995200 → 2022-01-01 08:00:00
2. Carbon实例: Carbon::parse('2023-06-15 14:30:45') → 2023-06-15 14:30:45
3. DateTime对象: new DateTime('2023-12-25 23:59:59') → 2023-12-25 23:59:59
4. 字符串: '2023-07-20 10:15:30' → 2023-07-20 10:15:30
5. 空值: null 或 '' → -
6. 零值: 0 → 1970-01-01 08:00:00 (有效时间戳)

使用示例

基本用法

<?php

namespace App\Module\Example\AdminControllers;

use UCore\DcatAdmin\AdminController;

class ExampleController extends AdminController
{
    protected function grid()
    {
        $grid = $this->gridMake();
        $helper = $this->gridHelper($grid);
        
        // 使用新的columnDateTime方法
        $helper->columnDateTime('created_at', '创建时间');
        $helper->columnDateTime('updated_at', '更新时间');
        $helper->columnDateTime('login_time', '登录时间');
        
        return $grid;
    }
}

与其他列组合使用

protected function grid()
{
    $grid = $this->gridMake();
    $helper = $this->gridHelper($grid);
    
    // ID列
    $helper->columnId();
    
    // 用户信息
    $grid->column('username', '用户名');
    $grid->column('email', '邮箱');
    
    // 时间列 - 使用统一格式
    $helper->columnDateTime('created_at', '注册时间');
    $helper->columnDateTime('last_login_at', '最后登录');
    $helper->columnDateTime('email_verified_at', '邮箱验证时间');
    
    // 状态列
    $helper->columnStatus('status', '状态');
    
    return $grid;
}

在模块中的应用

// 在Fund模块中
$helper->columnDateTime('trade_time', '交易时间');
$helper->columnDateTime('created_at', '创建时间');

// 在User模块中  
$helper->columnDateTime('register_time', '注册时间');
$helper->columnDateTime('last_active_time', '最后活跃');

// 在Game模块中
$helper->columnDateTime('game_start_time', '游戏开始时间');
$helper->columnDateTime('game_end_time', '游戏结束时间');

与现有方法的对比

旧方法

// 使用原有的columnCreatedAt和columnUpdatedAt
$helper->columnCreatedAt(); // 格式可能不统一
$helper->columnUpdatedAt(); // 格式可能不统一

// 或者手动处理
$grid->column('created_at', '创建时间')->display(function ($value) {
    return $value ? date('Y-m-d H:i:s', strtotime($value)) : '-';
});

新方法

// 使用新的columnDateTime方法 - 统一格式，更简洁
$helper->columnDateTime('created_at', '创建时间');
$helper->columnDateTime('updated_at', '更新时间');

优势

1. 代码简洁: 一行代码完成时间格式化
2. 格式统一: 所有时间字段使用相同的显示格式
3. 类型安全: 自动处理多种时间类型
4. 错误处理: 内置错误容错机制
5. 功能完整: 自动添加排序功能

注意事项

1. 时间戳会根据服务器时区进行转换
2. 空值（null或空字符串）会显示为 -
3. 数字0被视为有效时间戳（1970-01-01 08:00:00）
4. 字符串转换失败时会返回原始值
5. 自动添加sortable()功能，支持列排序

测试验证

项目中包含了完整的单元测试 tests/Unit/UCore/GridHelperDateTimeTest.php，验证了各种输入类型的正确处理。

运行测试：

vendor/bin/phpunit tests/Unit/UCore/GridHelperDateTimeTest.php