描述
从URL中删除了许多字符。如果URL用于显示（默认行为），则符号也会被替换。‘clean_url’过滤器应用于返回的已清理的URL。
参数
- $url
-
(string) (必填) 要清理的URL。
- $protocols
-
(string[]) (可选) 可接受协议的数组，默认返回值为wp_allowed_protocols()。
默认值: null
- $_context
-
(string) (可选) 私有的，使用esc_url_raw()进行数据库使用。
默认值: 'display'
返回
(string) 应用‘clean_url’过滤器后清理的URL。如果$url指定的协议不是$protocols中的协议，或者$url包含空字符串，则返回空字符串。
说明
清理url（在文本节点、属性节点或任何其他位置）时，始终使用esc_url。拒绝没有提供的白名单协议之一的URL（默认为http、https、ftp、ftps、mailto、news、irc、gopher、nntp、feed和telnet），消除无效字符并删除危险字符。此函数将字符编码为HTML实体：在生成（X）HTML或XML文档时使用它。编码符号和（&）和单引号（'）作为数字实体引用（&，'）。
如果URL看起来是一个不包含方案的绝对链接，则预先添加http://前缀。请注意，相对url（/my-url/parameter2/）以及锚点（#myanchor）和参数项（?myparam=yes）也可以作为特例进行过滤，而无需将默认协议前置到过滤的url。
替换已弃用的clean_url()。
相关
| 使用 | 描述 |
|---|---|
| clean_url | 过滤已清理并转义为URL输出的字符串 |
| wp_allowed_protocols() | 检索HTML属性中允许的协议列表 |
| apply_filters() | 调用已添加到过滤器钩子的回调函数 |
| stripos() | |
| wp_parse_url() | |
| _deep_replace() | |
| wp_kses_normalize_entities() | |
| wp_kses_bad_protocol() |
| 被使用 | 描述 |
|---|---|
| get_the_privacy_policy_link() | 如果适用，则返回带有格式的隐私策略链接 |
| get_term_parents_list() | 检索父级项目以分隔符分隔 |
| get_custom_logo() | 返回链接到主页的自定义logo，除非主题支持删除主页链接 |
| get_the_author_posts_link() | 检索指向当前文章作者的作者页面的HTML链接 |
| menu_page_url() | 获取用于访问特定菜单页的URL，该URL基于该菜单页注册的slug |
| get_the_term_list() | 以指定格式检索文章的terms列表 |
| wp_generate_tag_cloud() | 根据提供的数据生成标签云（热点图） |
| get_the_category_list() | 以HTML列表或自定义格式检索文章的类别列表 |
| wp_list_categories() | 显示或检索类别的HTML列表 |
| header_image() | 显示页眉图像URL |
| esc_url_raw() | 对数据库或重定向使用执行esc_url() |
| get_avatar() | 检索用户、电子邮件地址、MD5哈希、评论或文章的头像 |
| paginate_links() | 检索存档文章页面的分页链接 |
| get_archives_link() | 根据预定义或自定义代码检索存档链接内容。 |
| wp_loginout() | 显示登录/退出链接 |
| wp_login_form() | 提供了一个简单的登录表单，可以在WordPress中的任何地方使用 |
| wp_register() | 显示注册或管理链接 |
| get_search_form() | 显示搜索表单 |
| clean_url() | 检查并清除URL |
| wp_nonce_ays() | 显示“你确定吗”消息以确认正在采取的操作 |
| wp_shortlink_wp_head() | 如果为当前页面定义了短链接，则将rel=shortlink注入头部 |
| the_shortlink() | 显示文章的短链接 |
| edit_post_link() | 显示文章的编辑文章链接 |
| edit_comment_link() | 显示带有格式的编辑评论链接 |
| edit_bookmark_link() | 显示编辑书签链接的锚内容 |
| the_feed_link() | 显示feed类型的固定链接 |
| the_permalink() | 显示当前文章的固定链接 |
| _walk_bookmarks() | bookmark列表的格式化输出 |
| wp_get_attachment_link() | 如果可能，使用图像或图标检索附件页面链接 |
| get_the_author_link() | 检索作者的链接或作者的名称 |
| wp_list_authors() | 列出网站的所有作者，并提供了几个选项 |
| comment_form() | 输出完整的评论表单，供在模板中使用 |
| comments_template() | 加载在$file中指定的评论模板 |
| get_comment_reply_link() | 检索回复评论的链接的HTML内容 |
| comments_link() | 显示指向当前文章评论的链接 |
| get_comment_text() | 检索当前评论的文本 |
| WP_Widget_Media::get_l10n_defaults() | |
| wp_list_users() | |
| deactivated_plugins_notice() | |
| wp_is_local_html_output() | |
| WP_Site_Health::get_test_authorization_header() | |
| WP_Sitemaps::add_robots() | |
| WP_Sitemaps_Renderer::get_sitemap_index_xml() | |
| WP_Sitemaps_Renderer::get_sitemap_xml() | |
| WP_Sitemaps_Renderer::__construct() | |
| WP_Sitemaps_Stylesheet::get_sitemap_stylesheet() | |
| WP_Sitemaps_Stylesheet::get_sitemap_index_stylesheet() | |
| wp_dashboard_site_health() | |
| wp_credits_section_list() | |
| WP_Privacy_Data_Removal_Requests_List_Table::column_email() | |
| WP_Privacy_Data_Removal_Requests_List_Table::column_next_steps() | |
| WP_MS_Sites_List_Table::get_views() | |
| WP_Privacy_Data_Export_Requests_List_Table::column_email() | |
| WP_Privacy_Data_Export_Requests_List_Table::column_next_steps() | |
| wp_get_update_php_annotation() | |
| paused_themes_notice() | |
| wp_recovery_mode_nag() | |
| WP_Site_Health::get_test_wordpress_version() | |
| WP_Site_Health::get_test_plugin_version() | |
| WP_Site_Health::get_test_theme_version() | |
| WP_Site_Health::get_test_php_version() | |
| WP_Site_Health::get_test_php_extensions() | |
| WP_Site_Health::get_test_sql_server() | |
| WP_Site_Health::get_test_dotorg_communication() | |
| WP_Site_Health::get_test_is_in_debug_mode() | |
| WP_Site_Health::get_test_https_status() | |
| paused_plugins_notice() | |
| validate_plugin_requirements() | |
| wp_direct_php_update_button() | |
| wp_dashboard_php_nag() | |
| wp_get_script_polyfill() | |
| do_block_editor_incompatible_meta_box() | |
| the_block_editor_meta_boxes() | |
| the_block_editor_meta_box_post_form_hidden_fields() | |
| wp_comments_personal_data_exporter() | |
| WP_Privacy_Policy_Content::notice() | |
| WP_Privacy_Policy_Content::policy_text_changed_notice() | |
| wp_privacy_generate_personal_data_export_group_html() | |
| WP_Privacy_Requests_Table::column_email() | |
| WP_Privacy_Requests_Table::get_views() | |
| WP_Widget_Custom_HTML::add_help_text() | |
| update_network_option_new_admin_email() | |
| wp_load_press_this() | |
| wp_print_plugin_file_tree() | |
| wp_print_theme_file_tree() | |
| WP_Widget_Media_Audio::__construct() | |
| WP_Widget_Media_Video::__construct() | |
| WP_Widget_Media_Image::render_media() | |
| WP_Widget_Media_Image::__construct() | |
| wp_print_community_events_markup() | |
| wp_dashboard_events_news() | |
| the_header_video_url() | |
| wp_resource_hints() | |
| network_edit_site_nav() | |
| the_embed_site_title() | |
| WP_Customize_Site_Icon_Control::content_template() | |
| rest_output_rsd() | |
| rest_output_link_wp_head() | |
| wp_filter_oembed_result() | |
| wp_embed_excerpt_more() | |
| wp_oembed_add_discovery_links() | |
| get_post_embed_html() | |
| the_post_thumbnail_url() | |
| WP_Posts_List_Table::get_edit_link() | |
| wp_site_icon() | |
| site_icon_url() | |
| WP_Posts_List_Table::handle_row_actions() | |
| WP_MS_Themes_List_Table::column_name() | |
| WP_Comments_List_Table::handle_row_actions() | |
| WP_MS_Sites_List_Table::handle_row_actions() | |
| WP_MS_Sites_List_Table::column_blogname() | |
| WP_MS_Sites_List_Table::column_users() | |
| WP_Terms_List_Table::handle_row_actions() | |
| WP_MS_Users_List_Table::handle_row_actions() | |
| WP_MS_Users_List_Table::column_username() | |
| WP_MS_Users_List_Table::column_email() | |
| WP_MS_Users_List_Table::column_blogs() | |
| WP_Media_List_Table::column_author() | |
| WP_Media_List_Table::column_default() | |
| WP_Customize_Theme_Control::content_template() | |
| customize_themes_print_templates() | |
| wp_admin_canonical_url() | |
| WP_Customize_Manager::remove_panel() | |
| login_footer() | |
| retrieve_password() | |
| login_header() | |
| signup_another_blog() | |
| confirm_another_blog_signup() | |
| network_step1() | |
| network_step2() | |
| wp_prepare_themes_for_js() | |
| get_theme_update_available() | |
| WP_Screen::render_screen_meta() | |
| WP_Plugins_List_Table::single_row() | |
| WP_Plugins_List_Table::no_items() | |
| Theme_Upgrader_Skin::after() | |
| Theme_Installer_Skin::after() | |
| WP_List_Table::view_switcher() | |
| WP_List_Table::comments_bubble() | |
| WP_List_Table::pagination() | |
| WP_List_Table::print_column_headers() | |
| _access_denied_splash() | |
| site_admin_notice() | |
| choose_primary_blog() | |
| update_option_new_admin_email() | |
| send_confirmation_on_profile_email() | |
| wp_image_editor() | |
| WP_MS_Themes_List_Table::get_views() | |
| admin_color_scheme_picker() | |
| WP_Theme_Install_List_Table::install_theme_info() | |
| WP_Theme_Install_List_Table::single_row() | |
| WP_Theme_Install_List_Table::theme_installer_single() | |
| update_nag() | |
| wp_plugin_update_row() | |
| wp_theme_update_row() | |
| wp_welcome_panel() | |
| install_dashboard() | |
| install_plugin_information() | |
| wp_dashboard_quota() | |
| wp_dashboard_browser_nag() | |
| wp_dashboard_plugins_output() | |
| wp_add_dashboard_widget() | |
| wp_network_dashboard_right_now() | |
| wp_dashboard_quick_press() | |
| wp_dashboard_recent_drafts() | |
| _wp_dashboard_recent_comments_row() | |
| wp_install_defaults() | |
| _get_plugin_data_markup_translate() | |
| WP_Plugin_Install_List_Table::display_rows() | |
| wp_import_upload_form() | |
| WP_Themes_List_Table::display_rows() | |
| WP_Users_List_Table::single_row() | |
| WP_Users_List_Table::get_views() | |
| media_upload_type_form() | |
| media_upload_type_url_form() | |
| media_upload_gallery_form() | |
| media_upload_library_form() | |
| media_upload_max_image_resize() | |
| edit_form_image_editor() | |
| attachment_submitbox_metadata() | |
| wp_media_upload_handler() | |
| the_media_upload_tabs() | |
| get_sample_permalink_html() | |
| _wp_post_thumbnail_html() | |
| _admin_notice_post_locked() | |
| wp_ajax_send_attachment_to_editor() | |
| wp_ajax_send_link_to_editor() | |
| update_core() | |
| wp_link_manager_disabled_message() | |
| post_submit_meta_box() | |
| edit_link() | |
| get_default_link_to_edit() | |
| WP_Media_List_Table::_get_row_actions() | |
| WP_Comments_List_Table::column_author() | |
| WP_Comments_List_Table::column_date() | |
| WP_Comments_List_Table::column_comment() | |
| WP_Terms_List_Table::column_name() | |
| WP_Terms_List_Table::column_posts() | |
| Walker_Nav_Menu_Edit::start_el() | |
| wp_nav_menu_item_post_type_meta_box() | |
| wp_nav_menu_item_taxonomy_meta_box() | |
| request_filesystem_credentials() | |
| wp_widget_control() | |
| get_comment_to_edit() | |
| _wp_credits_add_profile_link() | |
| _wp_credits_build_object_link() | |
| Custom_Image_Header::step_1() | |
| Custom_Image_Header::step_2() | |
| confirm_delete_users() | |
| list_core_update() | |
| core_upgrade_preamble() | |
| list_plugin_updates() | |
| list_theme_updates() | |
| list_translation_updates() | |
| do_core_upgrade() | |
| Custom_Background::admin_page() | |
| _wp_menu_output() | |
| WP_Customize_Manager::register_controls() | |
| WP_Styles::_css_href() | |
| Walker_Category::start_el() | |
| wp_customize_url() | |
| _wp_customize_loader_settings() | |
| _make_url_clickable_cb() | |
| _make_web_ftp_clickable_cb() | |
| translate_smiley() | |
| wp_admin_css() | |
| feed_links() | |
| feed_links_extra() | |
| rsd_link() | |
| get_index_rel_link() | |
| comments_rss() | |
| get_links() | |
| WP_Theme::markup_header() | |
| wp_auth_check_html() | |
| _default_wp_die_handler() | |
| WP_Widget_RSS::widget() | |
| WP_Widget_Recent_Comments::widget() | |
| WP_Widget_Categories::widget() | |
| WP_Widget_Meta::widget() | |
| wp_widget_rss_output() | |
| wp_widget_rss_form() | |
| wp_widget_rss_process() | |
| WP_Embed::maybe_make_link() | |
| WP_Embed::maybe_run_ajax_cache() | |
| rel_canonical() | |
| get_next_comments_link() | |
| get_previous_comments_link() | |
| get_pagenum_link() | |
| next_posts() | |
| previous_posts() | |
| post_comments_feed_link() | |
| WP_Admin_Bar::_render() | |
| WP_Admin_Bar::_render_item() | |
| wp_version_check() | |
| WP_oEmbed::data2html() | |
| wp_admin_bar_my_sites_menu() | |
| wp_admin_bar_edit_menu() | |
| wp_admin_bar_search_menu() | |
| rss_enclosure() | |
| atom_enclosure() | |
| self_link() | |
| the_permalink_rss() | |
| comments_link_feed() | |
| comment_guid() | |
| comment_link() | |
| sanitize_user_field() | |
| Walker_Nav_Menu::start_el() | |
| Walker_Page::start_el() | |
| get_the_password_form() | |
| _wp_link_page() | |
| wp_embed_handler_audio() | |
| wp_embed_handler_video() | |
| wp_video_shortcode() | |
| wp_mediaelement_fallback() | |
| wp_audio_shortcode() | |
| get_image_tag() | |
| newblog_notify_siteadmin() | |
| newuser_notify_siteadmin() | |
| wpmu_signup_blog_notification() | |
| get_most_active_blogs() | |
| WP_Scripts::do_item() | |
| get_blogaddress_by_id() | |
| get_blogaddress_by_name() | |
| wp_rss() | |
| Walker_Comment::comment() | |
| Walker_Comment::html5_comment() | |
| get_comment_author_email_link() | |
| get_comment_author_url() | |
| wp_default_scripts() | |
| wp_set_comment_cookies() | |
| wp_print_media_templates() |
源码
更新日志
| 版本 | 描述 |
|---|---|
| 2.8.0 | 开始引入 |
使用示例
添加主页链接
如Twenty Thirteen主题所示，尽管为了示例而简化了<a href="<?php echo esc_url( home_url( '/' ) ); ?>">Home</a>
如果URI协议不是允许的协议之一，
esc_url()的结果是空字符串。WordPress允许的默认协议列表可以用以下代码扩展：<?php /** * Extend list of allowed protocols. * * @param array $protocols List of default protocols allowed by WordPress. * * @return array $protocols Updated list including new protocols. */ function wporg_extend_allowed_protocols( $protocols ){ $protocols[] = 'skype'; $protocols[] = 'spotify'; $protocols[] = 'macappstores'; return $protocols; } add_filter( 'kses_allowed_protocols' , 'wporg_extend_allowed_protocols' ); ?>此函数还应用于转义“img”标记的“src”属性：
<img src="<?php echo esc_url( $image_url ); ?>" alt="..." />
它还应用于“form”标记“action”属性：
<form action="<?php echo esc_url( $form_submit_url ); ?>">