云策 WordPress 开发者社区

函数文档

wp_star_rating()

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

概述

wp_star_rating() 函数用于输出基于给定评分的星级评分 HTML 元素，支持 0 到 5 分以半星为增量（如 1、1.5、2 星）的显示。可选参数允许显示评分数量，并控制是否直接输出或返回 HTML 标记。

关键要点

  • 函数输出星级评分 HTML，评分范围 0-5，支持半星增量（如 1.5 星）。
  • 参数包括 rating（评分，可为 0.5 增量或百分比）、type（评分格式，'rating' 或 'percent'）、number（评分数量）、echo（是否直接输出）。
  • 在前端使用时，需包含 wp-admin/includes/template.php 文件并加载 dashicons CSS 字体。
  • 函数内部处理评分转换（如百分比转星级）和国际化字符串。

代码示例

$args = array(
   'rating' => 3.5,
   'type' => 'rating',
   'number' => 1234,
);
wp_star_rating( $args );

注意事项

确保在前端正确加载 dashicons 字体 CSS，否则星级图标可能无法显示。参考 wp-admin/css/dashicons.css 获取完整字体数据。

📄 原文内容

Outputs a HTML element with a star rating for a given rating.

Description

Outputs a HTML element with the star rating exposed on a 0..5 scale in half star increments (ie. 1, 1.5, 2 stars). Optionally, if specified, the number of ratings may also be displayed by passing the $number parameter.

Parameters

$argsarrayoptional
Array of star ratings arguments.

  • rating int|float
    The rating to display, expressed in either a 0.5 rating increment, or percentage. Default 0.
  • type string
    Format that the $rating is in. Valid values are 'rating' (default), or, 'percent'. Default 'rating'.
  • number int
    The number of ratings that makes up this rating. Default 0.
  • echo bool
    Whether to echo the generated markup. False to return the markup instead of echoing it. Default true.

Default:array()

Return

string Star rating HTML.

More Information

In order to use this function on the front end, your template must include the wp-admin/includes/template.php file and enqueue the appropriate dashicons CSS font information.

Example CSS:
<br>
@font-face {<br>
font-family: "dashicons";<br>
src: url("../fonts/dashicons.eot");<br>
}

@font-face {<br>
font-family: "dashicons";<br>
src: url(data:application/x-font-woff;charset=utf-8;base64,/* !! Large amount of data removed, see wp-includes/css/dashicons.css for complete data !! */) format("woff"),<br>
url("../fonts/dashicons.ttf") format("truetype"),<br>
url("../fonts/dashicons.svg#dashicons") format("svg");<br>
font-weight: normal;<br>
font-style: normal;<br>
}


<p>.star-rating .star-full:before {<br>
content: "f155";<br>
}</p>
<p>.star-rating .star-half:before {<br>
content: "f459";<br>
}</p>
<p>.star-rating .star-empty:before {<br>
content: "f154";<br>
}</p>

.star-rating .star {<br>
color: #0074A2;<br>
display: inline-block;<br>
font-family: dashicons;<br>
font-size: 20px;<br>
font-style: normal;<br>
font-weight: 400;<br>
height: 20px;<br>
line-height: 1;<br>
text-align: center;<br>
text-decoration: inherit;<br>
vertical-align: top;<br>
width: 20px;<br>
}<br>

Note the font data in the above CSS has been omitted for clarity. This data must be included in working code. Refer to wp-admin/css/dashicons.css

Source

