README

WP 设置

此包旨在使创建WordPress插件的设置页面更容易。通常，您会使用设置API 或编写自定义代码。虽然设置API是有效的，但仍然需要设置很多东西。例如，您仍然需要编写您选项的HTML。如果您想添加选项卡和选项卡部分，它会变得相当复杂。请参阅此比较。

安装

composer require jeffreyvanrossum/wp-settings

使用方法

基本示例

use Jeffreyvr\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'
    ]
]);

多选

$section->add_option('select-multiple', [
    '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 Jeffreyvr\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')
]);

贡献者

许可

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

jeffreyvanrossum / wp-settings

维护者

详细信息