تابع wp_list_pages در وردپرس

تابع wp_list_pages() یکی از توابع مهم در وردپرس است که برای نمایش لیست صفحات (Pages) سایت استفاده می‌شود. این تابع بیشتر در قالب‌ها (Themes) برای ساخت منوهای ساده یا نمایش سلسله‌مراتبی صفحات به کار می‌رود. در این آموزش، به صورت جامع نحوه‌ی استفاده از این تابع، پارامترهای آن، مثال‌های کاربردی، و نکات بهینه‌سازی و امنیتی آن را بررسی خواهیم کرد.

کاربرد اصلی تابع `wp_list_pages()`

این تابع وظیفه دارد لیستی از صفحات منتشر شده‌ی وردپرس را در قالب HTML برگرداند. به طور پیش‌فرض، خروجی این تابع به صورت یک لیست نامرتب (<ul>) نمایش داده می‌شود که هر مورد آن یک لینک به صفحه مربوطه دارد.

<?php 
wp_list_pages();
?>

در این حالت، تابع بدون هیچ پارامتری تمام صفحات سایت را نمایش می‌دهد. اما در پروژه‌های واقعی معمولاً نیاز داریم کنترل بیشتری روی خروجی داشته باشیم، مثلاً فقط صفحات خاصی را نشان دهیم یا ترتیب نمایش را تغییر دهیم.

ساختار کلی تابع `wp_list_pages()`

wp_list_pages( string | array $args = '' )

آرگومان $args شامل مجموعه‌ای از گزینه‌هاست که می‌توان آن را به صورت رشته یا آرایه ارسال کرد. این پارامترها به ما اجازه می‌دهند رفتار تابع را شخصی‌سازی کنیم.

برخی از پارامترهای مهم تابع

پارامتر	توضیح	مقدار پیش‌فرض
`depth`	تعیین عمق نمایش صفحات (۰ برای همه‌ی سطوح)	0
`child_of`	نمایش فقط صفحات زیرمجموعه‌ی یک صفحه‌ی خاص	0
`exclude`	مستثنی کردن صفحات بر اساس ID	”
`include`	نمایش فقط صفحات خاص	”
`title_li`	عنوان لیست (درون `<li>`)	‘Pages’
`sort_column`	تعیین ستون مرتب‌سازی مانند `post_title` یا `menu_order`	‘menu_order, post_title’
`echo`	اگر مقدار false باشد، خروجی بازگردانده می‌شود و چاپ نمی‌شود	true

نمونه کد برای نمایش صفحات به صورت سفارشی

<?php
wp_list_pages( array(
  'title_li'    => '',
  'exclude'     => '10,15',
  'sort_column' => 'menu_order',
  'depth'       => 1
) );
?>

در مثال بالا، لیستی از صفحات سطح اول (بدون زیرصفحه) نمایش داده می‌شود. صفحات با شناسه‌ی ۱۰ و ۱۵ از لیست حذف شده‌اند و ترتیب نمایش بر اساس menu_order تعیین می‌شود.

نحوه استفاده در قالب وردپرس

یکی از رایج‌ترین مکان‌های استفاده از این تابع، فایل sidebar.php یا header.php قالب است، جایی که معمولاً منوی اصلی یا ناوبری صفحات قرار دارد:

<div class="page-menu">
  <ul>
    <?php wp_list_pages( array( 'title_li' => '' ) ); ?>
  </ul>
</div>

در این حالت، می‌توانید با CSS استایل دلخواه خود را برای کلاس .page-menu تعریف کنید تا ظاهر لیست مطابق طراحی سایت شود.

بازگرداندن خروجی به جای چاپ مستقیم

گاهی نیاز دارید خروجی تابع را در متغیری ذخیره کنید و بعداً از آن استفاده نمایید. برای این کار کافی است مقدار پارامتر echo را false قرار دهید:

<?php
$pages = wp_list_pages( array(
  'title_li' => '',
  'echo'     => false
) );

echo '<div class="custom-menu">' . $pages . '</div>';
?>

این روش زمانی مفید است که بخواهید قبل از نمایش نهایی، تغییراتی روی خروجی اعمال کنید (مثلاً افزودن کلاس‌های CSS یا ویرایش ساختار HTML).

