WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

pt-br:Referência de Funções/query posts

Descrição

Dentre todas as formas de modificar a query principal do WordPress, query_posts() é a mais simples, mas não é a preferida, nem a mais eficiente. Ela ignora a query principal e a substitui por uma nova. Para retornar à query principal depois de uma chamada a query_posts(), use a função wp_reset_query() e ela será restaurada.

É muito preferível e recomendado que ao invés de query_posts() você use a action pre_get_posts, alterando a query principal - que você pode detectar checando com is_main_query.

Por exemplo: na página principal você normalmente verá 10 posts. Se quiser mostrar apenas 5 (e não se importar com a paginação), você pode usar query_posts() assim:

query_posts( 'posts_per_page=5' );

Abaixo você vê a mesma funcionalidade, mas usando pre_get_posts no arquivo functions.php:

function five_posts_on_homepage( $query ) {
    if ( $query->is_home() && $query->is_main_query() ) {
        $query->set( 'posts_per_page', '5' );
    }
}
add_action( 'pre_get_posts', 'five_posts_on_homepage' );

Ressalvas

query_posts() é somente uma dentre várias maneiras de buscar informações no banco de dados e gerar uma lista de posts. Antes de se decidir por ela, tenha certeza que conhece as desvantagens.

Altera o loop principal

query_posts() foi criada para alterar o loop principal. Ela faz isso substituindo a query usada para gerar o conteúdo do loop principal. A cada vez que você usar query_posts(), as variáveis globais relacionadas aos posts e as Template Tags também serão alteradas - isso pode ou não ser o que resultado que você deseja.

Loops secundários

Para criar listas secundárias - por exemplo, uma lista de posts relacionados no rodapé ou uma lista de links na barra lateral - experimente criar uma nova instância da classe WP_Query, ou use get_posts().

Se você absolutamente necessita usar query_posts(), então certifique-se de chamar wp_reset_query() depois que usar os dados.

Paginação

A paginação não vai funcionar corretamente a menos que você use o argumento 'paged' da forma correta: adding the paged parameter

Consultas SQL adicionais

Quando query_posts é usada em um template, quando o WordPress chegar a ler e executar o seu template, já terá executado a query original e carregado do banco de dados os registros dela - é assim que ele determina qual template irá mostrar na tela! Então, quando você altera a query original com query_posts você está jogando fora a query original e os seus resultados e executando uma nova consulta ao banco de dados.

Isso não é necessariamente um problema se você está lidando com um site ou um blog pequeno e com poucos acessos. Desenvolvedores de grandes sites, com grandes bancos de dados e muito tráfego provavelmente preferirão a alternativa de modificar a query original direntamente (antes que ela seja executada). O filtro request pode ser usado para esse fim.

As actions 'parse_query' e pre_get_posts também estão disponíveis para modificar o objeto $query, que é usado para gerar a consulta SQL ao banco.

Como usar

<?php
// The Query
query_posts$args );

// The Loop
while ( have_posts() ) : the_post();
    echo 
'<li>';
    
the_title();
    echo 
'</li>';
endwhile;

// Reset Query
wp_reset_query();
?>
Coloque uma chamada para query_posts() e um dos seus arquivos de Template antes de iniciar o Loop. O objeto wp_query vai gerar uma nova consulta SQL usando os seus parâmetros. Quando você faz isso, o WordPress ignora os outros parâmetros que recebe pela URL, como por exemplo o número da página ou uma categoria.

Preservando os parâmetros existentes da consulta

Para preservar alguns parâmetros originais utilizados para gerar a consulta atual, e modificar outros, você pode usar a variável global $query_string na chamada a query_posts().

Por exemplo, para alterar a order de visualização dos posts sem afetar o restante da string de consulta você pode colocar o seguinte código antes do Loop:

global $query_string;
query_posts( $query_string . '&order=ASC' );

Ateção: quando usar query_posts() dessa forma, a parte entre aspas do parâmetro precisa começar com um "E" comercial (&).

Outra maneira de conseguir o mesmo efeito é combinar o array original da consulta com o array dos seus parâmetros:

global $wp_query;
$args = array_merge( $wp_query->query_vars, array( 'post_type' => 'product' ) );
query_posts( $args );

Combinando parâmetros

Você viu em alguns exemplos que os parâmetros são combinados com um "E" comercial (&), como em:

query_posts( 'cat=3&year=2004' );

Retornar posts da categoria 13, no mês atual, na página principal:

if ( is_home() ) {
	query_posts( $query_string . '&cat=13&monthnum=' . date( 'n', current_time( 'timestamp' ) ) );
}

Retornar posts das categorias 1 E 3, mostrando no máximo 2 posts, em ordem descendente, ordenados pelo título:

