README

支持 alpha 通道的 WordPress 自定义主题颜色控制。

这是一个使用 react-color 颜色选择器的自定义主题控制。

根据所选颜色的不透明度，控制将保存为 HEX 值（如 #000000）或 RGBA（如 rgba(0,0,0,0.9)）。如果颜色完全不透明，则保存为 HEX 值。如果所选颜色不是完全不透明（alpha 值小于 1），则保存为 RGBA。

使用方法

注册控制

这是一个包含 JS 模板的控制。因此，它应该在自定义主题中列出白名单。为此，我们可以使用 WP_Customize_Manager::register_control_type 方法

add_action( 'customize_register', function( $wp_customize ) {
	$wp_customize->register_control_type( '\WPTRT\Customize\Control\ColorAlpha' );
} );

使用上述代码注册控制后，我们可以在自定义主题中使用它，使用 自定义主题 API

use \WPTRT\Customize\Control\ColorAlpha;

add_action( 'customize_register', function( $wp_customize ) {

	$wp_customize->add_setting( 'your_setting_id' , [
		'default'           => 'rgba(0,0,0,0.5)', // Use any HEX or RGBA value.
		'transport'         => 'refresh',
		'sanitize_callback' => 'my_custom_sanitization_callback'
	] );
	$wp_customize->add_control( new ColorAlpha( $wp_customize, 'your_setting_id', [
		'label'      => __( 'My Color', 'mytheme' ),
		'section'    => 'my_section',
		'settings'   => 'your_setting_id',
	] ) );
} );

可用过滤器

wptrt_color_picker_alpha_url

您可以使用此过滤器更改控制资源的 URL。默认情况下，控制将针对安装在 wp-content/themes 和 wp-content/plugins 的任何插件和主题正常工作。但是，您可以使用 wptrt_color_picker_alpha_url 过滤器更改 URL。

add_filter( 'wptrt_color_picker_alpha_url', function() {
	return get_template_directory_uri() . '/vendor/wptrt/control-color-alpha';
} );

清理

WordPress 自定义主题中的所有控制都应定义一个 sanitize_callback。您可以编写自己的函数并将其用作清理回调，或使用下面的示例函数。

/**
 * Sanitize colors.
 *
 * @since 1.0.0
 * @param string $value The color.
 * @return string
 */
function my_custom_sanitization_callback( $value ) {
	// This pattern will check and match 3/6/8-character hex, rgb, rgba, hsl, & hsla colors.
	$pattern = '/^(\#[\da-f]{3}|\#[\da-f]{6}|\#[\da-f]{8}|rgba\(((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*,\s*){2}((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*)(,\s*(0\.\d+|1))\)|hsla\(\s*((\d{1,2}|[1-2]\d{2}|3([0-5]\d|60)))\s*,\s*((\d{1,2}|100)\s*%)\s*,\s*((\d{1,2}|100)\s*%)(,\s*(0\.\d+|1))\)|rgb\(((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*,\s*){2}((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*)|hsl\(\s*((\d{1,2}|[1-2]\d{2}|3([0-5]\d|60)))\s*,\s*((\d{1,2}|100)\s*%)\s*,\s*((\d{1,2}|100)\s*%)\))$/';
	\preg_match( $pattern, $value, $matches );
	// Return the 1st match found.
	if ( isset( $matches[0] ) ) {
		if ( is_string( $matches[0] ) ) {
			return $matches[0];
		}
		if ( is_array( $matches[0] ) && isset( $matches[0][0] ) ) {
			return $matches[0][0];
		}
	}
	// If no match was found, return an empty string.
	return '';
}

高级使用方法

此控制允许您将值保存为 string 或 array。默认行为是保存为 string，但您可以通过使用控制中的 choices 参数轻松更改它。

$wp_customize->add_control( new ColorAlpha( $wp_customize, 'your_setting_id', [
	'label'    => __( 'My Color', 'mytheme' ),
	'section'  => 'my_section',
	'settings' => 'your_setting_id',
	'choices'  => [
		'save_as' => 'array',
	]
] ) );

值将使用以下格式保存

