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

تابع wp_trim_words() یکی از ابزارهای ساده و کاربردی وردپرس برای کوتاه‌سازی متن بر اساس تعداد کلمات است. این تابع عمدتاً برای نمایش خلاصه‌ها (excerpts)، کارت‌های مطالب، یا هر جایی که نیاز به نمایش نسخه کوتاه‌شده از محتوای کامل دارید، استفاده می‌شود. در این مقاله به صورت دقیق پارامترها، مثال‌های عملی، نکات فنی و یک راهکار پیشرفته برای حفظ تگ‌های HTML هنگام بریدن متن بررسی می‌کنیم.

پارامترهای اصلی و رفتار تابع

• $text: رشته ورودی که می‌خواهید کوتاه شود (مثلاً محتوای پست)
• $num_words: تعداد کلماتی که باید نگه داشته شوند (پیش‌فرض 55)
• $more: رشته‌ای که در انتها اضافه می‌شود در صورت کوتاه شدن متن (مثلاً “…”)

به طور پیش‌فرض wp_trim_words متن را به صورت plain text در نظر می‌گیرد و تگ‌های HTML را نادیده می‌گیرد (یعنی تگ‌ها حذف می‌شوند) و سپس متن را بر اساس تعداد کلمه برش می‌دهد. اگر تعداد کلمات ورودی از مقدار تعیین‌شده بیشتر باشد، مقدار $more به انتهای خروجی اضافه می‌شود.

نمونه ساده استفاده در قالب (Template)

<?php
echo wp_trim_words( get_the_content(), 20, ' … ' );
?>

این مثال محتوای پست جاری را گرفته و فقط 20 کلمه اول آن را نمایش می‌دهد و در صورت کوتاه شدن، یک «…» HTML-encoded در انتها می‌افزاید. این روش رایج برای نمایش خلاصه در لیست مقالات یا کارت‌ها است.

مثال: ساخت شورت‌کد برای خلاصه دلخواه

<?php
function my_trim_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'words' => 30,
        'more' => '…',
    ), $atts, 'trim' );

    $content = get_the_content();
    return wp_trim_words( $content, intval( $atts['words'] ), $atts['more'] );
}
add_shortcode( 'trim', 'my_trim_shortcode' );
?>

این کد یک شورت‌کد [trim] می‌سازد که می‌توانید در هر محتوایی از آن استفاده کنید و با پارامتر words تعداد کلمات را تنظیم کنید. مثال استفاده: [trim words=”15″]

تفاوت با توابع مشابه

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

• برای نمایش خلاصه در لیست پست‌ها اغلب از wp_trim_words روی get_the_content() یا get_the_excerpt() استفاده می‌شود.
• اگر می‌خواهید استایل‌های HTML ساده (مثل <strong> یا <em>) حفظ شوند، wp_trim_words مناسب نیست زیرا تگ‌ها را حذف می‌کند.
• برای تغییر مقدار پیش‌فرض خلاصه در وردپرس می‌توانید فیلترهای excerpt_length و excerpt_more را استفاده کنید، که مرتبط با عملکرد کلی excerpt هستند.
• در متن‌های فارسی و زبان‌های راست‌به‌چپ، تابع با توجه به فاصله‌ها (space) عمل می‌کند؛ اگر بین کلمات از کاراکترهای غیرمعمول استفاده شده باشد ممکن است نتایج متفاوت شود.

وقتی نیاز به حفظ تگ‌های HTML دارید (راهکار پیشرفته)

اگر می‌خواهید هنگام کوتاه‌سازی برخی تگ‌های HTML (مثل <a>، <strong>، <em>) حفظ شوند، باید از روش‌های پیچیده‌تری استفاده کنید چون wp_trim_words تگ‌ها را حذف می‌کند. در ادامه یک تابع مبتنی بر DOMDocument ارائه می‌شود که تا حد امکان ساختار HTML را حفظ کرده و بر اساس تعداد کلمه برش می‌دهد:

