StimulusBundle：Symfony 與 Stimulus 的整合

TypeScript 控制器

如果您想使用 TypeScript 來定義您的控制器，您可以！安裝並設定 sensiolabs/typescript-bundle。然後務必將 assets/controllers 路徑新增至 sensiolabs_typescript.source_dir 設定中。最後，在該目錄中建立您的控制器，就完成了。

UX 套件

Symfony 提供了一組 UX 套件，它們增加了額外的 Stimulus 控制器以解決常見問題。StimulusBundle 會啟用 assets/controllers.json 檔案中提及的任何第三方 Stimulus 控制器。每當您安裝 UX 套件時，此檔案都會更新。

官方 UX 套件包括

• ux-autocomplete：將 EntityType、ChoiceType 或任何 <select> 元素轉換為 Ajax 驅動的自動完成欄位（請參閱示範）
• ux-chartjs：使用 Chart.js 輕鬆繪製圖表（請參閱示範）
• ux-cropperjs：用於裁切影像的表單類型和工具（請參閱示範）
• ux-dropzone：用於檔案上傳的樣式化「拖放區」表單類型（請參閱示範）
• ux-lazy-image：使用 BlurHash 優化影像載入（請參閱示範）
• ux-live-component：以零 JavaScript 建立動態介面（請參閱示範）
• ux-notify：使用 Mercure 發送伺服器發送的原生通知（請參閱示範）
• ux-react：從 Twig 渲染 React 組件（請參閱示範）
• ux-svelte：從 Twig 渲染 Svelte 組件（請參閱示範）
• ux-swup：與 Swup 整合（請參閱示範）
• ux-toggle-password：切換密碼輸入的可見性（請參閱示範）
• ux-translator：在 JavaScript 中使用您的 Symfony 翻譯（請參閱示範）
• ux-turbo：與 Turbo Drive 整合，以獲得單頁應用程式體驗（請參閱示範）
• ux-twig-component：建立由 PHP 類別支援的 Twig 組件（請參閱示範）
• ux-typed：與 Typed 整合（請參閱示範）
• ux-vue：從 Twig 渲染 Vue 組件（請參閱示範）

延遲載入 Stimulus 控制器

預設情況下，您的所有控制器（即 assets/controllers/ 中的檔案 + assets/controllers.json 中的控制器）都會在每個頁面下載並載入。

有時您可能會有一個控制器僅在某些頁面上使用。在這種情況下，您可以將控制器設定為「延遲載入」。在這種情況下，控制器在初始頁面載入時不會被下載。相反地，一旦頁面上出現與控制器匹配的元素（例如 <div data-controller="hello">），控制器以及它導入的任何其他內容都將透過 Ajax 延遲載入。

若要將您的自訂控制器設定為延遲載入，請在頂端新增一個特殊註解

1
2
3
4
5
6

import { Controller } from '@hotwired/stimulus';

/* stimulusFetch: 'lazy' */
export default class extends Controller {
    // ...
}

若要將第三方控制器設定為延遲載入，請在 assets/controllers.json 中將 fetch 設定為 lazy。

stimulus_controller

此套件附帶一個特殊的 stimulus_controller() Twig 函式，可用於渲染 Stimulus 控制器與值 以及 CSS 類別。Stimulus 控制器也可以透過使用 Outlets 引用其他控制器。

例如

1
2
3
4
5
6
7
8
9
10
11
12

<div {{ stimulus_controller('chart', { 'name': 'Likes', 'data': [1, 2, 3, 4] }) }}>
    Hello
</div>

<!-- would render -->
<div
   data-controller="chart"
   data-chart-name-value="Likes"
   data-chart-data-value="&#x5B;1,2,3,4&#x5D;"
>
   Hello
</div>

如果您想要設定 CSS 類別

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<div {{ stimulus_controller('chart', { 'name': 'Likes', 'data': [1, 2, 3, 4] }, { 'loading': 'spinner' }) }}>
    Hello
</div>

<!-- would render -->
<div
   data-controller="chart"
   data-chart-name-value="Likes"
   data-chart-data-value="&#x5B;1,2,3,4&#x5D;"
   data-chart-loading-class="spinner"
>
   Hello
</div>

<!-- or without values -->
<div {{ stimulus_controller('chart', controllerClasses = { 'loading': 'spinner' }) }}>
    Hello
</div>

