Symfony UX Swup

编辑此页

Symfony UX Swup 是一个 Symfony 扩展包，集成了 Swup 到 Symfony 应用中。它是 Symfony UX 倡议的一部分。

Swup 是一个完整且易于使用的网页应用页面过渡库。它为 Web 应用程序创建单页应用程序的感觉，而无需更改服务器上的任何内容，也无需引入 React/Vue/Angular 应用程序的复杂性。

安装

注意

在开始之前，请确保你的应用中配置了 StimulusBundle。

使用 Composer 和 Symfony Flex 安装此扩展包

        1
        $ composer require symfony/ux-swup
    

如果你正在使用 WebpackEncore，请安装你的 assets 并重启 Encore (如果你正在使用 AssetMapper，则无需此操作)

        1
2
        $ npm install --force
$ npm run watch
    

用法

为了实现页面过渡，Swup 的工作原理是将应用程序的链接转换为对其 href 目标的 AJAX 调用。一旦收到 AJAX 调用结果，Swup 就能将当前页面的内容与通过 AJAX 收到的新内容进行交换。在进行此交换时，它就能够为页面之间的过渡添加动画效果。

Symfony UX Swup 的主要用法是使用其 Stimulus 控制器来初始化 Swup

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        <html lang="en">
    <head>
        <title>Swup</title>

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body {{ stimulus_controller('symfony/ux-swup/swup') }}>
        {# ... #}

        <main id="swup">
            {# ... #}
        </main>
    </body>
</html>
    

注意

stimulus_controller() 函数来自 StimulusBundle。

就是这样！Swup 现在会对链接点击做出反应，并运行默认的淡入过渡效果。

默认情况下，Swup 将使用 #swup 选择器作为容器，这意味着它只会交换此容器的内容，从一个页面到另一个页面。如果你愿意，你可以配置额外的容器，例如，拥有一个在页面更改时更新的导航菜单

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
        <html lang="en">
    <head>
        <title>Swup</title>

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body
        {{ stimulus_controller('symfony/ux-swup/swup', {
            containers: ['#swup', '#nav']
        }) }}
    >
        {# ... #}

        <nav id="nav">
            {# ... #}
        </nav>

        <main id="swup">
            {# ... #}
        </main>
    </body>
</html>
    

你可以使用控制器上的值配置其他几个选项。其中大多数对应于 Swup Options，但还有一些额外的选项

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <html lang="en">
    <head>
        <title>Swup</title>
    </head>
    <body
        {{ stimulus_controller('symfony/ux-swup/swup', {
            containers: ['#swup', '#nav'],
            animateHistoryBrowsing: true,
            animationSelector: '[class*="transition-"]',
            cache: true,
            linkSelector: '...',

            theme: 'slide',
            debug: true,
        }) }}
    >
        {# ... #}
    </body>
</html>
    

额外的选项是

theme: 可以是 slide 或 fade (默认值)；
debug: 添加此属性以启用调试。

扩展默认行为

Symfony UX Swup 允许你使用自定义 Stimulus 控制器来扩展其默认行为

        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
        // assets/controllers/myswup_controller.js

import { Controller } from '@hotwired/stimulus';
import SwupProgressPlugin from '@swup/progress-plugin';

export default class extends Controller {
    connect() {
        this.element.addEventListener('swup:pre-connect', this._onPreConnect);
        this.element.addEventListener('swup:connect', this._onConnect);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side-effects
        this.element.removeEventListener('swup:connect', this._onConnect);
        this.element.removeEventListener('swup:pre-connect', this._onPreConnect);
    }

    _onPreConnect(event) {
        // Swup has not been initialized - options can be changed
        console.log(event.detail.options); // Options that will be used to initialize Swup
        event.detail.options.plugins.push(new SwupProgressPlugin()); // Adding the progress bar plugin
    }

    _onConnect(event) {
        // Swup has just been intialized and you can access details from the event
        console.log(event.detail.swup); // Swup instance
        console.log(event.detail.options); // Options used to initialize Swup
    }
}
    

然后在你的模板中，将你的控制器添加到 HTML 属性中

        1
2
3
4
5
6
7
8
9
10
11
        <html lang="en">
    <head>
        <title>Swup</title>
        {# ... #}
    </head>
    <body {{ stimulus_controller('myswup')|stimulus_controller('symfony/ux-swup/swup', {
        // ... options
    }) }}>
        {# ... #}
    </body>
</html>
    

注意

请注意在 Swup 控制器之前添加你的控制器，以便它能在之前执行并能正确监听 swup:connect 事件。

向后兼容性承诺

此扩展包旨在遵循与 Symfony 框架相同的向后兼容性承诺： http://symfony.ac.cn/doc/current/contributing/code/bc.html

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。

版本