think-plugs-recorder/TEMPLATE_FUNCTIONS_GUIDE.md

模板函数使用指南

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

问题原因

模板函数需要在ThinkPHP启动时正确注册到全局作用域，可能因为以下原因导致函数未注册：

1. Composer自动加载未正确更新
2. 插件服务未正确启动
3. 函数文件未被正确加载

解决方案

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

在项目根目录执行：

composer dump-autoload

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

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

在应用启动时引入

在 app/provider.php 或 config/app.php 中添加：

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

在模板中临时引入

在需要使用的模板文件顶部添加：

{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
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
/**
 * 应用公共函数文件
 */

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

方案4: 使用类方法替代

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

<!-- 替代 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()" /}

测试函数注册

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

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

可用的模板函数

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

recorder_get_records()

获取操作记录数据：

{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()

渲染记录列表：

<!-- 默认样式 -->
{: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()

渲染时间线：

{:recorder_render_timeline(['data_type' => 'project', 'data_id' => $project_id])}

recorder_render_item()

渲染单条记录：

{:recorder_render_item($record, ['show_extra' => true])}

recorder_get_stats()

获取统计数据：

{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. 错误处理: 在模板中使用函数前检查函数是否存在

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