云策 WordPress 开发者社区

函数文档

checked()

查看官方原文 ↗
💡 云策文档标注

概述

checked() 函数用于输出 HTML 的 checked 属性，通过比较两个参数值是否相同来决定是否标记为选中状态。它是 WordPress 开发中处理表单复选框和单选按钮的常用辅助函数。

关键要点

  • 函数原型：checked( $checked, $current = true, $display = true )，返回 HTML 属性字符串或空字符串
  • 核心功能：比较 $checked 和 $current 参数，若相同则输出 checked="checked"，否则输出空字符串
  • 参数说明：$checked 为必需值，$current 默认为 true，$display 控制是否直接回显（默认 true）
  • 内部实现：基于 __checked_selected_helper() 私有辅助函数，与 selected()、disabled() 等函数共享逻辑
  • 应用场景：广泛用于 WordPress 后台设置、小部件表单、自定义控件等界面元素的选中状态处理

代码示例

// 使用 if 语句测试值
<input type="checkbox" name="test" value="1" <?php if ( 1 == $value ) echo 'checked="checked"'; ?> />

// 使用 checked() 函数替代
<input type="checkbox" name="test" value="1" <?php checked( $value, 1 ); ?> />

注意事项

  • 选项保存问题：复选框未选中时可能不保存值，使用前应检查选项是否设置，例如通过 isset() 或设置默认值
  • 多选复选框处理：对于多选场景，checked() 函数可接受数组作为参数进行比较，确保正确输出选中状态
📄 原文内容

Outputs the HTML checked attribute.

Description

Compares the first two arguments and if identical marks as checked.

Parameters

$checkedmixedrequired
One of the values to compare.
$currentmixedoptional
The other value to compare if not just true.

Default:true

$displaybooloptional
Whether to echo or just return the string.

Default:true

Return

string HTML attribute or empty string.

Source

function checked( $checked, $current = true, $display = true ) {
	return __checked_selected_helper( $checked, $current, $display, 'checked' );
}

View all references View on Trac View on GitHub

Uses Description
__checked_selected_helper()wp-includes/general-template.php

Private helper function for checked, selected, disabled and readonly.
Used by Description
WP_Screen::render_meta_boxes_preferences()wp-admin/includes/class-wp-screen.php

Renders the meta boxes preferences.
WP_Screen::render_list_table_columns_preferences()wp-admin/includes/class-wp-screen.php

Renders the list table columns preferences.
WP_Screen::render_view_mode()wp-admin/includes/class-wp-screen.php

Renders the list table view mode preferences.
signup_user()wp-signup.php

Shows a form for a visitor to sign up for a new user account.
network_step1()wp-admin/includes/network.php

Prints step 1 for Network installation process.
display_setup_form()wp-admin/install.php

Displays installer setup form.
use_ssl_preference()wp-admin/includes/user.php

Optional SSL preference that can be turned on by hooking to the ‘personal_options’ action.
WP_Screen::show_screen_options()wp-admin/includes/class-wp-screen.php
WP_Screen::render_screen_layout()wp-admin/includes/class-wp-screen.php

Renders the option for number of columns on the page.
meta_box_prefs()wp-admin/includes/screen.php

Prints the meta box preferences for screen meta.
admin_color_scheme_picker()wp-admin/includes/misc.php

Displays the default administration color scheme picker (Used in user-edit.php).
Walker_Category_Checklist::start_el()wp-admin/includes/class-walker-category-checklist.php

Start the element output.
wp_media_insert_url_form()wp-admin/includes/media.php

Creates the form for external url.
post_comment_status_meta_box()wp-admin/includes/meta-boxes.php

Displays comments status form fields.
link_submit_meta_box()wp-admin/includes/meta-boxes.php

Displays link create form fields.
post_submit_meta_box()wp-admin/includes/meta-boxes.php

Displays post submit form fields.
post_format_meta_box()wp-admin/includes/meta-boxes.php

Displays post format form elements.
Walker_Nav_Menu_Edit::start_el()wp-admin/includes/class-walker-nav-menu-edit.php

Start the element output.
request_filesystem_credentials()wp-admin/includes/file.php

Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
Custom_Image_Header::step_1()wp-admin/includes/class-custom-image-header.php

Displays first step of custom header image page.
Custom_Image_Header::show_header_selector()wp-admin/includes/class-custom-image-header.php

Displays UI for selecting one of several default headers.
Custom_Background::admin_page()wp-admin/includes/class-custom-background.php

Displays the custom background page.
WP_Widget_Tag_Cloud::form()wp-includes/widgets/class-wp-widget-tag-cloud.php

Outputs the Tag Cloud widget settings form.
WP_Widget_Recent_Posts::form()wp-includes/widgets/class-wp-widget-recent-posts.php

Outputs the settings form for the Recent Posts widget.
WP_Widget_Categories::form()wp-includes/widgets/class-wp-widget-categories.php

Outputs the settings form for the Categories widget.
WP_Widget_Text::form()wp-includes/widgets/class-wp-widget-text.php

Outputs the Text widget settings form.
WP_Widget_Archives::form()wp-includes/widgets/class-wp-widget-archives.php

Outputs the settings form for the Archives widget.
WP_Widget_Links::form()wp-includes/widgets/class-wp-widget-links.php

Outputs the settings form for the Links widget.
wp_widget_rss_form()wp-includes/widgets.php

Displays RSS widget options form.
WP_Customize_Control::render_content()wp-includes/class-wp-customize-control.php

Renders the control’s content.

Show 25 moreShow less

Changelog

Version Description
1.0.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    Example

    
<input name="slug-option[self-destruct]" value="1"
	<?php checked( $checked, $current, $echo ); ?>/>

    Testing the value with if():

    <input type='checkbox' name='options[postlink]' value='1'
	<?php if ( 1 == $options['postlink'] ) echo 'checked="checked"'; ?> />

    Using checked() instead:

    <input type="checkbox" name="options[postlink]" value="1"
	<?php checked( $options['postlink'], 1 ); ?> />

  2. Skip to note 5 content


    Anonymous User


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Note that checking for 

    checked()

    may/is not enough!

    Options are not saved if left empty (in the checkbox case == unchecked).

    Thus, before checked( $options['option_name'], 1 ); we should also check if the option is actually set, with something like:

    $options = get_option( 'wpdocs_option_array' );
if ( ! isset( $options['option'] ) ) {
    $options['option'] = 0;
}

  3. Skip to note 6 content


    sandeepjainlive


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    For multiselect checkbox use array in checked function instead of simple value. 

    ID, 'postlink', true ); ?>
<input type="checkbox" name="postlink[]" value="1"
     <?php checked(in_array( 1, $postlink ), 1); ?> />
<input type="checkbox" name="postlink[]" value="2"
     <?php checked(in_array( 2, $postlink ), 1); ?> />
<input type="checkbox" name="postlink[]" value="3"
     <?php checked(in_array( 3, $postlink ), 1); ?> />