Cheerio لجافا سكريبت (Node.js): دليل شامل مع أمثلة

ما هو Cheerio وما هي استخداماته؟

Cheerio هي مكتبة سريعة ومرنة وخفيفة الوزن لتحليل (Parsing) HTML و XML على جانب الخادم في Node.js. توفر للمطورين بناء جملة قويًا يشبه jQuery للتنقل والبحث والتلاعب بشجرة DOM. إذا كنت قد عملت مع jQuery في المتصفح من قبل، فستجد Cheerio بديهيًا — Cheerio يطبق مجموعة فرعية من jQuery مُكيَّفة للاستخدام على الخادم.

الاستخدامات الرئيسية لـ Cheerio:

• استخراج البيانات من الويب (Web Scraping): سحب البيانات من صفحات الويب (الأسعار، عناوين الأخبار، محتوى المقالات).
• الاختبار (Testing): التحقق من بنية قوالب HTML في اختبارات الوحدة دون الحاجة إلى متصفح حقيقي.
• معالجة HTML المسبقة: تنظيف وتحويل واستخراج أجزاء من مستندات HTML قبل إرسالها إلى العميل.
• تحليل خلاصات RSS/XML: معالجة مستندات XML، على الرغم من وجود أدوات أكثر تخصصًا لـ XML.

على عكس محرك المتصفح الكامل (مثل Puppeteer أو Playwright)، لا يقوم Cheerio بعرض JavaScript، ولا يقوم بتحميل CSS أو الصور أو الموارد الخارجية. وهذا يجعله سريعًا للغاية وموفرًا للذاكرة. يعمل Cheerio مع سلسلة HTML الجاهزة التي تحصل عليها، على سبيل المثال، عبر طلب HTTP (باستخدام axios أو node-fetch أو الوحدة المدمجة http/https).

تثبيت Cheerio

يتم تثبيت Cheerio في مشروع Node.js عبر مدير الحزم npm (أو yarn). افتح الطرفية في جذر مشروعك ونفّذ الأمر التالي:

npm install cheerio

إذا كنت تستخدم yarn:

yarn add cheerio

بعد التثبيت، يمكنك استيراد المكتبة في الكود الخاص بك:

const cheerio = require('cheerio');
// أو لوحدات ES:
// import * as cheerio from 'cheerio';

ملاحظة: Cheerio هي مكتبة لـ Node.js، وهي غير مخصصة للعمل في المتصفح. إذا كنت بحاجة إلى تحليل HTML على جانب العميل، فمن الأفضل استخدام DOMParser الأصلي.

بداية سريعة: المثال الأول

لنكتب سكريبتًا بسيطًا يقوم بتحميل سلسلة HTML، ويجد جميع الروابط فيها، ثم يعرض نصوصها وخصائص href.

const cheerio = require('cheerio');

// مثال على كود HTML (عادةً تحصل عليه عبر طلب HTTP)
const html = `
<html>
<head><title>صفحة مثال</title></head>
<body>
    <h1>مرحبًا بك!</h1>
    <ul>
        <li><a href="https://example.com">الرابط 1</a></li>
        <li><a href="https://google.com">الرابط 2</a></li>
        <li class="special"><a href="https://github.com">الرابط 3</a></li>
    </ul>
</body>
</html>
`;

// تحميل HTML في Cheerio
const $ = cheerio.load(html);

// البحث عن جميع وسوم <a> والتكرار عليها
$('a').each((index, element) => {
    const text = $(element).text();       // النص داخل الوسم
    const href = $(element).attr('href'); // قيمة الخاصية href
    console.log(`${index + 1}. ${text} - ${href}`);
});

// النتيجة:
// 1. الرابط 1 - https://example.com
// 2. الرابط 2 - https://google.com
// 3. الرابط 3 - https://github.com

كما ترى، بناء الجملة مشابه جدًا لـ jQuery: نستخدم الدالة $() لتحديد العناصر، ثم نطبق الطرق .text() و .attr() و .each() للتعامل معها.

الطرق والوظائف الأساسية في Cheerio

فيما يلي شرح مفصل لـ 10 طرق رئيسية في Cheerio مع الوصف والمعاملات والأمثلة.

1. cheerio.load(html, options?)