[
	'r'    => 107, // Red.
	'g'    => 55, // Green.
	'b'    => 119, // Blue.
	'h'    => 289, // Hue.
	's'    => 37, // Saturation.
	'l'    => 34, // Lightness.
	'a'    => 0.82, // Alpha
	'hex'  => '#6b3777', // The HEX code of the color (alpha = 1)
	'css'  => 'rgba(107,55,119,0.82)', // The CSS value of the selected color.
	'a11y' => [ // An array of accessibility-related properties.
		'luminance'                         => 0.0719,
		// Contrast with white (value 0 - 21).
		'distanceFromWhite'                 => 8.613,
		// Contrast with black (value 0 - 21).
		'distanceFromBlack'                 => 2.438,
		// Maximum contrasting color. Use this to get the text-color
		// if the colorpicker is used to select a background-color.
		'maxContrastColor'                  => '#ffffff',
		// Readable text-colors on white background preserving the hue.
		// The 1st value has a minimum contrast of 7:1 with white.
		// The 2nd value has a minimum contrast of 4.5:1 with white.
		'readableContrastingColorFromWhite' => [ '#6b3777', '#6b3777' ],
		// Readable text-colors on black background preserving the hue.
		// The 1st value has a minimum contrast of 7:1 with black.
		// The 2nd value has a minimum contrast of 4.5:1 with black.
		'readableContrastingColorFromBlack' => [ '#bc83c7', '#a458b5' ],
		// True if the color is dark.
		'isDark'                            => true
	],
]

数组清理

如果您选择将此控制的值保存为 array，则需要更改此设置的清理函数。您可以编写自己的，或者使用下面的一个。

/**
 * Sanitize colors.
 *
 * @since 1.0.0
 * @param array $value The color.
 * @return array
 */
function my_custom_sanitization_callback( $value ) {
	return [
		'r' => (int) $value['r'],
		'g' => (int) $value['g'],
		'b' => (int) $value['b'],
		'h' => (int) $value['h'],
		's' => (int) $value['s'],
		'l' => (int) $value['l'],
		'a' => (float) $value['a'],

		'hex' => my_custom_color_string_sanitization_callback( $value['hex'] ),
		'css' => my_custom_color_string_sanitization_callback( $value['css'] ),

		'a11y' => [
			'luminance'         => (float) $value['a11y']['luminance'],
			'distanceFromWhite' => (float) $value['a11y']['distanceFromWhite'],
			'distanceFromBlack' => (float) $value['a11y']['distanceFromBlack'],
			'maxContrastColor'  => my_custom_color_string_sanitization_callback( $value['a11y']['maxContrastColor'] ),
			'isDark'            => (float) $value['a11y']['isDark'],

			'readableContrastingColorFromWhite' => [
				my_custom_color_string_sanitization_callback( $value['a11y']['readableContrastingColorFromWhite'][0] ),
				my_custom_color_string_sanitization_callback( $value['a11y']['readableContrastingColorFromWhite'][1] ),
			],
			'readableContrastingColorFromBlack' => [
				my_custom_color_string_sanitization_callback( $value['a11y']['readableContrastingColorFromBlack'][0] ),
				my_custom_color_string_sanitization_callback( $value['a11y']['readableContrastingColorFromBlack'][1] ),
			]
		]
	];
}

/**
 * Sanitize colors.
 *
 * @since 1.0.0
 * @param string $value The color.
 * @return string
 */
function my_custom_color_string_sanitization_callback( $value ) {
	// This pattern will check and match 3/6/8-character hex, rgb, rgba, hsl, & hsla colors.
	$pattern = '/^(\#[\da-f]{3}|\#[\da-f]{6}|\#[\da-f]{8}|rgba\(((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*,\s*){2}((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*)(,\s*(0\.\d+|1))\)|hsla\(\s*((\d{1,2}|[1-2]\d{2}|3([0-5]\d|60)))\s*,\s*((\d{1,2}|100)\s*%)\s*,\s*((\d{1,2}|100)\s*%)(,\s*(0\.\d+|1))\)|rgb\(((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*,\s*){2}((\d{1,2}|1\d\d|2([0-4]\d|5[0-5]))\s*)|hsl\(\s*((\d{1,2}|[1-2]\d{2}|3([0-5]\d|60)))\s*,\s*((\d{1,2}|100)\s*%)\s*,\s*((\d{1,2}|100)\s*%)\))$/';
	\preg_match( $pattern, $value, $matches );
	// Return the 1st match found.
	if ( isset( $matches[0] ) ) {
		if ( is_string( $matches[0] ) ) {
			return $matches[0];
		}
		if ( is_array( $matches[0] ) && isset( $matches[0][0] ) ) {
			return $matches[0][0];
		}
	}
	// If no match was found, return an empty string.
	return '';
}

自动加载

您需要使用自动加载器。理想情况下，这将是一个 Composer。但是，我们有一个 基本的自动加载器 可供主题使用。

Composer

从命令行

composer require wptrt/control-color-alpha

WPTRT 自动加载器

如果您使用 WPTRT 自动加载器，请使用以下代码

include get_theme_file_path( 'path/to/autoload/src/Loader.php' );

$loader = new \WPTRT\Autoload\Loader();
$loader->add( 'WPTRT\\Customize\\Control', get_theme_file_path( 'path/to/control-color-alpha/src' ) );
$loader->register();