WordPress:Template Tags/How to Pass Tag Parameters

介绍

Template tags are PHP functions you can embed in your WordPress page templates to provide dynamic blog content. And like PHP functions, many template tags accept arguments, or parameters. Template tag parameters are variables you can use to change a tag's output or otherwise modify its action in some way. Think of parameters as user options or settings that allow you to customize how a template tag works.

模板标签是PHP函数，你可以将这个函数插入到你的WordPress网页模板，提供动态的博客内容。而且与PHP函数类似，许多模板标签接受实参或者形参。模板标签参数是变数，你可以使用这些变数更改标签的产出或者在某种方式上，更改标签的运行。将参数看做是用户选项或者设置，能使你定义一个模板标签是怎样运行的。

[In regards to parameters, WordPress template tags come in three "flavors." These are described below:

[关于参数，WordPress模板标签有三种不同的"flavors。"如下面所描述的：

1. [[WordPress:#Tags without parameters|Tags without parameters]]
2. [[WordPress:#Tags with PHP function-style parameters|Tags with PHP function-style parameters]]
3. [[WordPress:#Tags with query-string-style parameters|Tags with query-string-style parameters]]

1. [[WordPress:#Tags without parameters|没有参数的标签]]
2. [[WordPress:#Tags with PHP function-style parameters|PHP函数样式的参数的标签]]
3. [[WordPress:#Tags with query-string-style parameters|查询字符串样式参数的标签]]

没有参数的标签

Some template tags do not have any options, and thus have no parameters you can pass to them.

有些模板标签没有任何选项，你也就没有什么参数可以传递给这些模板标签。

The template tag the_author_firstname() is one that accepts no parameters. This tag simply displays the first name of the author for a post. Tags without parameters should have nothing between the tag function's opening and closing brackets (parentheses):

the_author_firstname()就是一个不接受任何参数的模板标签。这个标签指示显示文章作者的名。没有参数的标签在标签函数开始和结束的括号（括号）之间没有任何内容：

<?php the_author_firstname(); ?>

<?php the_author_firstname(); ?>

PHP函数样式的参数的标签

For template tags that can accept parameters, some require them to be in the default PHP style. For these, parameters are passed to a tag function by placing one or more values inside the function's parentheses, or brackets.

对于能够接受参数的标签，有的要求是默认PHP 样式。对于这些标签，通过将一个或者几个参数值放到函数的括号或者括弧内部，参数可以传递到标签函数中。

The bloginfo() tag accepts one parameter (known as the show parameter) that tells it what information about your blog to display:

bloginfo()标签接受一个参数(是show参数)，这个参数使得标签明白你的博客上显示什么内容：

%%% <?php bloginfo('name'); ?>%%%

%%% <?php bloginfo('name'); ?>%%%

The wp_title() tag accepts two parameters: the first is the sep or separator parameter, and the second the echo or display parameter:

wp_title()标签接受两个参数：第一个参数是sep或者叫分隔符参数，第二个叫echo或者叫显示参数：

%%% <?php wp_title(' - ', TRUE); ?> %%%

%%% <?php wp_title(' - ', TRUE); ?> %%%

The first is enclosed in single-quotes and the second is not because the first is a string, and the second a boolean parameter. (See [[WordPress:#Types of parameters|Types of parameters]] for information on parameter types and how to use them.)

第一个参数包含在一个单引号中，第二个参数没有包含在单引号中，因为第一个参数是一个string,而第二个参数是一个boolean参数。(请看看[[WordPress:#Types of parameters|参数类型]] 上关于参数类型以及怎样使用这些不同类型的参数的信息。)

Important points to keep in mind for PHP function-style parameters:

牢记PHP函数样式的参数的要点：

• Some functions take multiple parameters.

• 有的函数拥有几个参数。

• Multiple parameters are separated by commas.

• 几个参数由逗号分开。

• The order of parameters is important!

• 参数的顺序非常重要!

When passing parameters to a template tag's function, make sure you specify values for all parameters up to the last one you wish to modify, or the tag may not work as expected. For example, the template tag get_archives() has six parameters:

当向模板标签的函数传递参数的时候，要确定你为所有的参数都规定了参数值直到你想要规定的最后一个参数的参数值，否则的话，标签就不会如你所愿地那样运行。例如，模板标签get_archives()拥有六个参数：

%%% <?php get_archives('type', 'limit', 'format', 'before',

                  'after', show_post_count); ?>  %%%

%%% <?php get_archives('type', 'limit', 'format', 'before',

                  'after', show_post_count); ?>  %%%

To display the archives list the way you want, let's say you only need to modify the third (format) and fifth (after) parameters. To do this, you also need to make sure to enter default values for the first, second and fourth parameters, as well:

以你喜欢的方式显示归档列表，假如你只需要更改第三个(format和第五个 (after)参数。要实现更改，你需要确定为第一个参数，第二个，和第四个参数输入了默认值：

%%%<?php get_archives( , , 'custom', , '
');

?>%%% 

%%%<?php get_archives( , , 'custom', , '
');

?>%%% 

Notice the use of single-quotes to denote empty parameter values, which in this case forces defaults for those specific parameters. Be aware that defaults can be overwritten when passing empty parameters, as is the case of a parameter specifying a string of text, and there's no way to pass an empty boolean value. So check the documentation for a parameter's default, and when one is specified use it as your parameter value (also see [[WordPress:#Types of parameters|Types of parameters]] for information on parameter types). The sixth parameter was left off; this is because WordPress uses the default for any remaining parameters left unspecified. 注意使用单引号表示empty参数值，在这个例子中，迫使这些特别的参数规定为默认值。要了解当传递一个空参数，如一个参数规定了一个文本字符串的时候，参数的默认值就会被覆盖了，而且不能传递一个空boolean参数值。因此你要查看关于参数默认设置的文件，如果有特别规定，可以将其用作你的参数值（也看看[[WordPress:#Types of parameters|参数类型]]上关于参数类型的信息）。第六个参数被遗弃了；因为WordPress为任何没有特别规定参数值的参数使用默认值。

Make sure to follow the documentation for a template tag carefully, and place your parameters in the order the template function expects. Finally, to use the defaults for all parameters in a template tag, use the tag with no parameter values specified:

要确定仔细地遵循了模板标签的文件说明，并且将你的参数按模板函数要求排列。最后，在模板标签中为所有的参数使用默认值，使用没有特别规定参数值的标签：

%%%<?php get_archives(); ?>%%%

%%%<?php get_archives(); ?>%%%

拥有查询字符串样式参数的标签

The last type of template tag makes use of what's called a query-string style to pass parameters to the tag. These provide a convenient 'wrapper' to tags which use the [[WordPress:#Tags with PHP function-style parameters|PHP function parameter style]] and have a relatively large number of parameters. For example, the template tag wp_list_cats() is a wrapper to list_cats(), a tag with eighteen parameters!

模板标签的最后一种类型利用了查询字符串样式，向标签传递参数。这些提供了一个便利的标签的'包装函式'，这个函式使用了[[WordPress:#Tags with PHP function-style parameters|PHP 函数参数样式]]和一个相关的数值较大的参数。例如，模板标签wp_list_cats()是list_cats()的包装函式，list_cats()，一个拥有十八个参数的标签！

If you want to set the exclude parameter in list_cats() (seventeenth in the parameter list) and leave the rest at their defaults, you have to do this:

如果你想在list_cats()中设置'删除参数（参数列表上有十七个参数），并且将剩余的参数保持为默认设置，你需要：

<?php list_cats(TRUE, 'All', 'ID', 'asc', '', TRUE, FALSE, FALSE, 
TRUE, TRUE, FALSE, '', '', FALSE, '', '', '10,11,12'); ?> 

<?php list_cats(TRUE, 'All', 'ID', 'asc', '', TRUE, FALSE, FALSE,

TRUE, TRUE, FALSE, '', '', FALSE, '', '', '10,11,12'); ?> 

Or you can use wp_list_cats(): 或者你可以使用wp_list_cats()：

<?php wp_list_cats('exclude=10,11,12'); ?> 

 <?php wp_list_cats('exclude=10,11,12'); ?> 

So query-string style tags are useful in that they let you change the values of just those parameters you require, without needing to provide values for all or nearly all of them. However, not all PHP function-style template tags have a query-string style equivalent. (Also note that names for tags that accept query-string style parameters usually start with a 'wp_' prefix, such as wp_list_cats(), but check the documentation on a tag to verify its method for accepting parameters, if any.)

因此查询字符串格式标签是有用的，因为这些标签能够使你更改你需要的参数的参数值，但是不需要提供所有的参数或者近乎所有的参数的参数值。然而，并不是所有的PHP函式样式的模板标签都有一个查询字符串样式的等同物。（同时注意接受query-string样式的参数的名称，通常以'wp_'作为前缀，例如wp_list_cats()，但是你要查看标签的文件，确定标签接受参数的方法。）

The tag wp_list_authors() has six parameters, of which we set three here:

标签wp_list_authors()有六个参数，我们在这里设置了其中的三个参数：

<?php wp_list_authors('show_fullname=1&feed=rss&optioncount=1'); ?>

<?php wp_list_authors('show_fullname=1&feed=rss&optioncount=1'); ?>

First, all the parameters together are enclosed by either single or double quotes. Then each parameter is entered in the parameter=value format, while these are separated with an ampersand (&). Broken down, the tag as shown above states:

首先，所有的参数在一起，都是由单引号或者双引号括起来的。每个参数都输入进了parameter=value格式，但是这些是由一个&(&)分开的。Broken down，上述显示的标签声明：

• Parameter show_fullname (a boolean type parameter) equals 1 (true).
• 参数 show_fullname (boolean 样式的参数) 等同于1 (正确的)。

AND

和

• Parameter feed (a string type parameter) equals rss.

• 参数feed (string 样式参数)等同于 rss。

AND

和

• Parameter optioncount (a boolean type parameter) equals 1 (true).

• 参数 optioncount (boolean 样式参数)等同于1 (正确的)。

(See [[WordPress:#Types of parameters|Types of parameters]] for information on parameter types and how to use them.)

(请看看 [[WordPress:#Types of parameters|参数类型]]关于参数样式以及怎样使用这些参数样式的信息。)

Parameters in the query-string style do not have to be entered in a specific order. The only real concern is assuring parameter names are spelled correctly. If legibility is a problem, you can separate parameters with a space:

query-string样式的参数不需要以一个特别的顺序输入。真正需要在意的是确保参数名称的拼写是正确的。如果参数名不容易读出，你可以用空格分开参数：

<?php wp_list_authors('show_fullname=1 & feed=rss & optioncount=1'); ?>

<?php wp_list_authors('show_fullname=1 & feed=rss & optioncount=1'); ?>

You can also spread a query-string over several lines (note the specific format of enclosing each parameter/value pair in single quotes and a dot starting each new line):

你也可以将query-string扩展在几行上（注意将每个参数/参数值放入一个单引号和以一个点号开始一个新行）：

<?php wp_list_authors(
                      'show_fullname=1'
                      .'&feed=rss'
                      .'&optioncount=1'
                      ); ?>

<?php wp_list_authors(

                      'show_fullname=1'
                      .'&feed=rss'
                      .'&optioncount=1'
                      ); ?>

There are a few limitations when using query-string style tags, among which you cannot pass certain characters, such as the ampersand or a quote mark (single or double). In those cases, you can use an associative array:

使用query-string格式标签有一些限制，你可以传递某些字符，例如&符号和引号（单引号或者双引号）。在这些情况下，你可以使用一个联合的数组：

<?php $params = array( 'type'   => 'postbypost',
                       'limit'  => 5,
                       'format' => 'custom',
                       'before' => '<li>&bull;&nbsp;',
                       'after'  => '</li>' );
wp_get_archives($params); ?>

<?php $params = array( 'type' => 'postbypost',

                       'limit'  => 5,
                       'format' => 'custom',
                       'before' => '<li>&bull;&nbsp;',
                       'after'  => '</li>' );
wp_get_archives($params); ?>

参数的类型

There are three types of parameters you need to know about in regards to WordPress template tags: string, integer, and boolean. Each is handled a bit differently, as described below.

关于WordPress模板标签，你需要了解三种类型的参数：字符串，整数和boolean。每个参数的处理都有所不同，如下面所描述的：

字符串

A string is a line of text, and is typically anything from a single character to several dozen words. A string parameter is often a selection from two or more valid options, as is the show parameter in bloginfo(). Otherwise, a string is intended as text to be displayed, such as the sep parameter in wp_title().

一个字符串是一行文本，而且通常是一个单独的字符或者几十个单词。一个字符串参数通常是从两个或者多个有效的选项中选择的，就如bloginfo()中的show参数。否则的话，字符串是一个显示的文本，例如wp_title()中的sep参数。

In tags which use the [[WordPress:#Tags with PHP function-style parameters|PHP function parameter style]], string values should be enclosed in single (') or double (") quotation marks. If a single or double quote is required for part of your string, mix the marks (using double quotes to enclose the parameter if a single quote exists in your parameter value), or use the PHP escape character (a backslash: \), as the following does to assign single quotes for the before and after parameters in the_title():

使用[[WordPress:#Tags with PHP function-style parameters|PHP 函数参数格式]]的标签，字符串参数值应该包含在一个单引号(')或者双引号(")之中。如果单引号或者双引号需要部分的字符串，将引号混合使用（如果单引号存在在你的参数值中，使用双引号包裹参数），或者使用PHP escape参数(一个反斜线符号: \)，如下所执行的，为the_title()中的之前和之后参数指定单引号。

<?php the_title('\'', '\''); ?> 

<?php the_title('\'', '\''); ?>

整数

An integer is a whole number, and can have a positive (1, 2, 3) or negative (-1, -2, -3) value. Integer parameters are often used for date and archive based information, like the year and month parameters for the get_month_link() tag, or for specifying the numeric value of something on your blog, as one finds in the case of the id parameter in get_permalink().

整数是一个整数，而且可以有正整数（1，2，3）或者负整数（-1，-2，-3）。整数参数通常用作日期和归档方面的信息，如get_month_link()标签中的年和 月参数，或者用来规定你的博客上的数值信息，如get_permalink()中的id参数。

When passed to a [[WordPress:#Tags with PHP function-style parameters|PHP function parameter style]] tag, integer values either in or out of quotes will be handled correctly. So the following examples are both valid:

当传递到[[WordPress:#Tags with PHP function-style parameters|PHP函数参数格式]]标签中的时候，引号内或者引号外的整数值都会得到合适地处理。因此下面的两个例子都是有效的：

<?php get_permalink('100'); ?> 

<?php get_permalink(100); ?> 

<?php get_permalink('100'); ?>

<?php get_permalink(100); ?> 

Boolean

Boolean parameters provide a simple true/false evaluation. Boolean参数提供了一个简单的正确的/错误的评价。

For example, the the_date() tag has an echo parameter which takes either TRUE or FALSE as a value; setting the parameter to TRUE displays the date on the page, whereas FALSE causes the tag to "return" the date as a value that can then be used in other PHP code.

例如，the_date()标签有echo参数，将正确的 或者 错误的作为参数值；将参数设置为正确的，能在网页上显示日期，然而错误的导致标签"返回"日期作为参数值，用于其它的PHP代码。

A boolean parameter can be notated as a numeric value: 1 for TRUE, 0 for FALSE. For a boolean value in [[WordPress:#Tags with PHP function-style parameters|PHP function parameter style]] tags, these are all equivalent:

一个boolean参数可以表示为一个数值：1表示正确的, 0表示错误的。对于[[WordPress:#Tags with PHP function-style parameters|PHP函数参数样式]]标签中的一个boolean参数值，这些都是对等值：

• 1 = TRUE = true
• 0 = FALSE = false

• 1 = 正确的 = 正确的
• 0 = 错误的 = 错误的

However, do NOT enclose boolean values within quote marks. For [[WordPress:#Tags with query-string-style parameters|query-string style tags]], use only the numeric boolean values (1 or 0).

然而，不要将boolean参数值放入双引号中。[[WordPress:#Tags with query-string-style parameters|query-string样式标签]]只使用数字式的boolean参数值(1 or 0)。

Go to Template Tag index