function wp_star_rating( $args = array() ) {
	$defaults    = array(
		'rating' => 0,
		'type'   => 'rating',
		'number' => 0,
		'echo'   => true,
	);
	$parsed_args = wp_parse_args( $args, $defaults );

	// Non-English decimal places when the $rating is coming from a string.
	$rating = (float) str_replace( ',', '.', $parsed_args['rating'] );

	// Convert percentage to star rating, 0..5 in .5 increments.
	if ( 'percent' === $parsed_args['type'] ) {
		$rating = round( $rating / 10, 0 ) / 2;
	}

	// Calculate the number of each type of star needed.
	$full_stars  = floor( $rating );
	$half_stars  = ceil( $rating - $full_stars );
	$empty_stars = 5 - $full_stars - $half_stars;

	if ( $parsed_args['number'] ) {
		/* translators: Hidden accessibility text. 1: The rating, 2: The number of ratings. */
		$format = _n( '%1$s rating based on %2$s rating', '%1$s rating based on %2$s ratings', $parsed_args['number'] );
		$title  = sprintf( $format, number_format_i18n( $rating, 1 ), number_format_i18n( $parsed_args['number'] ) );
	} else {
		/* translators: Hidden accessibility text. %s: The rating. */
		$title = sprintf( __( '%s rating' ), number_format_i18n( $rating, 1 ) );
	}

	$output  = '<div class="star-rating">';
	$output .= '<span class="screen-reader-text">' . $title . '</span>';
	$output .= str_repeat( '<div class="star star-full" aria-hidden="true"></div>', $full_stars );
	$output .= str_repeat( '<div class="star star-half" aria-hidden="true"></div>', $half_stars );
	$output .= str_repeat( '<div class="star star-empty" aria-hidden="true"></div>', $empty_stars );
	$output .= '</div>';

	if ( $parsed_args['echo'] ) {
		echo $output;
	}

	return $output;
}

View all references View on Trac View on GitHub

Uses Description
_n()wp-includes/l10n.php

Translates and retrieves the singular or plural form based on the supplied number.
__()wp-includes/l10n.php

Retrieves the translation of $text.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.
number_format_i18n()wp-includes/functions.php

Converts float number to format based on the locale.

Show 2 moreShow less

Used by Description
WP_Customize_Manager::handle_load_themes_request()wp-includes/class-wp-customize-manager.php

Loads themes into the theme browsing/installation UI.
WP_Theme_Install_List_Table::install_theme_info()wp-admin/includes/class-wp-theme-install-list-table.php

Prints the info for a theme (to be used in the theme installer modal).
install_plugin_information()wp-admin/includes/plugin-install.php

Displays plugin information in dialog box form.
WP_Plugin_Install_List_Table::display_rows()wp-admin/includes/class-wp-plugin-install-list-table.php

Generates the list table rows.
wp_ajax_query_themes()wp-admin/includes/ajax-actions.php

Handles getting themes from themes_api() via AJAX.

Changelog

Version Description
4.4.0 Introduced the echo parameter.
3.8.0 Introduced.

User Contributed Notes

  2. Skip to note 4 content


    Codex


    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

    Usage on the front end

    In order to use this function on the front end, your template must include the wp-admin/includes/template.php file and enqueue the appropriate dashicons CSS font information. Example CSS: 

    @font-face {
	font-family: "dashicons";
	src: url("../fonts/dashicons.eot");
}

@font-face {
	font-family: "dashicons";
	src: url(data:application/x-font-woff;charset=utf-8;base64,/* !! Large amount of data removed, see wp-includes/css/dashicons.css for complete data !! */) format("woff"),
		url("../fonts/dashicons.ttf") format("truetype"),
		url("../fonts/dashicons.svg#dashicons") format("svg");
	font-weight: normal;
	font-style: normal;
}

.star-rating .star-full:before {
    content: "f155";
}

.star-rating .star-half:before {
    content: "f459";
}

.star-rating .star-empty:before {
    content: "f154";
}

.star-rating .star {
    color: #0074A2;
    display: inline-block;
    font-family: dashicons;
    font-size: 20px;
    font-style: normal;
    font-weight: 400;
    height: 20px;
    line-height: 1;
    text-align: center;
    text-decoration: inherit;
    vertical-align: top;
    width: 20px;
}

    Note the font data in the above CSS has been omitted for clarity. This data must be included in working code. Refer to wp-admin/css/dashicons.css