【WP学习】使用 Widgets API 自定义后台选项

115资源网 2022年5月11日 实用教程, 技术分享 浏览：44 0

WordPress 可以将一些常用的模块封装成一个个的小工具，并供给对应的装备选项，这样咱们可以通过拖拽的方法自界说摆放各种小工具完结网页的规划。Widgets API 便是用于用户自界说小工具的一个类，该 API 界说在 wp-includes/widgets.php 文件下。常用的方法主要有：

  • register_sidebar()：注册一个小工具侧栏。
  • unregister_sidebar()：卸载一个小工具侧栏。
  • is_registered_sidebar()：判别某个小工具能否从前注册。
  • dynamic_sidebar()：前端闪现指定的小工具。
  • is_dynamic_sidebar()：判别主题能否启用了小工具功用。
  • is_active_sidebar()：判别某个小工具侧栏能否被激活（能否添加了小工具）。
  • register_widget()：注册一个小工具（留心不是侧栏方位）。
  • unregister_widget()：卸载一个小工具。
  • is_active_widget()：判别某个小工具能否被激活运用。

register_sidebar()

WordPress 默许是不闪现小工具的，咱们需求通过 register_sidebar() 注册一个侧栏方位，小工具功用才会闪现。

register_sidebar( array|string $args = array() )

$args: 数组，用于装备小工具参数。

  • id：字符串，后台小工具侧栏方位的独一辨认 ID 。
  • name：字符串，后台小工具侧栏方位的标题称谓。
  • description：字符串，后台小工具侧栏方位的描绘信息，一般不必。
  • before_sidebar：字符串，HTML 标签内容，闪现在 sidebar 输出的前面，默许为空，一般不必。
  • after_sidebar：字符串，HTML 标签内容，闪现在 sidebar 输出的后面，默许为空，一般不必。
  • before_widget：字符串，HTML 标签内容，闪现在 widget 输出的前面，自界说小工具时可通过 $before_widget 引用。
  • after_widget：字符串，HTML 标签内容，闪现在 widget 输出的结尾，自界说小工具时可通过 $after_widget 引用。
  • before_title：字符串，HTML 标签内容，闪现在 widget 输出的标题前面，自界说小工具时可通过 $before_title 引用。
  • after_title：字符串，HTML 标签内容，闪现在 widget 输出的标题后面，自界说小工具时可通过 $after_title 引用。

简略地说，register_sidebar 界说一个方位，咱们通过 dynamic_sidebar 操控其在网页的哪个方位闪现，Sidebar 里可以放置多个 Widget ，before_sidebar、after_sidebar、before_widget、after_widget、before_title、after_title 可以预界说一段 HTML 代码，这些代码可以在咱们自界说小工具的时分直接引用，这样在输出小工具内容时，预界说的 HTML 代码会主动烘托。一般情况下一个网站会界说多个侧栏方位，界说方法如下：

