跳至主要内容
版本：5.1

在模块、插件和模板中使用 com_ajax

本节演示如何通过使用 com_ajax 在模块、插件和模板中使用 Ajax。由于您不能直接向模块/插件/模板发送 HTTP 请求，因此必须使用 com_ajax 作为代理，它将根据 Ajax HTTP 请求中的参数将控制权传递给您的扩展。

提示

您也可以以与 Ajax 调用无关的方式使用 com_ajax，以支持为 临时作业 定义 URL。

模块​

要将 Ajax 调用传递给模块，您需要在 Ajax HTTP 请求的 URL 中设置

  • option - com_ajax
  • module - 您模块的名称，不含 "mod_" 前缀。
  • method - 当添加 "Ajax" 作为后缀时，这是要调用的模块的辅助方法的名称
  • format - 预期响应的格式 - “json” 或 “raw”

要调用的方法必须是模块的辅助类的公共实例函数，辅助类必须命名为 <Modulename>Helper，并且必须根据 Joomla 辅助类的模式进行命名空间。

您的辅助函数只返回所需数据；com_ajax 将使用 JsonResponse 提供 JSON 或原始格式输出，具体取决于 HTTP 请求中的 format 参数。

如果您选择 format=raw，则辅助方法返回的任何内容都将直接回显到输出中。

模块示例​

您可以在 模块教程第 9 步 Ajax 中找到一个示例。

在本示例中

  • 模块名为 mod_hello
  • 辅助文件中的方法为 countAjax()
  • 请求的格式为 json。

因此，URL 必须采用以下形式

index.php?option=com_ajax&module=hello&method=count&format=json

插件​

这是通过 com_ajax 触发名为 OnAjax<Methodname> 的事件来实现的，您的插件必须侦听该事件。

要将 Ajax 调用传递给插件，您需要在 Ajax HTTP 请求的 URL 中设置

  • option - com_ajax
  • plugin - 当添加 "OnAjax" 作为前缀时，这是要分派的事件的名称
  • format - 预期响应的格式 - “json” 或 “raw”

您的插件应属于 "ajax" 插件组，因此在您插件的清单文件中

<extension method="upgrade" type="plugin" group="ajax">

您的插件应将结果添加到事件的 "result" 参数中，com_ajax 将使用 JsonResponse 提供 JSON 或原始格式输出，具体取决于 HTTP 请求中的 format 参数。

您的插件可以引发异常，这将被 com_ajax 捕获并视为失败，异常文本将在 Ajax 响应中传递。

插件示例​

例如，您可以轻松修改 com_ajaxdemo 的 Ajax 文档部分的代码。

在 media/js/divide.js 中，只需更改以下行

 let url = vars.root + 'index.php?option=com_ajaxdemo&format=json&task=ajax.divide';

为

 let url = vars.root + 'index.php?option=com_ajax&plugin=divide&format=json',

这将把 Ajax HTTP 请求路由到 com_ajax，com_ajax 将导入 "ajax" 插件组，并触发 "OnAjaxDivide" 事件。

您可以下载 plg_ajaxdemo，然后安装并启用此插件。此插件以类似于 com_ajaxdemo 组件的方式执行 a/b 除法。

模板​

要将 Ajax 调用传递给模板，您需要在 Ajax HTTP 请求的 URL 中设置

  • option - com_ajax
  • template - 模板的名称（例如 cassiopeia）
  • method - 当添加 "Ajax" 作为后缀时，这是模板的辅助方法中要调用的方法的名称
  • format - 预期响应的格式 - “json” 或 “raw”

要调用的方法必须是模板辅助类的公共静态函数，辅助类必须命名为 Tpl<Templatename>Helper，并且必须位于模板目录中的 helper.php 中。

您的辅助函数只返回所需数据；com_ajax 将使用 JsonResponse 提供 JSON 或原始格式输出，具体取决于 HTTP 请求中的 format 参数。

如果您选择 format=raw，则辅助方法返回的任何内容都将直接回显到输出中。

模板示例​

例如，您可以轻松修改 com_ajaxdemo 的 Ajax 文档部分的代码。

在 media/js/divide.js 中，只需更改以下行

 let url = vars.root + 'index.php?option=com_ajaxdemo&format=json&task=ajax.divide';

为

 let url = vars.root + 'index.php?option=com_ajax&template=cassiopeia&format=json',

然后存储以下文件

templates/cassiopeia/helper.php
<?php

defined('_JEXEC') or die;

use Joomla\CMS\Factory;

class TplCassiopeiaHelper
{
    public static function divideAjax()
    {
        $app = Factory::getApplication();
        $input = $app->input; 

        $a = $input->get("a", 0, "float");
        $b = $input->get("b", 0, "float");

        $result = self::_divide($a, $b);
        return $result;
    }
    
    private static function _divide($a, $b)  
    {
        if ($b == 0)
        {
            throw new \Exception('Division by zero!');
        }
        return $a/$b;
    }
}

当然，您永远不应该在属于 Joomla 核心文件的文件夹中写入文件。

但是，如果您开发了自己的模板，或者如果您创建了 cassiopeia 的子模板，那么您可以使用该模板，并将 helper.php 文件存储在该模板的目录中。