WebpackEncoreBundle：Symfony 与 Webpack Encore 的集成！

编辑此页

此 bundle 允许您使用 splitEntryChunks() 功能，通过读取 entrypoints.json 文件并帮助您渲染所有需要的动态 script 和 link 标签。

安装

通过以下命令安装 bundle

        1
        $ composer require symfony/webpack-encore-bundle
    

配置

如果您正在使用 Symfony Flex，那么您就完成了！ recipe 将预先配置 config/packages/webpack_encore.yaml 文件中您需要的一切

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
        # config/packages/webpack_encore.yaml
webpack_encore:
    # The path where Encore is building the assets - i.e. Encore.setOutputPath()
    # if you customize this, you will also need to change framework.assets.json_manifest_path (it usually lives in assets.yaml)
    output_path: '%kernel.project_dir%/public/build'
    # If multiple builds are defined (as shown below), you can disable the default build:
    # output_path: false

    # Set attributes that will be rendered on all script and link tags
    script_attributes:
        defer: true
        # referrerpolicy: origin
    # link_attributes:
    #     referrerpolicy: origin

    # if using Encore.enableIntegrityHashes() and need the crossorigin attribute (default: false, or use 'anonymous' or 'use-credentials')
    # crossorigin: 'anonymous'

    # preload all rendered script and link tags automatically via the http2 Link header
    # preload: true

    # Throw an exception if the entrypoints.json file is missing or an entry is missing from the data
    # strict_mode: false

    # if you have multiple builds:
    # builds:
        # frontend: '%kernel.project_dir%/public/frontend/build'
        # or if you use a CDN:
        # frontend: 'https://cdn.example.com/frontend/build'

        # pass the build name" as the 3rd argument to the Twig functions
        # {{ encore_entry_script_tags('entry1', null, 'frontend') }}

    # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes)
    # Available in version 1.2
    # Put in config/packages/prod/webpack_encore.yaml
    # cache: true
    

如果您没有使用 Flex，手动启用 bundle 并从上面复制配置文件到您的项目中。

用法

如果您使用 Symfony Flex 安装此 bundle，Webpack Encore 中的 “Split Chunks” 功能默认通过 recipe 启用。否则，请手动启用它

        1
2
3
4
5
6
7
8
9
        // webpack.config.js
// ...
    .setOutputPath('public/build/')
    .setPublicPath('/build')
    .setManifestKeyPrefix('build/')
    .addEntry('entry1', './assets/some_file.js')

+   .splitEntryChunks()
// ...
    

当您启用 splitEntryChunks() 时，您可能需要多个 script 和 link 标签，而不是只需要 1 个用于 entry1.js 的 script 标签和 1 个用于 entry1.css 的 link 标签。这是因为 Webpack “拆分” 您的文件成更小的块，以获得更好的优化。

为了帮助解决这个问题，Encore 写入了一个 entrypoints.json 文件，其中包含每个 “entry” 所需的所有文件。

例如，要渲染特定 “entry”（例如 entry1）的所有 script 和 link 标签，您可以

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        {# any template or base layout where you need to include a JavaScript entry #}

{% block javascripts %}
    {{ parent() }}

    {{ encore_entry_script_tags('entry1') }}

    {# or render a custom attribute #}
    {#
    {{ encore_entry_script_tags('entry1', attributes={
        defer: true
    }) }}
    #}
{% endblock %}

{% block stylesheets %}
    {{ parent() }}

    {{ encore_entry_link_tags('entry1') }}
{% endblock %}
    

假设 entry1 需要包含两个文件 - build/vendor~entry1~entry2.js 和 build/entry1.js，那么 encore_entry_script_tags() 等价于

        1
2
        <script src="{{ asset('build/vendor~entry1~entry2.js') }}"></script>
<script src="{{ asset('build/entry1.js') }}"></script>
    

如果您想要更多控制，可以使用 encore_entry_js_files() 和 encore_entry_css_files() 方法获取所需的文件列表，然后手动循环并创建 script 和 link 标签。

在一个请求中多次渲染（例如，生成 PDF）

当您渲染 script 或 link 标签时，bundle 会非常智能，不会在同一请求中重复相同的 JavaScript 或 CSS 文件。这可以防止在您渲染都依赖于同一文件的多个 entry 时出现重复的 <link> 或 <script> 标签。

但在某些情况下，您可能希望在一个请求中多次渲染同一 entry 的 script 和 link 标签。例如，如果您渲染多个 Twig 模板以在单个请求期间创建多个 PDF 文件。

在这种情况下，在每次渲染之前，您需要 “重置” 内部缓存，以便 bundle 重新渲染先前渲染的 CSS 或 JS 文件。例如，在控制器中

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // src/Controller/SomeController.php
use Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface;

class SomeController
{
    public function index(EntrypointLookupInterface $entrypointLookup)
    {
        $entrypointLookup->reset();
        // render a template

        $entrypointLookup->reset();
        // render another template

        // ...
    }
}
    

如果您有多个构建，您还可以自动注入 Symfony\WebpackEncoreBundle\Asset\EntrypointLookupCollectionInterface 并使用它来获取任何构建的 EntrypointLookupInterface 对象。

script 和 link 标签上的自定义属性

可以通过 3 种不同的方式将自定义属性添加到渲染的 script 或 link 中

通过全局配置（script_attributes 和 link_attributes） - 请参阅上面的配置示例。
在 Twig 中渲染时 - 请参阅上面文档中的 attributes 选项。

通过监听 Symfony\WebpackEncoreBundle\Event\RenderAssetTagEvent 事件。例如

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        namespace App\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\WebpackEncoreBundle\Event\RenderAssetTagEvent;

class ScriptNonceSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            RenderAssetTagEvent::class => 'onRenderAssetTag'
        ];
    }

    public function onRenderAssetTag(RenderAssetTagEvent $event)
    {
        if ($event->isScriptTag()) {
            $event->setAttribute('nonce', 'lookup nonce');
        }
    }
}
    

Stimulus / Symfony UX 助手

此 bundle 的版本 1 附带了 stimulus_controller(), stimulus_action() 和 stimulus_target() Twig 函数。这些已被删除：请改用 symfony/stimulus-bundle。

这项工作，包括代码示例，均根据 Creative Commons BY-SA 3.0 许可获得许可。

版本