云策 WordPress 开发者社区

函数文档

wp_is_mobile()

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

概述

wp_is_mobile() 是一个 WordPress 条件标签函数，用于检测当前浏览器是否运行在移动设备（如智能手机、平板电脑）上。它通过检查 HTTP 请求头中的用户代理字符串或 Sec-CH-UA-Mobile 头来返回布尔值 TRUE 或 FALSE。

关键要点

  • 函数返回布尔值，TRUE 表示移动设备，FALSE 表示非移动设备。
  • 检测基于用户代理字符串，包括 Mobile、Android、Silk/、Kindle、BlackBerry、Opera Mini 和 Opera Mobi 等关键词。
  • 从 WordPress 6.4.0 开始，优先检查 Sec-CH-UA-Mobile 请求头以提高准确性。
  • 主要用途是优化移动设备资源（如 CPU、内存、带宽），而非检测屏幕宽度或替代 CSS 媒体查询。
  • 在主题中使用时，需注意缓存问题：页面缓存必须区分移动和非移动版本，否则可能导致函数失效。
  • 适用于创建轻量级移动版本或独特移动体验，但需额外设计响应式规格（如桌面、移动、AMP）。

代码示例

if ( wp_is_mobile() ) {
    // 显示移动设备特定内容
} else {
    // 显示桌面设备内容
}

注意事项

  • 函数不检测屏幕宽度，不能替代 CSS 媒体查询或平台特定样式。
  • 在公共主题中使用时，确保缓存解决方案支持移动/非移动分离，否则可能破坏功能。
  • 移动和桌面版本仍需保持响应式设计，以适应不同设备尺寸。
📄 原文内容

Test if the current browser runs on a mobile device (smart phone, tablet, etc.).

Return

bool

More Information

This Conditional Tag checks if the user is visiting using a mobile device. This is a boolean function, meaning it returns either TRUE or FALSE. It works through the detection of the browser user agent string ($_SERVER[‘HTTP_USER_AGENT’])

Do not think of this function as a way of detecting phones. Its purpose is not detecting screen width, but rather adjusting for the potentially limited resources of mobile devices. A mobile device may have less CPU power, memory and/or bandwidth available. This function will return true for a tablet, as it too is considered a mobile device. It is not a substitute for CSS media queries or styling per platform.

One way that this function could be used in a theme is to produce a very light version of the site that does not have the large payload of the desktop site. Note that both the desktop and the mobile versions of the page will still need to be responsive, as an older portrait phone will have a significantly different width than a modern iPad in landscape. wp_is_mobile() will be true for both. Similarly a desktop browser window may not be displayed at full width. Essentially this approach may double the amount of work you will need to put into the theme. Yet for a tightly optimized theme or a unique mobile experience, it may be essential. It also means that a proper theme may have at least three different responsive design specs: Desktop, Mobile and AMP.

Additionally, care must be taken when using this function in a public theme. If your theme works differently for mobile devices and desktop devices, any page caching solution used MUST keep separate mobile/non-mobile buckets. Many caching solutions do not do this or charge for this feature. Even the most detailed read me file may not be able to adequately explain these details

Source

function wp_is_mobile() {
	if ( isset( $_SERVER['HTTP_SEC_CH_UA_MOBILE'] ) ) {
		// This is the `Sec-CH-UA-Mobile` user agent client hint HTTP request header.
		// See <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Mobile>.
		$is_mobile = ( '?1' === $_SERVER['HTTP_SEC_CH_UA_MOBILE'] );
	} elseif ( empty( $_SERVER['HTTP_USER_AGENT'] ) ) {
		$is_mobile = false;
	} elseif ( str_contains( $_SERVER['HTTP_USER_AGENT'], 'Mobile' ) // Many mobile devices (all iPhone, iPad, etc.)
		|| str_contains( $_SERVER['HTTP_USER_AGENT'], 'Android' )
		|| str_contains( $_SERVER['HTTP_USER_AGENT'], 'Silk/' )
		|| str_contains( $_SERVER['HTTP_USER_AGENT'], 'Kindle' )
		|| str_contains( $_SERVER['HTTP_USER_AGENT'], 'BlackBerry' )
		|| str_contains( $_SERVER['HTTP_USER_AGENT'], 'Opera Mini' )
		|| str_contains( $_SERVER['HTTP_USER_AGENT'], 'Opera Mobi' ) ) {
			$is_mobile = true;
	} else {
		$is_mobile = false;
	}

	/**
	 * Filters whether the request should be treated as coming from a mobile device or not.
	 *
	 * @since 4.9.0
	 *
	 * @param bool $is_mobile Whether the request is from a mobile device or not.
	 */
	return apply_filters( 'wp_is_mobile', $is_mobile );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_is_mobile’, bool $is_mobile )

Filters whether the request should be treated as coming from a mobile device or not.

Uses Description
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Used by Description
WP_Customize_Manager::customize_pane_settings()wp-includes/class-wp-customize-manager.php

Prints JavaScript settings for parent window.
WP_Customize_Manager::is_ios()wp-includes/class-wp-customize-manager.php

Determines whether the user agent is iOS.
media_upload_form()wp-admin/includes/media.php

Outputs the legacy media upload form.
_wp_customize_loader_settings()wp-includes/theme.php

Adds settings for the customize-loader script.
user_can_richedit()wp-includes/general-template.php

Determines whether the user can access the visual editor.
_device_can_upload()wp-includes/functions.php

Tests if the current device has the capability to upload files.
WP_Admin_Bar::_render()wp-includes/class-wp-admin-bar.php
wp_plupload_default_settings()wp-includes/media.php

Prints default Plupload arguments.
_WP_Editors::editor_settings()wp-includes/class-wp-editor.php

Show 4 moreShow less

Changelog

Version Description
6.4.0 Added checking for the Sec-CH-UA-Mobile request header.
3.4.0 Introduced.

User Contributed Notes

  3. Skip to note 6 content


    Tom Rhodes


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

    Note: Whilst caching issues are mentioned in more information for this function it cannot be re-stated enough that any page caching, which does not split itself into mobile and non-mobile buckets, will break this function. If your page caching is global and a desktop device triggers a refresh, the return of this function will always be FALSE until the next refresh. Likewise if a mobile device triggers the refresh, the return will always be TRUE. IF you expect the result of this function to change on a per user basis, ensure that you have considered how caching will affect your code.