// 自界说侧栏方位
if ( !function_exists(\'diy_register_sidebar\') ) {
	function diy_register_sidebar(){
		$sidebars = array(
			\'diy_sidebar\'           => \'自界说侧栏方位01\',
            \'diy_sidebar_2\'         => \'自界说侧栏方位02\',
		);
		foreach ( $sidebars as $key => $value ) {
			register_sidebar(array(
				\'id\'            => $key,
				\'name\'          => $value,
				\'before_widget\' => \'
\',    // 闪现在整个小工具前面
				\'after_widget\'  => \'
\',    // 闪现在整个小工具后面
				\'before_title\'  => \'
\',    // 闪现在小工具标题前面
				\'after_title\'   => \'
\'    // 闪现在小工具标题后面
			));
		};
	}
	add_action( \'widgets_init\', \'diy_register_sidebar\' );
}

注册完结后闪现如下：

unregister_sidebar()

注册的小工具假设不需求了，可以通过 unregister_sidebar 取消注册。

unregister_sidebar( string $id )

$id：字符串，后台小工具侧栏方位的独一辨认 ID 。

is_registered_sidebar()

判别小工具能否注册了，避免反复注册或许引起的错误，回来布尔值。

is_registered_sidebar( string $id )

$id：字符串，后台小工具侧栏方位的独一辨认 ID 。

dynamic_sidebar()

在前端页面闪现指定小工具方位内的全部小工具。

dynamic_sidebar( int|string $index = 1 )

$index：整型或字符串，默许闪现索引为 1 的侧栏方位下的小工具，假设注册侧栏方位时指定了 id 或许 name 属性，则可以传入指定的 id 或 name 值用来闪现特定的侧栏。

is_dynamic_sidebar()

判别主题能否启用或许运用了小工具功用，不需求传送参数，主题扩展功用时判别一下避免错误，回来布尔值。

is_dynamic_sidebar()

is_active_sidebar()

判别主题中某个注册了的侧栏能否从前激活运用（能否添加了小工具），回来布尔值。比如：咱们可以用它判别用户能否运用了某个侧栏，进而调整网页规划。

is_active_sidebar( string|int $index )

$index：整型或字符串，注册时用到的侧栏 id 或许 name 属性。

unregister_widget()

默许的小工具无论是样式还是功用上常常不能满意咱们的运用，所以一般情况下需求将默许小工具卸载掉，然后自界说一下主题中用到的小工具。

unregister_widget( string|WP_Widget $widget )

$widget：一个 WP_Widget 实例，或许 WP_Widget 的类名。

// 卸载全部默许小工具
if ( !function_exists(\'diy_unregister_widget\')) {
	function diy_unregister_widget(){
		unregister_widget(\'WP_Widget_Pages\');
		unregister_widget(\'WP_Widget_Calendar\');
		unregister_widget(\'WP_Widget_Archives\');
		unregister_widget(\'WP_Widget_Links\');
		unregister_widget(\'WP_Widget_Media_Audio\');
		unregister_widget(\'WP_Widget_Media_Image\');
		unregister_widget(\'WP_Widget_Media_Video\');
		unregister_widget(\'WP_Widget_Media_Gallery\');
		unregister_widget(\'WP_Widget_Meta\');
		unregister_widget(\'WP_Widget_Search\');
		unregister_widget(\'WP_Widget_Text\');
		unregister_widget(\'WP_Widget_Categories\');
		unregister_widget(\'WP_Widget_Recent_Posts\');
		unregister_widget(\'WP_Widget_Recent_Comments\');
		unregister_widget(\'WP_Widget_RSS\');
		unregister_widget(\'WP_Widget_Tag_Cloud\');
		unregister_widget(\'WP_Nav_Menu_Widget\');
		unregister_widget(\'WP_Widget_Custom_HTML\');
	}
	add_action(\'widgets_init\', \'diy_unregister_widget\');
}

register_widget()

运用该方法可以注册一个小工具，闪现在 WordPress 小工具面板下，但是在注册前需求先界说一个小工具类，关于这部分的内容放在最终，这里只展示下注册方法及注册后的成果。

register_widget( string|WP_Widget $widget )

$widget：一个 WP_Widget 实例，或许 WP_Widget 的类名。

is_active_widget()

判别某个小工具能否从前在前端闪现，避免反复闪现惹起的排版错误，回来布尔值或指定小工具的 ID 。

is_active_widget( callable|false $callback = false, int|false $widget_id = false, string|false $id_base = false, bool $skip_inactive = true )
  • $callback：回调或 false ，要查看的小工具回调函数，默许：false。
  • widget_id：整型或 false ，要查看的小工具 ID ，默许：false。
  • id_base：字符串或 false，通过 WP_Widget 类扩展创建的小工具的根本 ID ，默许：false。
  • skip_inactive：布尔值，能否在 ‘wp_inactive_widgets’ 中查看，默许：true。

界说一个小工具

好吧，这才是重中之重。创建小工具实则是创建一个对 WP_Widget 类库的集成，并装备相应的内容。WP_Widget 类界说在 wp-includes/class-wp-widget.php 文件中。一个常见的自界说小工具包含 __construct()、form()、update()、widget() 四部分。

  • __construct()：小工具的根本属性装备。
  • form()：小工具后台装备选项。
  • update()：更新小工具设置。
  • widget()：小工具前端输出内容。

__construct()

PHP 5 新增的结构方法，用于在创建一个实例之前传入相应的参数装备实例。这里传入小工具的根本装备信息，这个方法必需装备，不装备会报错。

WP_Widget::__construct( string $id_base, string $name, array $widget_options = array(), array $control_options = array() )
  • $id：字符串，可选，小工具的独一 ID 值，需为小写，为空则主动运用小工具类名。
  • $name：字符串，可选，小工具的称谓，便是后台装备页的标题称谓。
  • $widget_options：数组，可选小工具的装备项，与 wp_register_sidebar_widget 方法中的 options 选项分歧。
    • classname：字符串，小工具输出外层 HTML 标签的类名，默许值为输出回调称谓的缩写。
    • description：字符串，小工具后台装备面板的描绘信息。
  • $control_options：数组，可选，小工具的操控项，与 wp_register_widget_control 方法中的 options 选项分歧，一般不必。
    • height：整型，后台小工具的高度，一般不必，默许 200 。
    • width：整型，后台小工具的宽度，默许 250 。
    • id_base：整型或字符串，小工具的基准 ID ，多窗口小工具必需运用，运用后小工具 ID 值变为 {ParseError: KaTeX parse error: Expected ‘EOF’, got ‘}’ at position 8: id_base}̲-{unique_number} 。

示例：

// 小工具初始化
public function __construct(){
	parent::__construct( \'diy_widget\', __(\'自界说小工具\', \'textdomain\'), array(
		\'classname\'  => \'diy-widget-class\',
		\'description\'=> \'自界说小工具描绘\'
	));
}

form()

一般的小工具都会供给后台装备选项，这些装备选项在 form() 方法中装备。常用的控件类型包含：文本、单选按钮、复选框、下拉挑选、下拉菜单、链接、数字等。

WP_Widget::form( array $instance )

$instanse：数组，小工具当时的装备。
form() 方法的回来值为字符串类型，默许为 noform 。

示例：

// 后台设置表单
public function form($instance){
	$defaults = array(
		\'text\'        => \'默许单行文本控件的值\',
		\'textarea\'    => \'默许多行文本控件的值\',
		\'radio\'       => \'默许选中的按钮值\',
		\'checkbox\'    => \'on\',
		\'select\'      => \'selectOpt2\',
		\'nav_menu\'    => 0,
		\'number\'      => 5,
		\'link\'        => \"https://blog.quietguoguo.com\"
	);
	
	
	$instance = wp_parse_args( (array) $instance, $defaults );   // 将用户界说的参数兼并到默许数组中去
	extract($instance);    // 从数组中将变量导入到当时的符号表
	?>
	
	

		<label for=\"get_field_id( \'text\' ); ?>\">
			
		
		<input type=\"text\" id=\"get_field_id(\'text\'); ?>\" name=\"get_field_name(\'text\'); ?>\" value=\"\" class=\"text\">
		
	

	
	

		<label for=\"get_field_id( \'textarea\' ); ?>\">
			
		
		<textarea  id=\"get_field_id(\'textarea\'); ?>\" name=\"get_field_name(\'textarea\'); ?>\" rows=\"3\" cols=\"20\">
	

	
	

		<input type=\"radio\" id=\"radio-1\" name=\"get_field_name( \'radio\' ); ?>\"  value=\"默许选中的按钮值\" class=\"radio\" />
		
		

		<input type=\"radio\" id=\"radio-2\" name=\"get_field_name( \'radio\' ); ?>\"  value=\"默许未选中的按钮值\" class=\"radio\" />
		
	

	
	

		<input type=\"checkbox\" id=\"get_field_id( \'checkbox\' ); ?>\" name=\"get_field_name( \'checkbox\' ); ?>\"  class=\"checkbox\" />
		<label  for=\"get_field_id( \'checkbox\' ); ?>\">
			
		
	

	
	

		<label for=\"get_field_id( \'select\' ); ?>\">
			
		
		<select id=\"get_field_id( \'select\' ); ?>\" name=\"get_field_name( \'select\' ); ?>\">
			<option value =\"selectOpt1\" >下拉挑选值1
			<option value =\"selectOpt2\" >下拉挑选值2
			<option value =\"selectOpt3\" >下拉挑选值3
		
	

	
	
	

		<label for=\"get_field_id( \'nav_menu\' ); ?>\">
			
		
		<select id=\"get_field_id( \'nav_menu\' ); ?>\" name=\"get_field_name( \'nav_menu\' ); ?>\">
			
			
				<option value=\"term_id ); ?>\" term_id ); ?>>
					name ); ?>
				
			
		
	

	
	

		<label for=\"get_field_id( \'number\' ); ?>\">
		<input type=\"number\" id=\"get_field_id( \'number\' ); ?>\" name=\"get_field_name( \'number\' ); ?>\" step=\"1\" min=\"1\" value=\"\" size=\"3\" class=\"tiny-text\" />
	

	
	

		<label for=\"get_field_id( \'link\' ); ?>\">
			
		
		<input type=\"url\" id=\"get_field_id(\'link\'); ?>\" name=\"get_field_name(\'link\'); ?>\" value=\"\" class=\"url\">
	

	<?php
}

后台设置选项如下图所示，你可以自界说下样式。

update()

update 方法用于更新小工具装备项。

WP_Widget::update( array $new_instance, array $old_instance )
  • $new_instance：小工具新的装备项（新设置的装备项）。
  • $old_instance：小工具原有装备项（数据库中的装备项）。

示例：

// 更新设置选项
public function update( $new_instance, $old_instance ) {
	$instance = $old_instance;
	$instance[\'text\']       = $new_instance[\'text\'];
	$instance[\'textarea\']   = $new_instance[\'textarea\'];
	$instance[\'radio\']      = $new_instance[\'radio\'];
	$instance[\'checkbox\']   = $new_instance[\'checkbox\'];
	$instance[\'select\']     = $new_instance[\'select\'];
	$instance[\'nav_menu\']   = $new_instance[\'nav_menu\'];
	$instance[\'number\']     = $new_instance[\'number\'];
	$instance[\'link\']     = $new_instance[\'link\'];
	return $instance;
}

更新后的小工具数据存储在数据库 wp_options 表下对应 id 字段下，同一个小工具被引用屡次，每个小工具的装备项都会独立保管在这里。

widget()

widget 方法输出前端闪现内容，你可以在这里规划小工具的前端闪现结构及样式。

WP_Widget::widget( array $args, array $instance )
  • args：默许参数，便是运用 register_sidebar 注册小工具方位时的装备项，比如：args：默许参数，便是运用registers​idebar注册小工具方位时的装备项，比如：before_sidebar、after_sidebar、afters​idebar、before_widget、after_widget、afterw​idget、before_title、$after_title 等。
  • $instance：小工具装备项的值。

示例：

// 前端生成闪现
public function widget( $args, $instance ) {
	extract( $args );
	extract( $instance );
	
	$text = apply_filters(\'widget_name\', $instance[\'text\']);
	$textarea = apply_filters(\'widget_name\', $instance[\'textarea\']);
	$radio = apply_filters(\'widget_name\', $instance[\'radio\']);
	$checkbox = apply_filters(\'widget_name\', $instance[\'checkbox\']);
	$select = apply_filters(\'widget_name\', $instance[\'select\']);
	$nav_menu = apply_filters(\'widget_name\', $instance[\'nav_menu\']);
	$number = apply_filters(\'widget_name\', $instance[\'number\']);
	$link = apply_filters(\'widget_name\', $instance[\'link\']);
	
	echo $before_widget;

	echo \'
单行文本输出值： 
\' . $text . \'
\';
	
	echo \'
多行文本输出值： 
\' . $textarea . \'
\';

	echo \'
单选按钮输出值： 
\' . $radio . \'
\';

	echo \'
复选框输出值： 
\' . $checkbox . \'
\';

	echo \'
下拉挑选输出值： 
\' . $select . \'
\';

	echo \'
菜单 ID 输出值： 
\' . $nav_menu . \'
\';

	echo \'
数量调整输出值： 
\' . $number . \'
\';

	echo \'
自界说链接输出值： 
\' . $link . \'
\';

	echo $after_widget;
}

前端闪现成果如下：


如此，一个一般的前端小工具即构建完结。