README

(请注意，此文档仍在进行中。)

静态库是一种将网页上使用的各种静态资源（如各种样式表和 JavaScript 库）收集在一起的方法。它们提供了一种机制，可以轻松包含多个项目，无需记住依赖关系或顺序。

静态库通过事件进行注册。这样，如果您不需要任何库，则不会发生任何操作，从而节省性能。因此，如果您想注册一个库，只需将其添加到服务提供者的 boot() 方法中即可

Event::listen(\HollyIT\StaticLibraries\Events\RegisterStaticLibrariesEvent::class,
    function (\HollyIT\StaticLibraries\Events\RegisterStaticLibrariesEvent $event) {
    $event->manager->add(
        Library::make('package1', __DIR__ . '/../dist')
            ->assets(
                Css::make('css/package1.css'),
                Js::make('js/package1.js')
            )
            ->requires('package1'),
        Library::make('package2', __DIR__ . '/../dist')
            ->assets(
                Css::make('css/package2.css'),
                Js::make('js/package2.js')
            )
    );
});

Library::make 的签名是 $libraryName, $basePath。上面的示例假设您正在开发一个包。您还可以在自己的应用程序中使用库，并将基本路径设置为 public_path 或其他任何位置。此包将知道如何处理。

安装

首先，您需要引入此包

composer require hollyit/laravel-static-libraries

之后，您需要更新您的 blade 文件以注入资源。因此，在 blade 文件的头部，只需添加

@static_assets_head()

并在关闭标签之前添加

@static_assets_footer()

这两个指令调用一系列其他 blade 模板来组装所有所需的库的代码。您可以随意发布模板以覆盖它们，但默认设置应该足够。

理解库

如您在上面所注意到的，库添加了断言，即您希望添加的实际 JavaScript 或 CSS 文件/代码。目前有 5 种类型的资产可用。

前三种资产类型是 Css、Js 和 JsModule，它们是基于文件的资产。您可以将其添加为库基本路径的相对路径或 URL（因此允许使用 CDN 或外部文件）。

最后两种资产类型是 InlineStyle 和 InlineScript。如名称所示，这些是内联样式资产，将在适当的 <style> 或 <script> 标签之间注入提供的代码。

在所有资产中，您可以提供要添加到相应标签的属性。例如

Css::make('css/package1.css', ['media' => print])

将添加具有 media="print" 属性的样式表。

JsModule

此包提供了一种自定义 JsModule 资产类型。此资产类型的工厂签名略有不同

make(string $file, string $name, array $attributes = [])

在渲染时，它将添加 type="module" 和 name="{$name}" 属性。但 JsModules 提供的远不止这些。

ES Modules 的提议标准是 import-map。您可以在此处了解有关信息这里。虽然适应性还不够广泛，但此模块将注入一个垫片以提供对需要它的浏览器的支持。此垫片可以在静态库配置文件中覆盖。

当您将 JsModules 添加到库中时，此包将自动为您的页面渲染一个 import map。以下是我想要表达的意思的示例

<script type="importmap">
            {"imports":
                {
                    "module1":"https://\/js\/module1.js?_c=efb6379fdf66",
                    "module2":"https://\/js\/module2.js?_c=338cbc12e51d"
                }
            }
        
</script>

此映射是从以下库自动生成的

Library::make('test1')
    ->assets(
        \HollyIT\StaticLibraries\StaticAssets\JsModule::make('js/module1.js', 'module1')
    )

Library::make('test2')->assets(
    \HollyIT\StaticLibraries\StaticAssets\JsModule::make('js/module2.js', 'module2')
)

依赖关系管理

库还可以管理依赖关系。通过将 ->requires(...libraries) 链接到您的库声明，每当需要该库时，它将自动需要并在其之前放置在 requires() 中定义的库。

另一个依赖关系功能是在需要另一个库时添加库。例如，假设您正在使用 TinyMCE 并有另一个为它提供插件的库。那么，如果您定义一个库

    Library::make('tinymce_plugin', __DIR__)
    ->requiredWith('tinymce')

那么简单地做 $libraries->require('tinymce') 也会包含 'tinymce_plugin'。您还可以指定该库是否应该添加到父库之前或之后

    Library::make('tinymce_plugin', __DIR__)
    ->requiredWith('tinymce')
    ->position(new PositionBefore('tinymce'))

提供了两种定位规则：PositionBefore 和 PositionAfter。

资源服务

此软件包使用驱动程序的概念来处理发布和托管您的静态资源。它附带两个驱动程序，但可以添加更多。驱动程序可以在静态库配置文件中进行配置，或者通过在您的 .env 文件中设置 STATIC_LIBRARIES_DRIVER 来进行设置。

开发驱动程序

这是最简单的驱动程序。它通过 Laravel 为您提供所有本地资源。

1.1.0 新增

现在您可以为库指定 ->withHotFile(...文件路径...)。当使用开发驱动程序时，如果存在热文件，它将自动解析并包含该文件。目前，这仅适用于 Laravel Mix。Vite 将在不久的将来添加。

文件驱动程序

此驱动程序被称为可发布驱动程序。这意味着它将复制各种文件从其位置复制到您的 public_path。如果文件未找到，则将回退到利用 Laravel 提供文件。此驱动程序还基于静态文件的哈希值集成缓存破坏。

要发布文件，只需发出以下 artisan 命令

php artisan static-libraries:publish

您也可以使用以下命令取消发布库

php artisan static-libraries:unpublish

注意：随着更多软件包使用静态库，很容易最终得到过时的发布资源。为防止这种情况，建议将以下内容添加到您项目 composer.json 文件的 scripts 部分中

        "post-update-cmd": [
            "@php artisan static-libraries:publish"
        ],

这样，每当您更新软件包时，任何已修改的库都将发布其文件。

开发信息

此软件包还提供另一个 artisan 命令，static-libraries:info。这将列出所有已注册库、它们的发布状态以及发布的文件是否过时。

未来开发

如果您想添加 S3 支持，我非常感谢您打开一个 PR 并创建一个处理该功能的驱动程序。我不是 S3 的大用户，但此软件包将与它很好地配合使用，并且可以使用 S3 的回退规则，如果需要，可以回退到通过 Laravel 提供文件服务。

变更日志

请参阅 CHANGELOG 了解最近更改的更多信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

许可证

MIT 许可证 (MIT)。请参阅许可证文件了解更多信息。

hollyit / laravel-static-libraries

维护者

详细信息