README

此软件包旨在简化创建WordPress插件设置页面的过程。通常，您会使用设置API或编写自定义代码。虽然设置API可以工作，但仍有大量设置工作要做。例如，您仍然需要编写您的选项的HTML代码。如果您想添加标签页和标签节，则更加复杂。请参阅此比较。

安装

composer require wordpressvn/wp-settings

用法

基本示例

use WPVNTeam\WPSettings\WPSettings;

$settings = new WPSettings(__('My Plugin Settings'));

$tab = $settings->add_tab(__( 'General', 'textdomain'));

$section = $tab->add_section('MailChimp');

$section->add_option('text', [
    'name' => 'mailchimp_api_key',
    'label' => __('API Key', 'textdomain')
]);

$settings->make();

创建设置实例

$settings = new WPSettings(__('My Plugin Settings'));

默认情况下，页面别名是通过清理标题创建的。您可以将特定的别名作为构造函数的第二个参数传递。

此类其他方法

$settings->set_capability('manage_options');
$settings->set_option_name('my_plugin_options');
$settings->set_menu_icon('dashicons-admin-generic');
$settings->set_menu_position(5);
$settings->set_menu_parent_slug('options-general.php');

标签页

只有当存在多个标签页时，才会显示标签页。

$settings->add_tab(__( 'General', 'textdomain'));

节

您可以从Tab实例调用add_section方法。您也可以从WPSettings实例调用它。然后，它将被添加到最后一个创建的Tab。

$tab->add_section('Section 1');

如果您想将节显示为子菜单项，您可以这样做

$tab->add_section('Section 1', ['as_link' => true]);

请注意，这仅在有多个as_link节时才有影响。

选项

要添加选项，您可以从Section实例调用add_option方法。您也可以从WPSettings实例调用add_option。然后，选项将被添加到最后创建的节。

文本

$section->add_option('text', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
]);

除了name和label之外，您还可以传递type。这使得可以将输入类型设置为，例如，密码或数字。

文本区域

$section->add_option('textarea', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain'),
]);

您还可以设置cols和rows属性。

复选框

$section->add_option('checkbox', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
]);

选择

$section->add_option('select', [
    'name' => 'option_1',
    'label' => __( 'Option 1', 'textdomain' ),
    'options' => [
        'value_1' => 'Label 1',
        'value_2' => 'Label 2'
    ]
]);

选择2

$section->add_option('select2', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain'),
    'options' => [
        'value_1' => 'Label 1',
        'value_2' => 'Label 2'
    ]
] );

WP编辑器

$section->add_option('wp-editor', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

代码编辑器

$section->add_option('code-editor', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

颜色

$section->add_option('color', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

媒体

$section->add_option('media', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

对于特定于图像，您可以这样做

$section->add_option('image', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

对于特定于视频，您可以这样做

$section->add_option('video', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

验证

您可以验证选项。您可以传递一个回调和一条反馈信息。您可以传递多个验证规则。

$section->add_option('text', [
    'name' => 'mailchimp_api_key',
    'label' => __('API Key', 'textdomain'),
    'validate' => [
        [
            'feedback' => __('Your API key is too short.', 'textdomain'),
            'callback' => function($value) {
                return strlen($value) > 35;
            }
        ]
    ]
]);

清理

您可以传递一个清理回调。

$section->add_option('text', [
    'name' => 'mailchimp_api_key',
    'label' => __('API Key', 'textdomain'),
    'santitize' => function($value) {
        return sanitize_key($value);
    }
]);

选项数组结构

默认情况下，选项存储为一维数组

[
    'option_1' => 'value 1',
    'option_2' => 'value 2',
]

然而，您可以在这种结构中添加标签页和/或节级别。

$tab = $settings->add_tab(__( 'General', 'textdomain'))
    ->option_level();

$section = $tab->add_section('Example', ['as_link' => true])
    ->option_level();

这将产生

[
    'general' => [
        'example' => [
            'option_1' => 'value 1',
            'option_2' => 'value 2',
        ]
    ]
]

添加自定义选项类型

要添加自定义选项类型，您可以使用wp_settings_option_type_map过滤器。

add_filter('wp_settings_option_type_map', function($options){
    $options['custom'] = YourCustomOption::class;
    return $options;
});

您需要为您的自定义选项类型创建一个类。

use WPVNTeam\WPSettings\Options\OptionAbstract;

class YourCustomOption extends OptionAbstract
{
    public $view = 'custom-option';

    public function render()
    {
        echo 'Your custom option HTML';
    }
}

一旦注册，您就可以像这样使用您的选项类型

$settings->add_option('custom-option', [
    'name' => 'your_option_name',
    'label' => __('Your label')
]);

贡献者

Jeffrey van Rossum

许可证

MIT。有关更多信息，请参阅许可证文件。

wordpressvn /wp-settings

维护者

详细信息