将 JavaScript 添加到您的扩展

本节介绍将 JavaScript 添加到 Joomla 扩展所需的步骤。

JavaScript 代码文件

要将 JavaScript 文件添加到您的扩展，您应该使用 Joomla Web 资产管理器 并执行以下操作。

1 将您的 JavaScript 文件存储在 media 文件夹中

您应该将 JS 文件存储在开发媒体/js 文件夹中，例如

media
  ├─ css
  └─ js
      ├─ myjs1.js
      └─ myjs2.js

然后，需要将其复制到 Joomla 实例的 media 文件夹中，因此在安装清单文件中需要

扩展清单文件

    <media destination="com_example" folder="media">
        <folder>js</folder>
    </media>

此处（以及本文档页面中的其他地方）需要将“com_example”替换为扩展的类型和名称。

安装扩展时，Joomla 会将 js 文件复制到 media/com_example/js 文件夹中。

信息

您也可以在开发文件夹 media/mylib/js/ 中实现扩展的 JavaScript 库，其中包含 js 源文件。这将映射到 media/com_example/mylib/js，当您的扩展安装时。

2 创建 media/joomla.asset.json 文件

在媒体文件夹中创建一个名为 joomla.asset.json 的文件，如 Web 资产管理器 - 定义 中所定义，例如

{
  "$schema": "https://developer.joomla.net.cn/schemas/json-schema/web_assets.json",
  "name": "com_example",
  "version": "1.0.0",
  "description": "Example joomla.asset.json file",
  "license": "GPL-2.0+",
  "assets": [
    {
      "name": "com_example.myjs1",
      "type": "script",
      "uri": "com_example/myjs1.js",
      "attributes": {
        "defer": true
      },
      "dependencies": [
        "core", "jquery"
      ],
      "version": "1.2.0"
    },
    {
      "name": "com_example.myjs2",
      "type": "script",
      "uri": "com_example/myjs1.min.js",
      "attributes": {
        "async": true
      },
      "dependencies": [
        "com_example.myjs1", "form.validate"
      ],
      "version": "1.0.3"
    }
    ]
}

在 assets 数组中，键是

name - 您可以在此处分配任何字符串，但通常将其设置为扩展的名称“点”JavaScript 文件的名称。此 name 是您将在 PHP 代码中使用的内容，以将 JavaScript 文件包含到网页中。包含您的扩展名称意味着该名称不应与 Joomla 或任何其他扩展的资产发生冲突。

type - 对于 JavaScript，这是“script”。

uri - 这告诉 Joomla 在哪里可以找到您的代码。它是 media 文件夹下的路径，但 js 段已删除。请注意，您可以使用压缩的 JavaScript，如“myjs2”示例所示。如果您在 js 文件夹中包含 myjs2.js 和 myjs2.min.js，那么如果在全局配置中打开 Joomla 调试，Web 资产管理器将包含非压缩版本。

attributes - 这些是属性，它们只会映射到页面 HTML 输出中 HTML <script> 标签的属性。

dependencies - 代码依赖的其他资产的名称或名称，例如上面的 json 中

• "com_example.myjs1" 依赖于 Joomla“core”（在 media/system/joomla.asset.json 中指定为 Joomla core.js 库）和“jquery”（在 media/vendor/joomla.asset.json 中指定）
• "com_example.myjs2" 依赖于“form.validate”（在 media/system/joomla.asset.json 中指定，用于执行表单字段验证）
• "com_example.myjs2" 还依赖于“com_example.myjs1”（在同一个 joomla.asset.json 文件中），因此当加载 myjs2.js 时，Joomla 还会加载 myjs1.js，以及“com_example.myjs1”的所有依赖项。

Web 资产管理器在 HTML 中对 <script> 标签进行排序，以确保浏览器首先处理依赖项。

您如何知道要包含为依赖项的 Joomla 库的名称？Joomla JavaScript 库 中的条目可能会有所帮助，但您可能需要查看代码文件

• Joomla 库资产位于 media/system/joomla.asset.json 中，并引用 media/system/js 中的代码
• 供应商库资产位于 media/vendor/joomla.asset.json 中，并引用 media/vendor/js 中的代码

这两个 joomla.asset.json 文件始终由 Joomla 处理，因此它们的资产始终可用。

version - 您要应用于 JavaScript 代码的版本。更新代码时，如果增加版本号，Joomla 将强制浏览器重新加载代码，而不是使用缓存的副本。（它通过在 js 文件的 URL 中添加您的版本作为查询参数来实现这一点）。

您还需要让 Joomla 将 joomla.asset.json 文件复制到 media 文件夹中

扩展清单文件

    <media destination="com_example" folder="media">
        <filename>joomla.asset.json</filename>
        <folder>js</folder>
    </media>

信息

如果您的扩展只有一个或两个资产，那么您可能会发现直接使用 Web 资产管理器 注册您的资产 比通过 joomla.asset.json 文件更方便。您可以使用 WebAssetManager::registerScript

$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->registerScript('com_example.myjs1', 'com_example/myjs1.js', [], ['defer' => 'true'], ["core", "jquery"]);

或使用 WebAssetManager::method_registerAndUseScript 一次性注册和使用您的脚本

