README

提供链式选择控件。

将 chainedselect 字段类型添加到 Carbon Fields。使用 Composer 安装

composer require "iamntz/carbon-chained-select:^3.0"

对于 Carbon Fields 2（旧版本）

composer require "iamntz/carbon-chained-select:^2.0"

add_option 数组结构

基本上这是一个包含几个 魔法 关键词的多维数组。这些关键词是：__label__、__config__。

可以使用 carbon_chained_select_config 过滤器更改这些键中的任何一个，甚至更进一步，通过 carbon_chained_select_config/name=field-name 过滤器。

->add_options([
  '__label__' => 'Select 1', // field label

  'value1' => 'Option Text 1',
  'value2' => 'Option Text 2',

  'value3_nested' => [
    '__label__' => 'Select 2 (nested)', // option text AND next field label

    'select-2-1-1' => 'Option text 2 - 1',
    'select-2-1-2' => 'Option text 2 - 2',

    "select-2-1-3" => [
      '__label__' => 'Select 3 (nested, with remote)', // option text and 3rd level field label

      '__config__' => [
        'multiple' => true,
        'endpoint' => '/wp-json/namespace/v2/chained-select',
      ],
    ],
  ],
]);

或者，您可以将所有与配置相关的项移动到 __config__ 数组中

->add_options([
  '__config__' => [
    'label' => 'Select 1', // field label
  ]

  'value1' => 'Option Text 1',
  'value2' => 'Option Text 2',

  'value3_nested' => [
    '__label__' => 'Select 2 (nested)', // option text AND next field label

    'select-2-1-1' => 'Option text 2 - 1',
    'select-2-1-2' => 'Option text 2 - 2',

    "select-2-1-3" => [
      '__config__' => [
        /**
         * By default, each nested item will be in an array that will look pretty much like this:
         * [
         *    'value3_nested' => value3_nested',
         *    'select-2-1-3' => select-2-1-3'
         * ]
         *
         * You can specify a name for each level, so you could have a multi-dimensional array, something like this:
         * [
         *  'value3_nested' => 'value3_nested',
         *  'last-level-name' => 'select-2-1-3'
         * ]
         *
         * If no `name` config key is provided, then the value name will be used. For consistency sake,
         * try to use one way or another, don't mix them. Also, please note that by NOT specifying a name,
         * you're stuck with the initial order. I.e. won't be able to reorder items without breaking existing data!
         *
         * So TL;DR: use a damn name!
         */
        'name' => 'last-level-name',

        // if you have a `label` key here, then the `__label__` key on an upper level will be ignored.
        'label' => 'Select 3 (nested, with remote)',

        // optional, is the label that will appear above `select` field. If not specified,
        // then the label above will be used as both option AND label
        'option_label' => '',

        // wether if the field can have multiple values or only one.
        // Please note that if a field is multiple, you can't have any further nested selects
        // you can try though, but the results are not predictible :)
        'multiple' => true,

        // REST endpoint to fetch new options. This should accept GET requests!
        // Params sent on the request:
        // {
        //    nonce: nonce, // checking for carbon_chained_select key
        //    value: value, // current select value
        //    fieldValue: field.value, // whole field value (as an array)
        //    name: name, // the field name
        //    query: query // if user searched something, it will be sent as this key
        // }
        //
        // The response should follow the same structure as this initial array,
        // parsed (read below) then sent as json
        'endpoint' => '/wp-json/namespace/v2/chained-select',
      ],
    ],
  ],
]);

内部将按需排列，因此您不必太担心。

对于 AJAX 调用，响应必须遵循相同的结构，但必须在发送之前进行解析

$parser = new \iamntz\carbon\chainedSelect\OptionsParser([
  'selectOptions' => $options // same structure as above!
], 'fieldName');

$parser->parse();

第二个参数 fieldName 是可选的，并且仅用于配置过滤器（即用于更改魔法关键词）。

限制

目前，您不能在通过 AJAX 获取的字段中同时使用链式和 AJAX。

因此，您可以像这样链字段

field > field > ajax > field > field

但是您 不能 以这种方式链字段

field > field > ajax > field > ajax

此外，您不能在同一个字段上同时使用多选和 AJAX。

返回值

返回的值是一个关联数组，遵循字段名称。

已知问题

• 您不能在 AJAX 选择之后有另一个嵌套字段。这可能 会 工作，但我没有测试。
• 您不能在多选选择之后有另一个嵌套字段。这在我的列表中 优先级非常低（主要是因为我认为这是一种用户体验噩梦）。
• 此字段的条件逻辑已损坏。这是由于我存储数据的方式造成的（作为 JSON 字符串）。虽然我想让它工作，但我必须找到时间深入研究 Carbon 字段的条件和逻辑。
• 未测试，但将字段设置为必填项应该会有与上述条件逻辑相同的问题。

如果您有任何修复方案，请发送 PR！

关于验证的特殊说明

Carbon 的选择字段（包括单选和多选）使用验证来确保用户无法选择在配置中不存在的选项。然而，考虑到源也可以是外部的（例如，通过 AJAX），这不能以合理可扩展的方式实现。

这很可能不会影响任何东西，但如果将来 Carbon 可以在前端使用，这 可能 成为一个滥用的大门。

支持我

您可以通过托管、捐赠或成为我的Patreon来支持我。

许可证

代码在 MIT 许可证下发布。