以及使用 outlets

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<div {{ stimulus_controller('chart', { 'name': 'Likes', 'data': [1, 2, 3, 4] }, { 'loading': 'spinner' }, { 'other': '.target' ) }}>
    Hello
</div>

<!-- would render -->
<div
   data-controller="chart"
   data-chart-name-value="Likes"
   data-chart-data-value="&#x5B;1,2,3,4&#x5D;"
   data-chart-loading-class="spinner"
   data-chart-other-outlet=".target"
>
   Hello
</div>

<!-- or without values/classes -->
<div {{ stimulus_controller('chart', controllerOutlets = { 'other': '.target' }) }}>
    Hello
</div>

任何非純量值（例如 data: [1, 2, 3, 4]）都會進行 JSON 編碼。並且所有值都會被正確逸出（字串 [ 是一個逸出的 [ 字元，因此屬性實際上是 [1,2,3,4]）。

如果您在同一個元素上有多個控制器，您可以將它們串聯起來，因為還有一個 stimulus_controller 過濾器

1
2
3
4
5
6
7
8

<div {{ stimulus_controller('chart', { 'name': 'Likes' })|stimulus_controller('other-controller') }}>
    Hello
</div>

<!-- would render -->
<div data-controller="chart other-controller" data-chart-name-value="Likes">
    Hello
</div>

您也可以將產生的屬性作為陣列檢索，這對於表單等情況可能很有用

1

{{ form_start(form, { attr: stimulus_controller('chart', { 'name': 'Likes' }).toArray() }) }}

stimulus_action

stimulus_action() Twig 函式可用於渲染 Stimulus 動作。

例如

1
2
3
4
5
6

<div {{ stimulus_action('controller', 'method') }}>Hello</div>
<div {{ stimulus_action('controller', 'method', 'click') }}>Hello</div>

<!-- would render -->
<div data-action="controller#method">Hello</div>
<div data-action="click->controller#method">Hello</div>

如果您在同一個元素上有多個動作和/或方法，您可以將它們串聯起來，因為還有一個 stimulus_action 過濾器

1
2
3
4
5
6
7
8

<div {{ stimulus_action('controller', 'method')|stimulus_action('other-controller', 'test') }}>
    Hello
</div>

<!-- would render -->
<div data-action="controller#method other-controller#test">
    Hello
</div>

您也可以將產生的屬性作為陣列檢索，這對於表單等情況可能很有用

1

{{ form_row(form.password, { attr: stimulus_action('hello-controller', 'checkPasswordStrength').toArray() }) }}

您也可以將參數傳遞給動作

1
2
3
4

<div {{ stimulus_action('hello-controller', 'method', 'click', { 'count': 3 }) }}>Hello</div>

<!-- would render -->
<div data-action="click->hello-controller#method" data-hello-controller-count-param="3">Hello</div>

stimulus_target

stimulus_target() Twig 函式可用於渲染 Stimulus 目標。

例如

1
2
3
4
5
6

<div {{ stimulus_target('controller', 'myTarget') }}>Hello</div>
<div {{ stimulus_target('controller', 'myTarget secondTarget') }}>Hello</div>

<!-- would render -->
<div data-controller-target="myTarget">Hello</div>
<div data-controller-target="myTarget secondTarget">Hello</div>

如果您在同一個元素上有多個目標，您可以將它們串聯起來，因為還有一個 stimulus_target 過濾器

1
2
3
4
5
6
7
8

<div {{ stimulus_target('controller', 'myTarget')|stimulus_target('other-controller', 'anotherTarget') }}>
    Hello
</div>

<!-- would render -->
<div data-controller-target="myTarget" data-other-controller-target="anotherTarget">
    Hello
</div>

您也可以將產生的屬性作為陣列檢索，這對於表單等情況可能很有用

1

{{ form_row(form.password, { attr: stimulus_target('hello-controller', 'myTarget').toArray() }) }}

使用 AssetMapper

如果您使用 AssetMapper，則會將兩個新條目新增至您的 importmap.php 檔案

1
2
3
4
5
6
7
8
9
10
11

// importmap.php
return [
    // ...

    '@symfony/stimulus-bundle' => [
        'path' => '@symfony/stimulus-bundle/loader.js',
    ],
    '@hotwired/stimulus' => [
        'version' => '3.2.2',
    ],
];

Recipe 將會更新您的 assets/bootstrap.js 檔案，使其看起來像這樣

1
2
3
4

// assets/bootstrap.js
import { startStimulusApp } from '@symfony/stimulus-bundle';

const app = startStimulusApp();

@symfony/stimulus-bundle 指的是您 importmap.php 檔案中的新條目之一。此檔案由套件動態建立，並將導入您的所有自訂控制器以及 controllers.json 中的控制器。當您的應用程式在偵錯模式下執行時，它還將動態啟用 Stimulus 中的「debug」模式。

使用 WebpackEncoreBundle

如果您使用 Webpack Encore，recipe 也會更新您的 webpack.config.js 檔案以包含此行

1
2

// webpack.config.js
.enableStimulusBridge('./assets/controllers.json')

assets/bootstrap.js 檔案將會更新，使其看起來像這樣

1
2
3
4
5
6
7
8
9

// assets/bootstrap.js
import { startStimulusApp } from '@symfony/stimulus-bridge';

// Registers Stimulus controllers from controllers.json and in the controllers/ directory
export const app = startStimulusApp(require.context(
    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
    true,
    /\.[jt]sx?$/
));

並且 2 個新套件 - @hotwired/stimulus 和 @symfony/stimulus-bridge - 將會新增至您的 package.json 檔案。