README

依赖选择框

为nette/forms提供，具有naja客户端扩展的依赖选择框组件。

特性

• 严格的类型
• 在任何表单上工作，无需自定义渲染器（无需片段）
• 支持表单容器（无限深度，适用于选择框及其父级）
• 由TypeScript和Naja提供客户端支持，可触发事件以便您可以附加监听器
• 条件父级（当某些其他控件具有特定值时，使表单控件成为选择框的父级）

安装

使用Composer获取Nette表单组件

composer require wavevision/dependent-selectbox

通过Yarn安装客户端

yarn add @wavevision/dependent-selectbox

或npm

npm install --save @wavevision/dependent-selectbox

用法

服务器端

创建一个将成为Wavevision\DependentSelectBox\Form\Form实例的表单。

如果您不想或不能从我们的基类继承，只需确保您创建的表单使用Wavevision\DependentSelectBox\Form\DependentForm特性。

您的表单还应使用Wavevision\DependentSelectBox\Form\DependentContainer，以便其容器也扩展为依赖选择框，但如果您已经有了自己的Nette\Forms\Container实现，只需确保容器使用Wavevision\DependentSelectBox\Form\DependentControl特性。

之后，您的表单及其容器将通过addDependentSelectBox方法进行扩展。此方法接受以下参数

该方法返回一个Wavevision\DependentSelectBox\DependentSelectBox实例。

使用表单的推荐方式是在Control组件中使用。

use Nette\Application\UI\Control;
use Nette\Application\UI\Presenter;
use Wavevision\DependentSelectBox\DependentComponent;
use Wavevision\DependentSelectBox\DependentData;
use Wavevision\DependentSelectBox\DependentValues;
use Wavevision\DependentSelectBox\Form\Form;

class FormComponent extends Control
{

    // add 'loadDependenData' signal and a few utilities
    use DependentComponent;

    public function __construct()
    {
        $this->monitor(Presenter::class, function (): void {
            // setup form in component - optionally pass form name (default 'form')
            $this->dependentComponentSetup();
            if ($this->hasReceivedDependentSignal()) {
                // if 'loadDependenData' signal received, do anything extra we need
            }
        });
    }

    protected function createComponentForm(): Form
    {
        // create your form as you are used to
        $form->addDependentSelectBox('name', 'Label', $form['someParentControl'])
            ->setDependentCallback(function (DependentValues $values): DependentData {
                // get ArrayHash values, if you perfer array, use getRawValues
                $formattedValues = $values->getValues();
                $data = new DependentData();
                if ($formattedValues->someParentControl === 'someDependentValue') {
                    $data->setItems(['firstItem' => 'firstValue']);
                }
                return $data;
            })
            // make the select box disabled when no values have been loaded
            ->setDisabledWhenEmpty()
            // if loaded values contain only one item, select it so the user does not have to
            ->setAutoSelectSingleValue()
            // if 'someOtherControl' has 'someValue', treat 'someControl' as parent
            ->addConditionalParent($form['someControl'], $form['someOtherControl'], 'someValue');
        // add form handlers etc.
        return $form;
    }
}

注意：您也可以在Presenter中使用表单，唯一的限制是您在每个页面上只能有一个依赖表单，如下所示。如果您将表单包裹在组件中（每个都使用DependentComponent特性），那么您就可以在单个页面上使用尽可能多的表单。

客户端

有多种方法将客户端集成到您的项目中。

1. 将依赖选择框注册为Naja扩展

import naja from 'naja';
import DependentSelectBox from '@wavevision/dependent-selectbox';

naja.registerExtension(new DependentSelectBox());
// add other extensions, initialize etc.

如特性中所述，扩展会发出您可以附加监听器的事件。

这两个事件监听器都会收到一个包含detail的CustomEvent对象，其中具有以下属性

第一个事件还包含request属性，它是一个包含以下内容的对象

后者包含一个包含以下内容的response对象，其中的键是更新选择框的HTML id属性，值是包含以下属性的对象

请参阅Naja文档以获取有关其扩展的更多信息。

2. 导入包含Naja的捆绑版本

如果您在其他地方的项目中不使用Naja并且不想设置它，这是您的选择。

⚠️ 警告：如果使用，这可能与其他Nette AJAX库冲突！

import '@wavevision/dependent-selectbox/dist/dependentSelectBox.all';

3. 在script标签中直接使用它

仅适用于老式人士 😎。

<script src="/path/to/assets/dependentSelectBox.all.js"></script>