مثال کاربردی: نمایش صفحات فرزند یک صفحه خاص

اگر می‌خواهید فقط زیرصفحات یک صفحه خاص (مثلاً صفحه “خدمات”) را نمایش دهید، باید از پارامتر child_of استفاده کنید:

<?php
wp_list_pages( array(
  'title_li' => '',
  'child_of' => 25
) );
?>

در این مثال، تنها صفحاتی نمایش داده می‌شوند که زیرمجموعه‌ی صفحه‌ای با شناسه ۲۵ هستند. این روش برای ساخت منوی فرعی در صفحات داخلی بسیار کاربردی است.

افزودن کلاس فعال (Active Class) به صفحه جاری

وردپرس به‌صورت خودکار به صفحه فعال کلاس current_page_item را اضافه می‌کند. می‌توانید در فایل CSS خود آن را استایل‌دهی کنید:

.current_page_item a {
  font-weight: bold;
  color: #2196f3;
}

این قابلیت باعث می‌شود کاربران بدانند در کدام صفحه از سایت قرار دارند.

تفاوت `wp_list_pages()` و `wp_nav_menu()`

بسیاری از توسعه‌دهندگان تازه‌کار بین این دو تابع سردرگم می‌شوند. در جدول زیر تفاوت‌های کلیدی این دو تابع را مشاهده می‌کنید:

ویژگی	`wp_list_pages()`	`wp_nav_menu()`
نوع داده	صفحات (Pages)	منوهای دلخواه (Menus)
قابلیت درگ‌و‌دراپ	ندارد	دارد (در پنل مدیریت)
قابلیت نمایش دسته‌ها	خیر	بله (در صورت تنظیم لینک سفارشی)
سطح کنترل	پایین‌تر، مناسب لیست ساده	بیشتر، مناسب ناوبری اصلی سایت

به طور خلاصه، اگر می‌خواهید منوی پویا و قابل تنظیم از بخش “نمایش > فهرست‌ها” بسازید، از wp_nav_menu() استفاده کنید. اما اگر فقط قصد دارید ساختار صفحات را به‌صورت خودکار نمایش دهید، wp_list_pages() گزینه‌ی بهتری است.

نکات بهینه‌سازی و بهترین شیوه‌ها

حذف صفحات غیرضروری: همیشه صفحات پیش‌نویس یا تستی را از خروجی مستثنی کنید تا کاربر فقط صفحات نهایی را ببیند.
کَش کردن خروجی: اگر سایت تعداد زیادی صفحه دارد، خروجی این تابع را با توابعی مانند wp_cache_set() در حافظه نگه دارید تا سرعت سایت کاهش نیابد.
رعایت دسترسی (Accessibility): از برچسب‌های <nav> و aria-label استفاده کنید تا لیست صفحات برای کاربران با نیازهای خاص نیز قابل استفاده باشد.
امنیت: هرگز مقدار پارامترها را مستقیماً از ورودی کاربر نگیرید؛ آن‌ها را اعتبارسنجی کنید.

نمونه‌ی کامل یک منوی صفحات سفارشی

<nav class="main-page-nav" aria-label="Main Page Navigation">
  <ul>
    <?php
      echo wp_list_pages( array(
        'title_li' => '',
        'depth' => 2,
        'exclude' => '12,14',
        'sort_column' => 'menu_order',
        'echo' => false
      ) );
    ?>
  </ul>
</nav>

این کد، منویی دو سطحی از صفحات سایت ایجاد می‌کند که صفحات با شناسه‌های ۱۲ و ۱۴ حذف شده‌اند. با اضافه کردن CSS مناسب، می‌توانید آن را به یک منوی واکنش‌گرا و زیبا تبدیل کنید.

جمع‌بندی نکات مهم

تابع wp_list_pages() برای نمایش خودکار ساختار صفحات وردپرس استفاده می‌شود.
می‌توانید با پارامترهایی مانند depth، exclude، و child_of خروجی را کنترل کنید.
با استفاده از echo => false خروجی تابع را در متغیر ذخیره کرده و سفارشی‌سازی کنید.
برای منوهای حرفه‌ای‌تر، wp_nav_menu() گزینه مناسب‌تری است.

آیا این مطلب برای شما مفید بود ؟

خیر

بله