think-plugs-recorder/TEMPLATE_FUNCTIONS_GUIDE.md

# 模板函数使用指南

如果在使用模板函数时提示 `recorder_get_records` 等函数未定义，请按照以下步骤解决：

## 问题原因

模板函数需要在ThinkPHP启动时正确注册到全局作用域，可能因为以下原因导致函数未注册：
1. Composer自动加载未正确更新
2. 插件服务未正确启动
3. 函数文件未被正确加载

## 解决方案

### 方案1: 更新Composer自动加载（推荐）

在项目根目录执行：
```bash
composer dump-autoload
```

这会重新生成自动加载文件，确保 `src/functions.php` 被正确加载。

### 方案2: 手动引入函数文件

#### 在应用启动时引入
在 `app/provider.php` 或 `config/app.php` 中添加：

```php
// 引入操作记录模板函数
$functionsFile = app_path('plugs/think-plugs-recorder/src/functions.php');
if (file_exists($functionsFile)) {
    require_once $functionsFile;
}
```

#### 在模板中临时引入
在需要使用的模板文件顶部添加：

```html
{php}
$functionsFile = app_path('plugs/think-plugs-recorder/src/functions.php');
if (file_exists($functionsFile)) {
    require_once $functionsFile;
}
{/php}

<!-- 现在可以正常使用函数了 -->
{:recorder_render_list(['user_id' => $user_id])}
```

#### 在控制器中引入
在控制器的构造函数或方法中：

```php
<?php
class UserController extends Controller
{
    public function __construct()
    {
        parent::__construct();
        
        // 确保模板函数可用
        $functionsFile = app_path('plugs/think-plugs-recorder/src/functions.php');
        if (file_exists($functionsFile)) {
            require_once $functionsFile;
        }
    }
}
```

### 方案3: 创建应用助手函数

在 `app/common.php` 中添加以下代码：

```php
<?php
/**
 * 应用公共函数文件
 */

// 引入操作记录模板函数
if (!function_exists('recorder_get_records')) {
    $recorderFunctions = app_path('plugs/think-plugs-recorder/src/functions.php');
    if (file_exists($recorderFunctions)) {
        require_once $recorderFunctions;
    }
}
```

### 方案4: 使用类方法替代

如果函数始终无法正确注册，可以直接使用类的静态方法：

```html
<!-- 替代 recorder_get_records() -->
{assign name="records" value=":jerryyan\recorder\helper\ViewHelper::getRecords(['user_id' => $user_id])" /}

<!-- 替代 recorder_render_list() -->
{:jerryyan\recorder\helper\ViewHelper::renderList(['user_id' => $user_id], ['limit' => 10])}

<!-- 替代 recorder_render_timeline() -->
{:jerryyan\recorder\helper\ViewHelper::renderTimeline(['data_type' => 'order', 'data_id' => $order_id])}

<!-- 替代 recorder_render_item() -->
{:jerryyan\recorder\helper\ViewHelper::renderItem($record, ['show_extra' => true])}

<!-- 替代 recorder_get_stats() -->
{assign name="stats" value=":jerryyan\recorder\helper\ViewHelper::getStats()" /}
```

## 测试函数注册

运行测试脚本检查函数是否正确注册：

```bash
php plugs/think-plugs-recorder/test_functions.php
```

## 可用的模板函数

注册成功后，以下函数可在模板中直接使用：

### recorder_get_records()
获取操作记录数据：
```html
{assign name="records" value=":recorder_get_records(['user_id' => $user_id, 'limit' => 5])" /}

{volist name="records" id="record"}
    <div>{$record.operation_type} - {$record.operation_desc}</div>
{/volist}
```

### recorder_render_list()
渲染记录列表：
```html
<!-- 默认样式 -->
{:recorder_render_list(['user_id' => $user_id])}

<!-- 卡片样式 -->
{:recorder_render_list(['data_type' => 'order'], ['theme' => 'card', 'limit' => 10])}

<!-- 紧凑样式 -->
{:recorder_render_list(['user_id' => $user_id], ['compact' => true, 'show_user' => false])}
```

### recorder_render_timeline()
渲染时间线：
```html
{:recorder_render_timeline(['data_type' => 'project', 'data_id' => $project_id])}
```

### recorder_render_item()
渲染单条记录：
```html
{:recorder_render_item($record, ['show_extra' => true])}
```

### recorder_get_stats()
获取统计数据：
```html
{assign name="stats" value=":recorder_get_stats(['start_time' => '2024-01-01'])" /}

<p>总操作次数: {$stats.total_count}</p>
```

## 常见问题

### Q: 提示 "Call to undefined function recorder_get_records()"
A: 函数未正确注册，请按方案1或方案2解决。

### Q: 函数存在但调用时报错
A: 可能是数据库连接问题或权限问题，检查数据库配置和表是否存在。

### Q: 在某些页面可以使用，某些页面不能使用
A: 可能是自动加载时机问题，建议使用方案2在应用启动时全局引入。

### Q: 开发环境正常，生产环境报错
A: 生产环境需要重新执行 `composer dump-autoload --optimize`。

## 最佳实践

1. **推荐使用方案1**: 通过Composer自动加载是最标准的方式
2. **在应用启动时引入**: 确保所有页面都能使用函数
3. **备用方案**: 准备类方法调用作为备用方案
4. **错误处理**: 在模板中使用函数前检查函数是否存在

```html
{if function_exists('recorder_render_list')}
    {:recorder_render_list(['user_id' => $user_id])}
{else}
    {:jerryyan\recorder\helper\ViewHelper::renderList(['user_id' => $user_id])}
{/if}
```