<?php
function wp_trim_words_preserve_html( $html, $num_words = 55, $more = '...' ) {
    libxml_use_internal_errors(true);
    $doc = new DOMDocument();
    $doc->loadHTML(mb_convert_encoding($html, 'HTML-ENTITIES', 'UTF-8'));
    libxml_clear_errors();

    $body = $doc->getElementsByTagName('body')->item(0);
    $word_count = 0;
    $truncated = '';

    $walker = function($node) use (&$walker, &$word_count, $num_words, &$truncated) {
        foreach ($node->childNodes as $child) {
            if ($word_count >= $num_words) break;
            if ($child->nodeType === XML_TEXT_NODE) {
                $text = trim($child->wholeText);
                if ($text === '') continue;
                $words = preg_split('/s+/u', $text, -1, PREG_SPLIT_NO_EMPTY);
                if ($word_count + count($words) <= $num_words) {
                    $truncated .= htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
                    $word_count += count($words);
                } else {
                    $remaining = $num_words - $word_count;
                    $truncated .= htmlspecialchars(implode(' ', array_slice($words, 0, $remaining)), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
                    $word_count = $num_words;
                    break;
                }
            } elseif ($child->nodeType === XML_ELEMENT_NODE) {
                $tag = $child->nodeName;
                $truncated .= '<' . $tag;
                if ($child->hasAttributes()) {
                    foreach ($child->attributes as $attr) {
                        $truncated .= ' ' . $attr->name . '="' . htmlspecialchars($attr->value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') . '"';
                    }
                }
                $truncated .= '>';
                $walker($child);
                $truncated .= '</' . $tag . '>';
            }
        }
    };

    $walker($body);
    if ($word_count >= $num_words) $truncated .= $more;
    return $truncated;
}
?>

این تابع با استفاده از DOMDocument ساختار HTML را پیمایش می‌کند، متن‌ها را بر اساس تعداد کلمه می‌شمارد و تگ‌های باز را بازنویسی می‌کند تا ساختار نهایی معتبر بماند. توجه کنید که این پیاده‌سازی پایه است و در صورت وجود تگ‌های پیچیده یا اسکریپت‌ها ممکن است نیاز به بهبود داشته باشد. ابزار DOMDocument امن‌تر و قابل اعتمادتر از دستکاری رشته‌ای ساده برای حفظ ساختار HTML است.

بهینه‌سازی و مسائل عملکردی

• wp_trim_words بسیار سبک و سریع است چون روی رشته ساده کار می‌کند؛ اما اگر از راهکار DOM برای HTML استفاده کنید، هزینه پردازشی افزایش می‌یابد—بنابراین آن را برای صفحات با ترافیک بالا با کش مناسب استفاده کنید.
• در صورتی که محتوای ورودی بسیار بزرگ است، بهتر است نتیجه را کش کنید (Transients یا object cache) تا بار سرور کاهش پیدا کند.
• همیشه خروجی را با wp_kses یا توابع مشابه در صورت قرار گرفتن در مکان‌های حساس فیلتر کنید تا از تزریق HTML مخرب جلوگیری شود.

خلاصه و توصیه‌ها

• برای خلاصه‌های ساده و سریع از wp_trim_words() استفاده کنید.
• اگر نیاز به حفظ تگ‌های HTML دارید، از روش‌های مبتنی بر DOM یا کتابخانه‌های معتبر استفاده کنید و نتیجه را کش کنید.
• برای تغییر رفتار عمومی خلاصه‌ها در وردپرس از فیلترهای مرتبط مثل excerpt_length و excerpt_more استفاده کنید.

با درک دقیق پارامترها و محدودیت‌های wp_trim_words می‌توانید نمایش بهتری از خلاصه مطالب در قالب و افزونه‌های وردپرس خود بسازید. در صورت نیاز می‌توان مثال‌های بیشتری از استفاده در قالب‌های مختلف و بهینه‌سازی برای زبان فارسی ارائه داد.

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

ارسال