query_posts( array( 'category__and' => array(1,3), 'posts_per_page' => 2, 'orderby' => 'title', 'order' => 'DESC' ) );

Retornar todos os posts que pertencem à categoria 1 e tem a tag "apples":

query_posts( 'cat=1&tag=apples' );

Você pode usar + para buscar por mais de uma tag:

query_posts( 'cat=1&tag=apples+apples' );

Parâmetros

Atenção: A explicação e mais detalhes sobre cada parâmetro estão na seção parâmetros do artigo sobre a Classe WP_Query.

Os exemplos abaixo também funcionam com o objeto WP_Query.

Exemplos

Excluir categorias da página inicial

Colocar este código no arquivo index.php fará com que a página inicial mostre posts de todas as categorias exceto a categoria com ID 3.

<?php
if ( is_home() ) {
	query_posts( 'cat=-3' );
}
?>

Você também pode inserir mais categorias na lista de exclusão:

<?php
if ( is_home() ) {
	query_posts( 'cat=-1,-2,-3' );
}
?>

Retornar um post específico

Para buscar um post específico você pode usar:

query_posts( 'p=5' );

Atenção: Se o post em questão for um anexo (imagem, documento, áudio, vídeo, etc), é preciso usar attachment_id ao invés de p:

query_posts( 'attachment_id=5' );

Se quiser usar a funcionalidade de Leia mais com esta consulta, você vai precisar definir a variável global $more como 0.

<?php
// buscar um post com o ID 5
query_posts( 'p=5' );

// definir $more como 0 para pegar somente a primeira parte do post
global $more;
$more = 0;

// the Loop
while (have_posts()) : the_post();
	the_content( 'Read the full post »' );
endwhile;
?>

Todos os posts em uma categoria

The "Blog pages show at most" parameter in Settings > Reading can influence your results. To overcome this, add the 'posts_per_page' parameter. For example:

query_posts( array ( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );

This will returns ALL posts from the category.

However, for subcategories (or child categories), 'The Category Name' doesn't always work. Rather use 'category-slug' instead. See Function_Reference/is_category.

if (is_category('category-slug')): 

	 query_posts(array('category_name' => 'my-category-slug', 'posts_per_page' => -1 )); 

endif; 

Syndication Feeds

The "Syndication feeds show the most recent" or 'posts_per_rss' parameters in Settings > Reading will overwrite any 'posts_per_page' parameter in a query used in a feed.

To overcome use (for example in a a custom ics feed, where all matching posts are required), use the "posts_limit" filter as follows:

if ( isset ( $query->query_vars['feed'] ) and ( $query->query_vars['feed'] == 'ics' ) )
{
	add_filter( 'post_limits', '__return_empty' );
}

Passing variables to query_posts

You can pass a variable to the query with two methods, depending on your needs. As with other examples, place these above your Loop:

Example 1

In this example, we concatenate the query before running it. First assign the variable, then concatenate and then run it. Here we're pulling in a category variable from elsewhere.

// assign the variable as current category
$categoryvariable = $cat;

// concatenate the query
$args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC';

// run the query
query_posts( $args );

Example 2

In this next example, the double quotes tell PHP to treat the enclosed as an expression. For this example, we are getting the current month and the current year, and telling query_posts() to bring us the posts for the current month/year, and in this case, listing in ascending order so we get the oldest post at the top of the page.

$current_year = date('Y');
$current_month = date('m');

query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" );

Example 3

This example explains how to generate a complete list of posts, dealing with pagination. We can use the default $query_string telling query_posts() to bring us a full posts listing. We can also modify the posts_per_page query parameter from -1 to the number of posts you want to show on each page; in this last case, you'll probably want to use posts_nav_link() to navigate the generated archive.

query_posts( $query_string . '&posts_per_page=-1' );

Example 4

If you don't need to use the $query_string variable, another method exists that is more clear and readable, in some more complex cases. This method puts the parameters into an array. The same query as in Example 2 above could be done like this:

$args = array(
	'cat'      => 22,
	'year'     => $current_year,
	'monthnum' => $current_month,
	'order'    => 'ASC'
);
query_posts( $args );

As you can see, with this approach, every variable can be put on its own line, for easier reading.

Example 5

It is even possible to use the array style (Example 4) to query multiple taxonomies. Simply supply the taxonomy slug with a string of comma-separated values (each value being one term). In the example below, we will get all movie posts starring either Bruce Campbell or Chuck Norris.

$args = array(
	'post_type'=> 'movie',
	'actor'    => 'Bruce Campbell, Chuck Norris',
	'order'    => 'ASC'
);
query_posts( $args );

Change Log

Since: 1.5.0

Source File

query_posts() is located in wp-includes/query.php.

Resources

Related

Articles

Code Documentation

See also index of Function Reference and index of Template Tags.