README

UX autoComplete.js 是一个将autoComplete.js库集成到 Symfony 应用中的 Symfony 扩展包。它是 Symfony UX 创新项目的一部分。

安装

UX autoComplete.js 需要 PHP 7.4+ 和 Symfony 4.4+。

使用 Composer 和 Symfony Flex 安装此扩展包

composer require kreemer/ux-autocomplete-js

# Don't forget to install the JavaScript dependencies as well and compile
yarn install --force
yarn encore dev

同时确保你的 package.json 文件中至少有版本 2.0 的 @symfony/stimulus-bridge。

使用方法

要使用此 UX 包，请注入 AutoCompleteBuilderInterface 服务并在 PHP 中创建一个 autoComplete 模型

// ...
use Kreemer\UX\AutoCompleteJS\Builder\AutoCompleteBuilderInterface;

class IndexController extends AbstractController
{
    /**
     * @Route("/", name="homepage")
     */
    public function index(AutoCompleteBuilderInterface $autoCompleteBuilder): Response
    {
        $autoComplete = $autoCompleteBuilder->createAutocomplete();
        $autoComplete->getDataModel()->setSrc([ 'here', 'are', 'the', 'options']);

        return $this->render('index/index.html.twig', [
            'autoComplete' => $autoComplete,
        ]);
    }
}

所有选项和数据都直接提供给 autoComplete.js。你可以阅读 autoComplete.js 文档 以了解所有选项。

一旦在 PHP 中创建，可以使用 Twig 显示 autoComplete 模型

{{ render_autocomplete(autoComplete) }}

{# You can pass HTML attributes as a second argument to add them on the <div> tag #}
{{ render_autocomplete(autoComplete, {'class': 'my-class'}) }}

表单类型

该扩展包提供了一个自定义表单类型，可以像使用 EntityType 一样使用。

$form = $this->createFormBuilder($array)
    ->add('user', AutoCompleteType::class, [
        'class' => User::class,
        'choice_label' => 'name',
    ])
    ->add('save', SubmitType::class, ['label' => 'Submit'])
    ->getForm();

表单本身将自动渲染一个输入框，可以选择实体类。

扩展默认行为

控制器允许你使用自定义 Stimulus 控制器扩展其默认行为

// custom_controller.js

import { Controller } from 'stimulus';

export default class extends Controller {
    connect() {
        this.element.addEventListener('autocomplete:pre-connect', this._onPreConnect);
        this.element.addEventListener('autocomplete:connect', this._onConnect);
        this.element.addEventListener('autocomplete:bound', this._onBound);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side effects
        this.element.removeEventListener('autocomplete:pre-connect', this._onPreConnect);
        this.element.removeEventListener('autocomplete:connect', this._onConnect);
        this.element.removeEventListener('autocomplete:bound', this._onBound);
    }

    _onPreConnect(event) {
        console.log(event.detail.config);
    }

    _onConnect(event) {
        console.log(event.detail.autoCompleteJS); // You can access the instance here
    }
    
    _onBound(event) {
        console.log(event.detail.dataTarget); // You can access data holder here
    }
}

然后在你的渲染调用中，将你的控制器作为 HTML 属性添加

{{ render_autocomplete(autoComplete, {'data-controller': 'custom'}) }}

这是扩展默认功能的首选方法。注意，使用 preConnect 事件，可以附加处理程序和回调函数。

运行测试

PHP 测试

php vendor/bin/phpunit

JavaScript 测试

cd Resources/assets
yarn test