WordPress 中文文档

Template Tags/wp list categories

出自WordPress Chinese 中文文档

跳转到: 导航, 搜索

wordpress.org.cn

目录

Description

Displays a list of Categories as links. When a Category link is clicked, all the posts in that Category will display on a Category Page using the appropriate Category Template dictated by the Template Hierarchy rules.

NOTE: wp_list_categories() works in much the same way as the two template tags replaced in WordPress 2.1, list_cats() and wp_list_cats() (both deprecated).

Usage

%%% ?php wp_list_categories( $args ); ? %%%

Default Usage

%%%?php $args = array( 'show_option_all' = , 'orderby' = 'name', 'order' = 'ASC', 'show_last_update' = 0, 'style' = 'list', 'show_count' = 0, 'hide_empty' = 1, 'use_desc_for_title' = 1, 'child_of' = 0, 'feed' = , 'feed_type' = , 'feed_image' = , 'exclude' = , 'exclude_tree' = , 'include' = , 'hierarchical' = true, 'title_li' = __( 'Categories' ), 'number' = NULL, 'echo' = 1, 'depth' = 0, 'current_category' = 0, 'pad_counts' = 0, 'taxonomy' = 'category', 'walker' = 'Walker_Category' ); ?%%%

By default, the usage shows:

  • No link to all categories
  • Sorts the list of Categories by the Category name in ascending order
  • Does not show the last update (last updated post in each Category)
  • Displayed in an unordered list style
  • Does not show the post count
  • Displays only Categories with posts
  • Sets the title attribute to the Category Description
  • Is not restricted to the child_of any Category
  • No feed or feed image used
  • Does not exclude any Category and includes all Categories
  • Displays the active Category with the CSS Class-Suffix ' current-cat'
  • Shows the Categories in hierarchical indented fashion
  • Display Category as the heading over the list
  • No SQL LIMIT is imposed ('number' = 0 is not shown above)
  • Displays (echos) the categories
  • No limit to depth
  • All categories.
  • The list is rendered using the Walker_Category class

Parameters

show_option_all 
(string) A non-blank value causes the display of a link to all categories if the style is set to list. The default value is not to display a link to all.
orderby 
(string) Sort categories alphabetically, by unique Category ID, or by the count of posts in that Category. The default is sort by category name. Valid values:
  • ttID/tt
  • ttname/tt - Default
  • ttslug/tt
  • ttcount/tt
  • ttterm_group/tt
order 
(string) Sort order for categories (either ascending or descending). The default is ascending. Valid values:
  • ttASC/tt - Default
  • ttDESC/tt
show_last_updated 
(boolean) Should the last updated timestamp for posts be displayed (TRUE) or not (FALSE). Defaults to FALSE.
  • tt1 (True)/tt
  • tt0 (False)/tt - Default
style 
(string) Style to display the categories list in. A value of list displays the categories as list items while none generates no special display method (the list items are separated by ttnowikibr/nowiki/tt tags). The default setting is list (creates list items for an unordered list). See the markup section for more. Valid values:
  • ttlist/tt - Default
  • ttnone/tt
show_count 
(boolean) Toggles the display of the current count of posts in each category. The default is false (do not show post counts). Valid values:
  • tt1 (True)/tt
  • tt0 (False)/tt - Default
hide_empty 
(boolean) Toggles the display of categories with no posts. The default is true (hide empty categories). Valid values:
  • tt1 (True)/tt - Default
  • tt0 (False)/tt
use_desc_for_title 
(boolean) Sets whether a category's description is inserted into the tttitle/tt attribute of the links created (i.e. nowikia title=emCategory Description/em href=.../nowiki). The default is true (category descriptions will be inserted). Valid values:
  • tt1 (True)/tt - Default
  • tt0 (False)/tt
child_of 
(integer) Only display categories that are children of the category identified by this parameter. There is no default for this parameter.
feed 
(string) Display a link to each category's rss-2 feed and set the link text to display. The default is no text and no feed displayed.
feed_type 
(string)
feed_image 
(string) Set a URI for an image (usually an rss feed icon) to act as a link to each categories' rss-2 feed. This parameter overrides the feed parameter. There is no default for this parameter.
exclude 
(string) Exclude one or more categories from the results. This parameter takes a comma-separated list of categories by unique ID, in ascending order. See the example. The child_of parameter is automatically set to false.
exclude_tree 
(string) Exclude category-tree from the results. This parameter added at Version 2.7.1
include 
(string) Only include the categories detailed in a comma-separated list by unique ID, in ascending order. See the example.
hierarchical 
(boolean) Display sub-categories as inner list items (below the parent list item) or inline. The default is true (display sub-categories below the parent list item). Valid values:
  • tt1 (True)/tt - Default
  • tt0 (False)/tt
title_li 
(string) Set the title and style of the outer list item. Defaults to Categories. If present but empty, the outer list item will not be displayed. See below for examples.
number 
(integer) Sets the number of Categories to display. This causes the SQL LIMIT value to be defined. Default to no LIMIT.
echo 
(boolean) Show the result or keep it in a variable. The default is true (display the categories organized). This parameter added at Version 2.3 Valid values:
  • tt1 (True)/tt - Default
  • tt0 (False)/tt
depth 
(integer) This parameter controls how many levels in the hierarchy of Categories are to be included in the list of Categories. The default value is 0 (display all Categories and their children). This parameter added at Version 2.5
  • tt0/tt - All Categories and child Categories (Default).
  • tt-1/tt - All Categories displayed in flat (no indent) form (overrides hierarchical).
  • tt1/tt - Show only top level Categories
  • ttn/tt - Value of n (some number) specifies the depth (or level) to descend in displaying Categories
current_category 
(integer) Allows you to force the current-cat to appear on uses of wp_list_categories that are not on category archive pages. Normally, the current-cat is set only on category archive pages. If you have another use for it, or want to force it to highlight a different category, this overrides what the function thinks the current category is. This parameter added at Version 2.6
pad_counts 
(boolean) Calculates link or post counts by including items from child categories. If show_counts and hierarchical are true this is automatically set to true. This parameter added at Version 2.9 Valid values:
  • tt1 (true)/tt
  • tt0 (false)/tt - default
taxonomy 
(string) Taxonomy to return. This parameter added at Version 3.0 Valid values:
  • ttcategory/tt - default
  • tttaxonomy/tt - or any registered taxonomy
walker 
(object) Walker class to render the list with. Valid values:
  • ttobject/tt - an instance of a class that extends either Walker_Category or Walker

Examples

Include or Exclude Categories

To sort categories alphabetically and include only the categories with IDs of 16, 3, 9 and 5, you could write the following code:

pre lt;ulgt; lt;?php wp_list_categories('orderby=nameinclude=3,5,9,16'); ?gt; lt;/ulgt; /pre

The following example displays category links sorted by name, shows the number of posts for each category, and excludes the category with the ID of 10 from the list.

pre lt;ulgt; lt;?php wp_list_categories('orderby=nameshow_count=1exclude=10'); ?gt; lt;/ulgt; /pre

Display or Hide the List Heading

The title_li parameter sets or hides a title or heading for the category list generated by wp_list_categories. It defaults to tt'(__('Categories')'/tt, i.e. it displays the word Categories as the list's heading. If the parameter is set to a null or empty value, no heading is displayed. The following example code excludes categories with IDs 4 and 7 and hides the list heading:

pre lt;ulgt; lt;?php wp_list_categories('exclude=4,7title_li='); ?gt; lt;/ulgt; /pre

In the following example, only Cateogories with IDs 9, 5, and 23 are included in the list and the heading text has been changed to the word Poetry, with a heading style of ttnowikih2/nowiki/tt:

pre lt;ulgt; lt;?php wp_list_categories('include=5,9,23title_li=lt;h2gt;' . __('Poetry') . 'lt;/h2gt;' ); ?gt; lt;/ulgt; /pre

Only Show Children of a Category

The following example code generates category links, sorted by ID, only for the children of the category with ID 8; it shows the number of posts per category and hides category descriptions from the tttitle/tt attribute of the generated links. Note: If there are no posts in a parent Category, the parent Category will not display.

pre lt;ulgt; lt;?php wp_list_categories('orderby=idshow_count=1use_desc_for_title=0child_of=8'); ?gt; lt;/ulgt; /pre

Remove Parentheses from Category Counts

When ttshow_count=1/tt, each category count is surrounded by parentheses. In order to remove the parentheses without modifying core WordPress files, use the following code.

pre lt;?php $variable = wp_list_categories('echo=0show_count=1title_li=lt;h2gt;Categorieslt;/h2gt;'); $variable = str_replace(array('(',')'), , $variable); echo $variable; ?gt; /pre

Display Categories with RSS Feed Links

The following example generates Category links sorted by name, shows the number of posts per Category, and displays links to the RSS feed for each Category.

pre lt;ulgt; lt;?php wp_list_categories('orderby=nameshow_count=1feed=RSS'); ?gt; lt;/ulgt; /pre

To replace the rss link with a feed icon, you could write:

pre lt;ulgt; lt;?php wp_list_categories('orderby=nameshow_count=1feed_image=/images/rss.gif'); ?gt; lt;/ulgt; /pre

Display Terms in a custom taxonomy

With Version 3.0 the taxonomy parameter was added to enable wp_list_categories() function to list Custom Taxonomies. This example list the terms in the taxonomy genre:

pre ?php //list terms in a given taxonomy using wp_list_categories (also useful as a widget if using a PHP Code plugin)

$taxonomy = 'genre'; $orderby = 'name'; $show_count = 0; // 1 for yes, 0 for no $pad_counts = 0; // 1 for yes, 0 for no $hierarchical = 1; // 1 for yes, 0 for no $title = ;

$args = array( 

 'taxonomy'     = $taxonomy,
 'orderby'      = $orderby,
 'show_count'   = $show_count,
 'pad_counts'   = $pad_counts,
 'hierarchical' = $hierarchical,
 'title_li'     = $title

); ?

ul ?php wp_list_categories( $args ); ? /ul /pre

Markup and Styling of Category Lists

By default, wp_list_categories() generates nested unordered lists (ttul/tt) within a single list item (ttli/tt) titled Categories.

You can remove the outermost item and list by setting the tttitle_li/tt parameter to an empty string. You'll need to wrap the output in an ordered list (ttol/tt) or unordered list yourself (see the examples below). If you don't want list output at all, set the ttstyle/tt parameter to varnone/var.

You can style the output with these CSS selectors : 

 li.categories { ... }  /* outermost list item */
 li.cat-item { ... }
 li.cat-item-7 { ... }  /* category ID #7, etc */
 li.current-cat { ... }
 li.current-cat-parent { ... }
 ul.children { ... }

Changelog

  • Since: 2.1.0
  • 2.3.0 : Added the codeecho/code parameter.
  • 2.5.0 : Added the codedepth/code parameter.
  • 2.6.0 : Added the codecurrent_category/code parameter.
  • 2.7.1 : Added the codeexclude_tree/code parameter.
  • 2.9 : Added the codepad_counts/code parameter.
  • 3.0 : Added the codetaxonomy/code parameter.

Source File

ttwp_list_categories()/tt is located in onlyincludecodewp-includes/category-template.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre已侦测回归模板: Template:Trac/pre

Link to trunk: pre已侦测回归模板: Template:Trac/pre

/div

wordpress.org.cn.

Related

the_category, the_category_rss, single_cat_title, category_description, wp_dropdown_categories, wp_list_categories, get_the_category, get_category_parents, get_category_link, is_category, in_category , get_categories

wp_list_authors, wp_list_categories, wp_list_pages, wp_list_bookmarks, wp_list_comments, wp_get_archives, wp_page_menu, wp_dropdown_pages, wp_dropdown_categories, wp_dropdown_users

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 已侦测回归模板: Template:Message /pre

Result

已侦测回归模板: Template:Message

/noinclude

取自"http://codex.wordpress.org.cn/Template_Tags/wp_list_categories"
wordpress