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',
    ],
];

配方将更新您的 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 中动态启用“调试”模式。

使用 WebpackEncoreBundle

如果您正在使用 Webpack Encore，则配方还将更新您的 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 文件中。