README

BRJ组织

智能资源加载器（兼容Nette框架）

资源加载器是一个简单的库，可自动将样式和脚本加载到您的应用程序中。

本软件包解决以下问题

注册和加载全局样式和脚本
为特定页面定义特定的样式和脚本，以便始终传输最小数据量
通过PHP在服务器上自动编译样式和脚本，以保持最大性能和易用性
自动缓存管理和失效

整个软件包（以及Baraja生态系统的其余部分）都旨在简单且优雅地使用。它内部解决大多数复杂问题，因此您可以轻松构建大型应用程序。

📦 安装 & 基本用法

此软件包可以使用软件包管理器安装，它也是Baraja 沙盒的一部分。如果您没有使用它，您将需要根据此指南手动安装软件包。

模型配置可以在软件包根目录中的common.neon文件中找到。

要手动安装软件包，请调用Composer并执行以下命令

$ composer require baraja-core/assets-loader

如果自动安装失败或不可用，请在项目的common.neon文件中注册扩展

extensions:
   assetsLoader: Baraja\AssetsLoader\LoaderExtension

在项目的common.neon中，您必须定义基本项目资源。本软件包中的common.neon文件提供了一个完整的配置示例。您可以使用assetsLoader扩展简单地定义配置。

重要：请确保您的项目www/.htaccess不会阻止PHP返回css和js文件。

基本用法

所有样式和脚本分为2类

全局（适用于所有页面或一组页面）
本地（仅适用于一个特定页面/路由）

将样式和脚本放在项目目录www/assets中。内部结构可以是任意的。

在项目的common.neon文件中，简单地定义每个资源的位置。

提示

资源也可以声明为CDN服务器上的URL（例如Baraja CDN）。在这种情况下，CDN路径将直接在源代码中列出。

此类型的资源加载适合内容不随时间变化而变化的文件，因为这些文件不受资源加载器管理。

基本定义示例

assetsLoader:
   routing:
      *:
         - https://unpkg.com/bootstrap/dist/css/bootstrap.min.css
         - css/global.css
         - js/global.js
      Front:Homepage:default:
         - js/welcome-form.js
      Front:Contact:default:
         - css/contact.css
         - js/contact.js
      Service:*:
         - css/service.css

强制格式规范

重要

文件格式根据后缀自动推导（例如.css）。如果出于任何原因（例如，从CDN加载字体）无法指定格式，则可以将其作为键和值传递。

例如（键是资源路径，字段的值是支持的格式）

assetsLoader:
   routing:
      *:
         'https://fonts.googleapis.com/css?family=Hind+Siliguri|Poppins:700&display=swap': css

路由规则

路由规则可以是绝对路由路径（基于Nette路由规则），也可以使用通配符路径。

*规则总是匹配所有模块、演示者（presenters）和动作（actions）。

Front:*规则匹配同一模块中的所有演示者和动作。

Front:Service:*规则匹配同一演示者中的所有动作。

Front:Service:default规则只匹配一个特定的动作。

URL中的查询参数和其他参数不影响路由规则。只有Nette路由器中的静态路由会被评估。路由信息被缓存以提高性能。

演示者中的操作

在BasePresenter中，创建服务实例，将其传递给模板，以便可以轻松渲染。整个逻辑保持不变，只需注册服务，内部逻辑就会自动工作。

abstract class BasePresenter extends \App\Presenters\BasePresenter
{
   #[Inject]
   public Api $assetsLoader;

   public function startup(): void
   {
      parent::startup();
      $this->template->assetsLoader = $this->assetsLoader->getHtmlInit($this->getAction(true));
   }

getHtmlInit()方法自动返回整个渲染的头部内容作为HTML。在演示者中可以直接使用$this->getAction(true)方法，它返回当前路由作为绝对路径。

然后只需将头部内容复制到@layout.latte中。

<!DOCTYPE html>
<html>
   <head>
      <meta charset="utf-8">
      {$assetsLoader ?? ''|noescape}

其余的将自动完成。

资源压缩和编译

该包会自动编译和压缩所有输出资源。

在返回HTTP响应之前，会自动设置缓存HTTP头部和其他逻辑以优化检索。同时，该包包含预制的自动压缩器（实现Baraja\AssetsLoader\Minifier\AssetMinifier接口的服务），可以减少CSS和JS文件的数据大小。

使用针对PHP的JShrink库的修改版本来进行压缩，因此不需要在服务器上安装其他应用程序。

缓存处理

在返回渲染的HTML到头部之前，库会自动检测任何返回文件的最后更改时间。根据这个更改时间，然后计算校验和，并将其作为版本传递的查询参数。

每个请求都会执行更改检测，并且只读取文件系统的元信息（超级快速的方法），因此即使文件在服务器上直接更改（或由某个脚本更改），缓存也会立即失效。

向URL添加查询参数将导致下载新的资源（因为浏览器在其内部缓存中不会保留原始文件的内容），资源将再次以原始方式行为。

警告：不会对绝对URL执行文件内容更改检测，因为无法检测实时更改。

baraja-core / assets-loader

维护者

详细信息