kknongchang_2506/docs/后台时间显示优化示例.md

后台时间显示优化示例

概述

优化了UCore GridHelper中的创建时间/修改时间展示，统一使用"年-月-日 时:分:秒"格式，并新增了组合时间列功能。

优化内容

1. 优化现有方法

columnCreatedAt() 方法优化

// 优化前
public function columnCreatedAt()
{
    return $this->grid->column('created_at', '创建时间')->sortable();
}

// 优化后
public function columnCreatedAt($field = 'created_at', $label = '创建时间')
{
    return $this->columnDateTime($field, $label);
}

columnUpdatedAt() 方法优化

// 优化前
public function columnUpdatedAt()
{
    return $this->grid->column('updated_at', '更新时间')->sortable();
}

// 优化后
public function columnUpdatedAt($field = 'updated_at', $label = '更新时间')
{
    return $this->columnDateTime($field, $label);
}

2. 新增组合时间列

columnTimes() 方法

public function columnTimes($createdAtField = 'created_at', $updatedAtField = 'updated_at', $label = '时间信息')
{
    return $this->grid->column($createdAtField, $label)->display(function ($createdAt) use ($updatedAtField) {
        $updatedAt = $this->{$updatedAtField} ?? '';
        
        // 格式化创建时间
        $createdAtFormatted = $this->formatDateTime($createdAt);
        $createdAtHtml = "<div><small class='text-muted'>创建:</small> {$createdAtFormatted}</div>";
        
        // 格式化更新时间
        $updatedAtHtml = '';
        if ($updatedAt) {
            $updatedAtFormatted = $this->formatDateTime($updatedAt);
            $updatedAtHtml = "<div><small class='text-muted'>更新:</small> {$updatedAtFormatted}</div>";
        }
        
        return $createdAtHtml . $updatedAtHtml;
    })->sortable();
}

3. 统一格式化方法

formatDateTime() 私有方法

private function formatDateTime($value)
{
    // 检查空值（但不包括0，因为0是有效的时间戳）
    if (is_null($value) || $value === '') {
        return '-';
    }
    
    // 如果是时间戳，转换为日期时间字符串
    if (is_numeric($value)) {
        return date('Y-m-d H:i:s', $value);
    }
    
    // 如果是Carbon实例或DateTime对象
    if ($value instanceof \Carbon\Carbon || $value instanceof \DateTime) {
        return $value->format('Y-m-d H:i:s');
    }
    
    // 如果是字符串，尝试转换为标准格式
    if (is_string($value)) {
        try {
            $date = new \DateTime($value);
            return $date->format('Y-m-d H:i:s');
        } catch (\Exception $e) {
            return $value; // 如果转换失败，返回原值
        }
    }
    
    return $value;
}

使用示例

1. 基本用法（向后兼容）

<?php

namespace App\Module\Example\AdminControllers;

use UCore\DcatAdmin\AdminController;

class ExampleController extends AdminController
{
    protected function grid()
    {
        $grid = $this->gridMake();
        $helper = $this->gridHelper($grid);
        
        // 现有代码无需修改，自动使用新的格式化
        $helper->columnCreatedAt();  // 自动格式化为 Y-m-d H:i:s
        $helper->columnUpdatedAt();  // 自动格式化为 Y-m-d H:i:s
        
        return $grid;
    }
}

2. 自定义字段名

protected function grid()
{
    $grid = $this->gridMake();
    $helper = $this->gridHelper($grid);
    
    // 使用自定义字段名和标签
    $helper->columnCreatedAt('register_time', '注册时间');
    $helper->columnUpdatedAt('last_login_time', '最后登录');
    
    return $grid;
}

3. 组合时间列

protected function grid()
{
    $grid = $this->gridMake();
    $helper = $this->gridHelper($grid);
    
    // 基本ID列
    $helper->columnId();
    
    // 业务字段
    $grid->column('username', '用户名');
    $grid->column('email', '邮箱');
    
    // 使用组合时间列，节省空间
    $helper->columnTimes(); // 默认使用 created_at 和 updated_at
    
    // 或者自定义字段
    $helper->columnTimes('start_time', 'end_time', '活动时间');
    
    return $grid;
}

4. 混合使用

protected function grid()
{
    $grid = $this->gridMake();
    $helper = $this->gridHelper($grid);
    
    $helper->columnId();
    $grid->column('title', '标题');
    
    // 重要的时间字段单独显示
    $helper->columnCreatedAt();
    
    // 其他时间字段组合显示
    $helper->columnTimes('published_at', 'expired_at', '发布时间');
    
    return $grid;
}

显示效果

1. 单独时间列

创建时间: 2023-12-25 14:30:45
更新时间: 2023-12-26 09:15:30

2. 组合时间列

时间信息:
创建: 2023-12-25 14:30:45
更新: 2023-12-26 09:15:30

优势

1. 向后兼容

• 现有代码无需修改
• 自动应用新的格式化规则

2. 统一格式

• 所有时间字段使用相同的 Y-m-d H:i:s 格式
• 消除了格式不一致的问题

3. 灵活性

• 支持自定义字段名和标签
• 提供组合显示选项

4. 空间优化

• 组合时间列可以节省列表空间
• 适合字段较多的管理页面

5. 代码复用

• 统一的格式化逻辑
• 减少重复代码

注意事项

1. 时区处理: 时间戳会根据服务器时区进行转换
2. 空值显示: null或空字符串显示为 -
3. 排序功能: 所有时间列都自动支持排序
4. 错误处理: 格式转换失败时返回原始值
5. 性能: 格式化在前端显示时进行，不影响数据库查询

测试验证

项目中包含了完整的单元测试，验证了优化后方法的正确性：

vendor/bin/phpunit tests/Unit/UCore/GridHelperDateTimeTest.php
# OK (2 tests, 13 assertions)

迁移建议

立即生效

现有使用 columnCreatedAt() 和 columnUpdatedAt() 的代码会自动使用新的格式化，无需修改。

推荐优化

对于字段较多的列表页面，建议使用 columnTimes() 组合显示来节省空间：

// 推荐：使用组合时间列
$helper->columnTimes();

// 而不是：
$helper->columnCreatedAt();
$helper->columnUpdatedAt();