README

Symfony UX 配合工作的集合

安装

开始之前，请确保您已经将 StimulusBundle 配置在您的应用程序中。

使用 Composer 和 Symfony Flex 安装该捆绑包

composer require arkounay/ux-collection

如果您正在使用 WebpackEncore，安装您的资产并重启 Encore（如果您使用 AssetMapper 则不需要）

npm install --force
npm run watch

# or use yarn
yarn install --force
yarn watch

如果您正在使用 bootstrap 5，您应该在 assets\controllers.json 中禁用 standalone CSS 导入

"@arkounay/ux-collection": {
    "collection": {
        "enabled": true,
        "fetch": "eager",
        "autoimport": {
            "@arkounay/ux-collection/src/style.css": true,
            "@arkounay/ux-collection/src/style-when-not-using-bootstrap-5.css": false
        }
    },
    "tabbed_collection": {
        "enabled": true,
        "fetch": "eager",
        "autoimport": {
            "@arkounay/ux-collection/src/tabbed-style.css": true
        }
    }
}

用法

在表单中，使用 UxCollectionType。它类似于经典的 CollectionType，但具有更多选项：例如

    use Arkounay\Bundle\UxCollectionBundle\Form\UxCollectionType;
    
    // ...
    
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            // ...
            ->add('myCollection', UxCollectionType::class, [
                'entry_type' => MyEntryType::class,
                'allow_add' => true,
                'allow_delete' => true,
                'allow_drag_and_drop' => true,
                'drag_and_drop_filter' => 'input,textarea,a,button,label',
                'display_sort_buttons' => true,
                'add_label' => 'Add an item',
                'min' => 3,
                'max' => 10,
            ])
        ;
    }

选项

allow_add：将显示添加按钮（默认为 true）
allow_delete：将显示删除按钮（默认为 true）
allow_drag_and_drop：将允许用户使用拖放更改项目位置（默认为 true）
drag_and_drop_filter：当允许拖放时，选择器不会导致拖放（默认为 true）
drag_and_drop_prevent_on_filter：当允许拖放时，当触发 filter 时调用 event.preventDefault()（默认为 false）
display_sort_buttons：将显示向上和向下箭头按钮以更改项目位置（默认为 true）
display_insert_button：将在每个集合项目下方显示插入按钮（例如，项目可以插入到集合的中间），只有当 allow_add 设置为 true 时才显示（默认为 false）
add_label：添加按钮标签（默认为 "添加"）
insert_label：插入按钮标签（默认为 "插入"）
add_wrapper_class：用于添加按钮包装器的类（默认为 "mb-3"）
add_class：用于添加按钮的类（默认为 "btn btn-outline-secondary collection-add"）
insert_class：用于插入按钮的类（默认为 "btn btn-outline-secondary btn-collection-insert collection-add"）
position_selector：如果指定了 DOM 选择器，并且它指向位于集合项目内部的输入，则将更改此输入的值并插入其当前位置（从 0 开始）而不是更改输入的名称。（例如：'.position'）
min：集合中的最小项目数。当集合在创建时将 allow_add 设置为 true 并且项目少于 min 时，将添加空项目，并直到创建了更多项目，删除按钮将保持隐藏。（默认为 1）
max：集合中的最大项目数。当集合达到最大项目数时，将隐藏添加按钮。（默认为 null - 无限制）

嵌套集合

当使用嵌套集合时，请记住更改子集合的 prototype_name。它需要与父集合不同（默认为 __name__）
如果父集合和子集合都使用 position_selector，请确保它们不同

扩展默认行为

UxCollection 允许您使用自定义 Stimulus 控制器扩展其默认行为，例如 custom_collection_controller.js

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

export default class extends Controller {
    
    connect() {
        this.element.addEventListener('ux-collection:connect', this._onConnect);
        this.element.addEventListener('ux-collection:change', this._onChange);
        this.element.addEventListener('ux-collection:add', this._onAdd);
        this.element.addEventListener('ux-collection:remove', this._onRemove);
    }

    disconnect() {
        this.element.removeEventListener('ux-collection:connect', this._onConnect);
        this.element.removeEventListener('ux-collection:change', this._onChange);
        this.element.removeEventListener('ux-collection:add', this._onAdd);
        this.element.removeEventListener('ux-collection:remove', this._onRemove);
    }

    _onConnect() {
        console.log('The custom collection was just created');
    }

    _onChange() {
        console.log('The custom collection changed');
    }

    _onAdd(event) {
        console.log('An element was added', event.detail);
    }

    _onRemove(event) {
        console.log('An element was removed', event.detail);
    }
    
}

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

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder
        // ...
        ->add('collection', UxCollectionType::class, [
            'attr' => ['data-controller' => 'custom-collection']
        ])
        // ...
    ;
}

监听父 stimulus 控制器的更改

如果您有一个父级刺激控制器，并想监控集合（例如更新项目总数或调整购物车中的价格）的变化，您可以使用ux-collection:change派发事件，并直接调用父级控制器的函数。例如，如果您有一个名为parent的刺激控制器，该控制器使用onCollectionChange方法包装集合，则当您在表单中添加适当的动作时，它将被调用。

$builder->add('collection', UxCollectionType::class, [
    // ...
    'attr' => ['data-action' => 'ux-collection:change->parent#onCollectionChange']
]);

关于文件输入的说明

如果您的集合包含文件输入，根据您如何使用FileType（例如，如果您使用VichUploaderBundle的集合），在添加/删除/移动项目时可能会出现问题，这些问题与定位方式有关。使用position_selector选项来修复此问题，或者通过将allow_drag_and_drop和display_sort_buttons设置为false来禁用排序：这样表单名称就不会改变。

EasyAdmin集成

对于easyadmin 3+，您需要手动指定表单主题，通过在您的DashboardController中覆盖configureCrud来添加主题@ArkounayUxCollection/ux_collection_form_theme.html.twig

public function configureCrud(): Crud
{
    return Crud::new()->addFormTheme('@ArkounayUxCollection/ux_collection_form_theme.html.twig');
}

您需要配置您的管理器以使用WebpackEncore，以便将Symfony UX考虑在内，例如

public function configureAssets(Assets $assets): Assets
{
    return parent::configureAssets($assets)
        ->addWebpackEncoreEntry('app');
}

QAG集成

该组件已包含在QAG中，并可直接使用。

额外集合类型

还有用于需要水平移动的集合的UxHorizontalCollectionType，以及创建标签类型集合的UxTabbedCollectionType（目前仅在项目中使用bootstrap时有效，并且您可能需要覆盖一些基本CSS - 这里有一个QuickAdminGeneratorBundle集成示例）。

arkounay / ux-collection

维护者

详细信息