Symfony UX Swup

編輯此頁面

Symfony UX Swup 是一個整合了 Swup 的 Symfony 套件，屬於 Symfony UX 計畫的一部分。

Swup 是一個完整且易於使用的網頁應用程式頁面轉換函式庫。它為網頁應用程式創造了單頁應用程式 (SPA) 的體驗，而無需更動伺服器端任何設定，也無需引入 React/Vue/Angular 應用程式的複雜性。

安裝

注意

在開始之前，請確保您已在應用程式中設定 StimulusBundle。

使用 Composer 和 Symfony Flex 安裝套件

        1
        $ composer require symfony/ux-swup
    

如果您使用 WebpackEncore，請安裝您的資源並重新啟動 Encore (如果您使用 AssetMapper 則不需要)

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

使用方式

為了實作頁面轉換，Swup 的運作方式是轉換應用程式中的連結為 AJAX 呼叫，連到連結的 href 目標。一旦收到 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 選項，但有一些額外新增的選項

        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 框架相同的向後相容性承諾：https://symfony.dev.org.tw/doc/current/contributing/code/bc.html

本作品，包括程式碼範例，以創用CC BY-SA 3.0 授權條款釋出。

版本