Symfony UX Dropzone

编辑此页

Symfony UX Dropzone 是一个 Symfony 扩展包，为 Symfony 表单中的文件输入提供轻量级的拖放区域。它是 Symfony UX 计划的一部分。

它允许访问者将文件拖放到容器中，而无需浏览他们的计算机来查找文件。

安装

注意

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

使用 Composer 和 Symfony Flex 安装扩展包

        1
        $ composer require symfony/ux-dropzone
    

如果你正在使用 WebpackEncore，请安装你的 assets 并重启 Encore (如果你正在使用 AssetMapper，则不需要)

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

用法

Symfony UX Dropzone 最常见的用法是将其用作原生 FileType 类的直接替代品

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // ...
use Symfony\UX\Dropzone\Form\DropzoneType;

class CommentFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            // ...
            ->add('photo', DropzoneType::class)
            // ...
        ;
    }

    // ...
}
    

自定义设计

Symfony UX Dropzone 提供默认样式表以简化使用。如果你愿意，你可以禁用它以添加你自己的设计。

在 assets/controllers.json 中，通过将 @symfony/ux-dropzone/dist/style.min.css 的自动导入切换为 false 来禁用默认样式表

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        {
    "controllers": {
        "@symfony/ux-dropzone": {
            "dropzone": {
                "enabled": true,
                "fetch": "eager",
                "autoimport": {
                    "@symfony/ux-dropzone/dist/style.min.css": false
                }
            }
        }
    },
    "entrypoints": []
}
    

注意

注意：你应该将值设置为 false，而不是删除该行，这样 Symfony Flex 将来就不会尝试再次添加该行。

完成后，默认样式表将不再使用，你可以在 Dropzone 之上实现你自己的 CSS。

扩展默认行为

Symfony UX Dropzone 允许你使用自定义 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
30
        // mydropzone_controller.js

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

export default class extends Controller {
    connect() {
        this.element.addEventListener('dropzone:connect', this._onConnect);
        this.element.addEventListener('dropzone:change', this._onChange);
        this.element.addEventListener('dropzone:clear', this._onClear);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side-effects
        this.element.removeEventListener('dropzone:connect', this._onConnect);
        this.element.removeEventListener('dropzone:change', this._onChange);
        this.element.removeEventListener('dropzone:clear', this._onClear);
    }

    _onConnect(event) {
        // The dropzone was just created
    }

    _onChange(event) {
        // The dropzone just changed
    }

    _onClear(event) {
        // The dropzone has just been cleared
    }
}
    

然后在你的表单中，将你的控制器添加为 HTML 属性

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // ...
use Symfony\UX\Dropzone\Form\DropzoneType;

class CommentFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            // ...
            ->add('photo', DropzoneType::class, [
                'attr' => ['data-controller' => 'mydropzone'],
            ])
            // ...
        ;
    }

    // ...
}
    

向后兼容性承诺

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

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

版本