الوظيفة: تحميل سلسلة HTML وإرجاع الدالة الرئيسية $ التي تتفاعل من خلالها مع DOM. هذه هي نقطة الدخول إلى المكتبة.

المعاملات: html (سلسلة نصية) — كود HTML المراد تحليله. options (كائن اختياري) — إعدادات مثل decodeEntities (فك تشفير الكيانات) و xmlMode (وضع XML).

مثال:

const $ = cheerio.load('<h1>Hello World</h1>', { decodeEntities: false });

2. $(selector, context?)

الوظيفة: تحديد العناصر في DOM بناءً على محدد CSS. تُرجع كائن Cheerio (يشبه مصفوفة) يمكنك التلاعب به.

المعاملات: selector (سلسلة نصية) — محدد CSS (مثل 'div'، '.class'، '#id'). context (اختياري) — عنصر أو كائن Cheerio للبحث بداخله.

مثال:

const $links = $('a.external'); // تحديد جميع الروابط ذات الفئة 'external'

3. .text(content?)

الوظيفة: الحصول على النص المدمج لعنصر (وجميع العناصر الفرعية) أو تعيين نص جديد للعنصر.

المعاملات: content (سلسلة نصية اختيارية) — إذا تم تمريرها، يتم تعيين النص للعنصر.

مثال:

const title = $('h1').text(); // الحصول على النص
$('h1').text('عنوان جديد'); // تعيين نص جديد

4. .attr(name, value?)

الوظيفة: الحصول على قيمة خاصية معينة للعنصر الأول في المجموعة، أو تعيين قيمة خاصية لجميع العناصر.

المعاملات: name (سلسلة نصية) — اسم الخاصية. value (سلسلة نصية اختيارية) — القيمة المراد تعيينها.

مثال:

const src = $('img').attr('src'); // الحصول على قيمة src
$('img').attr('alt', 'وصف الصورة'); // تعيين الخاصية alt

5. .each(function(index, element))

الوظيفة: التكرار على كل عنصر في مجموعة Cheerio وتنفيذ دالة لكل عنصر.

المعاملات: function(index, element) — دالة رد نداء (callback) تأخذ فهرس العنصر والعنصر نفسه (DOM الأصلي).

مثال:

$('li').each((i, el) => {
    console.log(i + ': ' + $(el).text());
});

6. .find(selector)

الوظيفة: البحث عن العناصر التابعة (الأطفال) التي تطابق المحدد، بدءًا من العنصر الحالي.

المعاملات: selector (سلسلة نصية) — محدد CSS.

مثال:

const $paragraphs = $('div.content').find('p'); // البحث عن جميع الفقرات داخل div.content

7. .children(selector?)

الوظيفة: الحصول على العناصر التابعة المباشرة للعنصر الحالي. يمكن تمرير محدد لتصفية النتائج.

المعاملات: selector (سلسلة نصية اختيارية) — محدد CSS لتصفية العناصر التابعة.

مثال:

const $firstLevel = $('ul').children('li'); // الحصول على عناصر li المباشرة داخل ul

8. .parent()

الوظيفة: الحصول على العنصر الأب المباشر للعنصر الحالي.

المعاملات: لا يوجد.

مثال:

const $parentDiv = $('span').parent(); // الحصول على الأب المباشر للعنصر span

9. .html(content?)

الوظيفة: الحصول على محتوى HTML الداخلي للعنصر الأول (بما في ذلك الوسوم الفرعية) أو تعيين HTML جديد للعنصر.

المعاملات: content (سلسلة نصية اختيارية) — كود HTML جديد لتعيينه.

مثال:

const innerHtml = $('div').html(); // الحصول على HTML الداخلي
$('div').html('<p>محتوى جديد</p>'); // تعيين HTML جديد

10. .remove()

الوظيفة: إزالة العناصر المحددة من DOM.

المعاملات: لا يوجد.

مثال:

$('script').remove(); // إزالة جميع وسوم script من المستند

خاتمة

Cheerio هي أداة لا غنى عنها لأي مطور Node.js يعمل مع HTML أو XML. بفضل سرعتها وبساطتها وتوافقها مع jQuery، يمكنك بسهولة استخراج البيانات ومعالجتها دون عناء. جرب الأمثلة أعلاه وابدأ في بناء مشاريع web scraping الخاصة بك اليوم!