$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->registerAndUseScript('com_example.myjs1', 'com_example/myjs1.js', [], ['defer' => 'true'], ["core", "jquery"]);

3 让 Joomla 处理您的 joomla.asset.json 文件

如果您的扩展是组件或模板，Joomla 会自动为您执行此步骤，您无需执行任何操作。

如果您的扩展是插件或模块，则需要在 PHP 代码中将文件注册到 Web 资产管理器

$app = Factory::getApplication();
$document = $app->getDocument();
$wa = $document->getWebAssetManager();
$wa->getRegistry()->addExtensionRegistryFile('mod_example');

上面的代码将让 Joomla 处理 media/mod_example/joomla.asset.json 并注册其中的资产。

4 在 PHP 代码中使用您的资产

$app = Factory::getApplication();
$document = $app->getDocument();
$wa = $document->getWebAssetManager();
$wa->useScript('com_example.myjs2');

Web 资产管理器将包含 <script> 标签以供您的 myjs2.js 代码使用，以及其所有依赖项的标签。

在核心 Joomla 中，使用脚本的代码通常放置在相关的 tmpl 文件中，但您也可以将其放置在另一个文件中，例如 View 类文件。有时，View 可能具有不同的 tmpl 文件，其中只有一个可能需要 JavaScript 代码，因此将 useScript 放置在适当的 tmpl 文件中将更高效。

提示

如果您的扩展使用 Joomla 库代码，那么您可能可以使用

$document = $this->getDocument();
// or the Application instance via
$app = $this->getApplication();

通过这种方式使用 依赖注入，而不是重复调用 Factory 静态函数，您可以更轻松地为自动单元测试模拟类，以提高代码质量。

使用外部 JavaScript 库

要使用外部库，请将库的 URL 指定为资产的 uri 键的值。

例如，要绘制地图，Joomla v3 Helloworld MVC 教程 使用了由 cdnjs.com 分发的 Openlayers JS 库

    {
      "name": "com_helloworld.mymap",
      "type": "script",
      "uri": "com_helloworld/mymap.min.js",
      "dependencies": [
        "com_helloworld.openlayers"
      ],
      "attributes": {
        "defer": true
      },
      "version": "1.0.0"
    },
    {
      "name": "com_helloworld.openlayers",
      "type": "script",
      "uri": "https://cdnjs.cloudflare.com/ajax/libs/openlayers/4.6.4/ol.js",
      "dependencies": [
      ],
      "attributes": {
        "defer": true
      },
      "version": "4.6.4"
    }

内联脚本

有时您可能需要动态生成 JavaScript 代码，而不是将其存储在文件中。

在这种情况下，您可以使用 Web 资产管理器 addInlineScript 函数，例如

$hi = "function sayhi() { alert('Hi!'); }";
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->addInlineScript($hi);

有关更多详细信息，请参见 Web 资产管理器 - 添加内联脚本。

将变量传递给 JavaScript

您可以使用 Document 类 addScriptOptions 方法将变量从 PHP 代码传递到 JavaScript 代码。

例如

$phpvars = array('alpha' => 1, 'beta' => 'test', 'gamma' => null);
$document = Factory::getApplication()->getDocument();
$document->addScriptOptions('com_example.myvars', $phpvars);

然后您可以在 JavaScript 中检索这些变量

var jsvars = Joomla.getOptions('com_example.myvars');
console.log(jsvars);

这将在浏览器控制台中输出 JavaScript 对象结构

{alpha: 1, beta: "test", gamma: null}

您可以在代码中多次使用它，使用不同的键（上面的示例中的键为“com_example.myvars”）。

您应该在键中包含扩展名称，因为数据是在全局“选项存储”中传递的，否则它可能会与来自其他扩展的数据发生冲突。

Joomla.getOptions 函数位于 Joomla 系统 core.js 库文件中，因此您的 JavaScript 资产应该包含“core”作为依赖项。

将语言常量传递给 JavaScript

您可以使用 Language Text::script 函数将语言常量传递给 JavaScript。

use Joomla\CMS\Language\Text;

Text::script('COM_EXAMPLE_ERROR_MESSAGE');

您应该确保扩展的语言已加载 - Joomla 在 MVC 库代码中为组件执行此操作，但不会自动处理模块或插件。

在您的 JavaScript 中，您可以使用以下方法访问翻译后的字符串

const errorMessage = Joomla.Text._('COM_EXAMPLE_ERROR_MESSAGE');

您可以使用以下方法将错误消息写入 Joomla 网页的消息区域

Joomla.renderMessages({ 'error': [errorMessage] });

如果您的语言常量包含 %s 以允许参数，则必须使用 JavaScript 函数来替换这些 %s 条目。

JavaScript Joomla.Text._ 函数位于 core.js 中，但 PHP Text::script 函数确保为您加载它。

JavaScript Joomla.renderMessages 函数位于 messages.js 中，因此您的资产需要包含 "messages" 作为依赖项。

示例

模块开发教程 步骤 7 添加 JavaScript 包含以下示例：

• 添加 JavaScript 文件
• 将变量传递给 JavaScript

模块开发教程 步骤 9 添加 Ajax 包含以下示例：

• 将语言常量传递给 JavaScript
• 在 JavaScript 中渲染消息