آموزش تابع get_the_excerpt() در وردپرس و کاربرد آن

تابع get_the_excerpt() یکی از توابع پرکاربرد در وردپرس برای دریافت خلاصهٔ مطلب (excerpt) یک پست است. این تابع می‌تواند خلاصهٔ نوشته‌ای را که به‌صورت دستی وارد شده باشد بازگرداند یا در صورت نبودن خلاصهٔ دستی، از محتوای پست یک خلاصهٔ خودکار تولید کند. در این مقاله به‌صورت عملی و دقیق ساختار، فیلترها، نمونه‌کدها و بهترین روش‌های استفاده را بررسی می‌کنیم.

تفاوت get_the_excerpt() و the_excerpt()

• get_the_excerpt(): مقدار خلاصه را بازمی‌گرداند (return). مناسب وقتی می‌خواهید آن را در متغیری قرار دهید، پردازش کنید یا قبل از چاپ فیلترها و تغییرات دیگری اعمال کنید.
• the_excerpt(): مقدار خلاصه را مستقیماً چاپ می‌کند (echo). معمولاً درون لوپ قالب برای نمایش سریع استفاده می‌شود.

نحوهٔ عملکرد داخلی (خلاصه)

روال کلی تابع:

• اگر پست قفل شده با رمز عبور باشد، معمولاً پیام محافظت‌شده برمی‌گردد.
• اگر فیلد post_excerpt (خلاصهٔ دستی) مقدار داشته باشد، از همان استفاده می‌شود.
• در غیر این صورت، از محتوای پست (post_content) با حذف شورت‌کدها و تگ‌ها، یک خلاصهٔ خودکار تولید می‌شود (با استفاده از توابعی مانند wp_trim_excerpt و wp_trim_words).
• در نهایت، مقدار بازگشتی از طریق فیلترهای وردپرس (مثل get_the_excerpt) عبور می‌کند تا توسعه‌دهندگان بتوانند آن را تغییر دهند.

استفادهٔ پایه

// درون لوپ یا زمانی که پست فعلی در دسترس است
echo get_the_excerpt();

این کد خلاصهٔ پست جاری را برمی‌گرداند و آن را چاپ می‌کند. اگر می‌خواهید خلاصه را در متغیری نگه دارید:

$excerpt = get_the_excerpt($post_id);
echo esc_html($excerpt);

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

تنظیم طول خلاصه

طول خلاصهٔ خودکار با فیلتر excerpt_length قابل تغییر است (پیش‌فرض معمولاً 55 کلمه). مثال:

// تغییر طول خلاصه به 20 کلمه
add_filter('excerpt_length', function($length) {
    return 20;
}, 999);

این کد طول خلاصه‌های تولیدشدهٔ خودکار را به 20 کلمه تغییر می‌دهد. مقدار اول آرگومان تابع مقدار فعلی طول است و مقدار بازگشتی طول جدید را تعیین می‌کند. اولویت بالا (999) باعث می‌شود این فیلتر نهایی شود مگر افزونه‌ای اولویت بالاتری داشته باشد.

تخصیص متن «ادامه» (more) در خلاصه

متن پایان خلاصه (مثلاً سه نقطه یا لینک «ادامه مطلب») از طریق فیلتر excerpt_more قابل تنظیم است. مثال:

// اضافه کردن لینک "ادامه" به انتهای خلاصه
add_filter('excerpt_more', function($more) {
    return '... ادامه';
});

توضیح: این فیلتر متن نهایی را تغییر می‌دهد. توجه داشته باشید که در بعضی شرایط (مثلاً زمانی که فراخوانی خارج از لوپ و بدون تنظیم global post انجام شود) تابع get_permalink() ممکن است شناسهٔ صحیح را نداشته باشد؛ در این موارد بهتر است شناسهٔ پست را به صورت صریح استفاده کنید.

چگونه تگ‌ها را نگه داریم یا فیلتر کنیم

خلاصهٔ خودکار معمولاً تگ‌های HTML را حذف می‌کند. اگر بخواهید برخی تگ‌های مجاز را نگه دارید، می‌توانید از فیلتر get_the_excerpt استفاده کرده و با wp_kses تعیین کنید چه تگ‌هایی مجازند:

add_filter('get_the_excerpt', function($excerpt, $post) {
    return wp_kses($excerpt, [
        'a' => ['href' => true, 'title' => true],
        'strong' => []
    ]);
}, 10, 2);

در این مثال، خلاصه‌ای که از تابع بازمی‌گردد فقط تگ‌های <a> و <strong> را نگه می‌دارد و بقیه تگ‌ها پاک می‌شوند. پارامتر 10 اولویت و عدد 2 نشان‌دهندهٔ شمار آرگومان‌های callback است.

نمونه‌های پیشرفته و نکات عملی

• برای نمایش خلاصهٔ یک پست دیگر خارج از لوپ: echo get_the_excerpt(123); (که 123 شناسهٔ پست است).
• اگر می‌خواهید خلاصهٔ دستی را بدون فیلترهای اضافی چاپ کنید، از get_post_field('post_excerpt', $post_id) استفاده کنید.
• برای جلوگیری از دو بار اعمال فیلترها یا بروز مشکل در قالب‌ها، همیشه خروجی را با توابعی مثل esc_html یا wp_kses_post امن کنید.
• اگر قالب شما نیاز به نمایش خلاصه‌های طولانی با HTML دارد، ممکن است بهتر باشد از فیلد سفارشی (custom field) یا متا استفاده کرده و کنترل کامل بر HTML داشته باشید.

جدول خلاصهٔ فیلترها و توابع مهم

نتیجه‌گیری و بهترین شیوه‌ها

get_the_excerpt() ابزاری ساده اما انعطاف‌پذیر برای مدیریت خلاصه‌ها در وردپرس است. بهترین روش‌ها:

• اگر نیاز به پردازش دارید از get_the_excerpt() استفاده کنید، وگرنه the_excerpt() برای چاپ سریع مناسب است.
• برای کنترل طول و متن more از فیلترهای excerpt_length و excerpt_more استفاده کنید.
• همیشه خروجی کاربرمحور را با توابع ایمن‌سازی صیقل دهید (مثل esc_html یا wp_kses).
• اگر نیاز به کنترل کامل HTML دارید، استفاده از فیلد خلاصهٔ دستی یا متا توصیه می‌شود.

با درک این نکات می‌توانید نمایش خلاصه‌ها در قالب‌ها و افزونه‌های خود را حرفه‌ای‌تر کنید و تجربهٔ کاربری بهتری ارائه دهید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال