# 后台时间显示优化示例

## 概述

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

## 优化内容

### 1. 优化现有方法

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

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

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

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

### 2. 新增组合时间列

#### columnTimes() 方法
```php
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() 私有方法
```php
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
<?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. 自定义字段名

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

### 3. 组合时间列

```php
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. 混合使用

```php
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. **性能**: 格式化在前端显示时进行，不影响数据库查询

## 测试验证

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

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

## 迁移建议

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

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

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

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