دليل مطوّر البرامج

تتيح لك واجهة برمجة تطبيقات العارض المضمّن تضمين محتوى الكتاب من كتب Google مباشرة في صفحات الويب باستخدام جافا سكريبت. كما توفر واجهة برمجة التطبيقات عددًا من الأدوات المساعدة للتلاعب بمعاينات الكتب، وغالبًا ما يتم استخدامها مع واجهات برمجة التطبيقات الأخرى الموضحة على هذا الموقع.

معالج المعاينة هو أداة تم تصميمها في أعلى واجهة برمجة التطبيقات للعارض المضمّن والتي تسهّل إضافة إمكانيات المعاينة إلى موقعك الإلكتروني من خلال نسخ سطرين من الرمز فقط. تم تصميم هذا المستند لمطوّري البرامج الأكثر تقدمًا الذين يريدون تخصيص كيفية ظهور المشاهد على مواقعهم.

الجمهور

تم تصميم هذا المستند للأشخاص المألوفين لبرمجة جافا سكريبت ومفاهيم البرمجة الموجهة للكائنات. كما يجب أن تكون على دراية بـكتب Google من وجهة نظر المستخدم. هناك العديد من البرامج التعليمية لجافا سكريبت المتاحة على الويب.

هذه المستندات النظرية ليست شاملة وشاملة، فهي مصمّمة للسماح لك ببدء استكشاف تطبيقات رائعة وتطويرها بسرعة باستخدام واجهة برمجة التطبيقات "العارض المضمّن". يجب أن يهتم المستخدمون المتقدمون بمرجع واجهة برمجة التطبيقات للعارض المضمّن، الذي يوفر تفاصيل شاملة حول الطرق والاستجابات المدعومة.

كما هو موضح أعلاه، قد يحتاج المبتدئون إلى البدء باستخدام معالج المعاينة، الذي ينشئ الرمز اللازم تلقائيًا لتضمين المعاينات الأساسية على موقعك الإلكتروني.

"Hello, World" لواجهة برمجة تطبيقات العارض المضمّن

أسهل طريقة لبدء التعرف على واجهة برمجة تطبيقات العارض المضمن هي مشاهدة مثال بسيط. تعرض صفحة الويب التالية معاينة مقاس 600×500 لـ Mountain View، بقلم نيكولاس بيري، ISBN 0738531367 (جزء من سلسلة "صور أمريكا" لشركة Arcadia Publishing):

<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Books Embedded Viewer API Example</title>
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
    <script type="text/javascript">
      google.books.load();

      function initialize() {
        var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
        viewer.load('ISBN:0738531367');
      }

      google.books.setOnLoadCallback(initialize);
    </script>
  </head>
  <body>
    <div id="viewerCanvas" style="width: 600px; height: 500px"></div>
  </body>
</html>

يمكنك الاطلاع على هذا المثال وتنزيله لتعديله وتشغيله. حتى في هذا المثال البسيط، هناك خمسة أشياء يجب ملاحظتها:

  1. يتم تضمين أداة تحميل واجهة برمجة التطبيقات باستخدام علامة script.
  2. أنشأنا عنصر div باسم "viewerCanvas" لتثبيت العارض.
  3. نكتب دالة جافا سكريبت لإنشاء كائن "مُشاهد".
  4. نحمِّل الكتاب باستخدام معرِّفه الفريد (في هذه الحالة ISBN:0738531367).
  5. نستخدم google.books.setOnLoadCallback لاستدعاء initialize عند تحميل واجهة برمجة التطبيقات بالكامل.

ويتم شرح هذه الخطوات في ما يلي.

تحميل واجهة برمجة تطبيقات العارض المضمّن

إن استخدام إطار عمل واجهة برمجة التطبيقات لتحميل واجهة برمجة التطبيقات للعارض المضمّن أمر بسيط نسبيًا. ويتمثل في إجراء الخطوتين التاليتين:

  1. ضمِّن مكتبة أداة تحميل واجهة برمجة التطبيقات: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. استدعاء طريقة google.books.load. تعتمد طريقة google.books.load على معلمة قائمة اختيارية تحدّد وظيفة رد الاتصال أو اللغة، كما هو موضّح أدناه. 
    <script type="text/javascript">
  google.books.load();
</script>

تحميل إصدار مترجم من واجهة برمجة التطبيقات للعارض المضمّن

تستخدم واجهة برمجة تطبيقات العارض المضمّن اللغة الإنجليزية بشكل افتراضي عند عرض معلومات نصية مثل التلميحات وأسماء عناصر التحكم ونص الرابط. وإذا أردت تغيير واجهة برمجة التطبيقات للعارض المضمّن لعرض المعلومات بلغة معيّنة بشكل صحيح، يمكنك إضافة معلَمة language اختيارية إلى طلب google.books.load.

على سبيل المثال، لعرض وحدة معاينة الكتاب باللغة الواجهة البرازيلية البرتغالية:

<script type="text/javascript">
  google.books.load({"language": "pt-BR"});
</script>

عرض مثال (book-language.html)

تتضمن حاليًا رموز اللغات المتوافقة مع RFC 3066 af، وar، وhy، وbg، وca، وzh-CN، وzh-TW، وhr، وcs، وda، وnl، وen، وfil، وfi، وfr، وde، وel، وhu، وhu، وid، وit، وja، وko، وlv، وlt، وrt، وtr، وt، وt، وtr، وt، وt، وt، وt، وt، وt، وt، وt، وt، وtr، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، وt، t، وt، وt، وt، وt، وt، وt، وt، وtu،

عند استخدام واجهة برمجة تطبيقات العارض المضمَّن بلغات أخرى غير الإنجليزية، نوصي بشدة بعرض صفحتك مع ضبط رأس content-type على utf-8، أو تضمين علامة <meta> مكافئة في صفحتك. يساعد إجراء ذلك على ضمان عرض الأحرف بشكل صحيح في جميع المتصفحات. لمزيد من المعلومات، اطلع على صفحة W3C حول تعيين معلمة مجموعة أحرف HTTP.

عناصر DOM للمشاهد

<div id="viewerCanvas" style="width: 600px; height: 500px"></div>

لعرض كتاب على صفحة ويب، يجب حجز مكان له. ويتم إجراء ذلك عادةً من خلال إنشاء عنصر div مُسمى والحصول على مرجع لهذا العنصر في نموذج كائن المستند (DOM) للمتصفح.

يحدّد المثال أعلاه div باسم "viewerCanvas" ويضبط حجمه باستخدام سمات النمط. يستخدم المشاهد ضمنيًا حجم الحاوية لتغيير حجمها.

كائن DefaultViewer

var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));

إن فئة جافا سكريبت التي تنشئ عارضًا واحدًا على الصفحة وتتحكم فيها هي فئة DefaultViewer. (يمكنك إنشاء أكثر من مثيل واحد لهذه الفئة - سيحدد كل كائن مشاهد منفصلاً على الصفحة). ويتم إنشاء مثيل جديد من هذه الفئة باستخدام عامل تشغيل JavaScript new.

عند إنشاء مثيل عارض جديد، يمكنك تحديد عقدة DOM في الصفحة (عادةً ما يكون العنصر div) كحاوية للمشاهد. عُقد HTML هي عناصر ثانوية لكائن JavaScript document، ونحصل على مرجع لهذا العنصر عبر طريقة document.getElementById().

يحدّد هذا الرمز متغيّرًا (يُسمّى viewer) ويخصّص هذا المتغير لكائن DefaultViewer جديد. الدالة DefaultViewer() تُعرف باسم المنشئ وتعريفها (هو مكثف للوضوح من مرجع واجهة برمجة التطبيقات للعارض المضمن) وهو موضح أدناه:

الشركة المصنِّعة الوصف
DefaultViewer(container, opts?) تنشئ عارضًا جديدًا داخل HTML container المحدد، والذي يجب أن يكون عنصرًا على مستوى الحظر في الصفحة (عادةً ما يكون DIV). ويتم تمرير الخيارات المتقدمة باستخدام معلمة opts الاختيارية.

لاحظ أن المعلمة الثانية في دالة الإنشاء اختيارية - وهي مخصصة لعمليات التنفيذ المتقدمة التي تتجاوز نطاق هذا المستند - وقد تم حذفها من مثال "Hello, World".

تهيئة المشاهد بكتاب معين

  viewer.load('ISBN:0738531367');

بعد إنشاء عارض باستخدام المُنشئ DefaultViewer، يجب إعداده باستخدام كتاب معيّن. ويتم إكمال هذه التهيئة باستخدام طريقة المُشاهد load(). تتطلّب الطريقة load() قيمة identifier تحدّد واجهة برمجة التطبيقات الكتاب الذي يجب عرضه. يجب إرسال هذه الطريقة قبل تنفيذ أي عمليات أخرى على كائن المشاهد.

إذا كنت تعرف معرّفات متعددة لأحد الكتب، رقم ISBN لإصدار الغلاف الورقي، أو أرقام OCLC البديلة، يمكنك تمرير مجموعة من سلاسل المعرّفات كالمعلّمة الأولى إلى الدالة load(). سيعرض العارض الكتاب إذا كانت هناك معاينة قابلة للتضمين مرتبطة بأي من المعرِّفات في المصفوفة.

معرّفات الكتب المتوافقة

مثل ميزة الروابط الديناميكية، تدعم واجهة برمجة التطبيقات للعارض المضمّن عدد من القيم لتحديد كتاب معين. ومن بينها:

رقم ISBN
الرقم الدولي المعياري للكتاب المؤلف من 10 أو 13 رقمًا.
مثال: ISBN:0738531367
رقم OCLC
الرقم الفريد المعيّن لكتاب بواسطة OCLC عند إضافة سجل الكتاب إلى نظام كتالوج WorldCat.
مثال: OCLC:70850767
رقم LCCN (رقم الضبط في مكتبة الكونغرس)
رقم مكتبة التحكّم في الكونغرس المخصص للسجلّ من خلال مكتبة الكونغرس.
مثال: LCCN:2006921508
معرّف حجم كتب Google
السلسلة الفريدة التي خصصتها "كتب Google" للمجلد، الذي يظهر في عنوان URL للكتاب على "كتب Google".
مثال: Py8u3Obs4f4C
عنوان URL لمعاينة "كتب Google"
عنوان URL يفتح صفحة معاينة الكتاب على "كتب Google".
مثال: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

وغالبًا ما يتم استخدام هذه المعرّفات مع واجهات برمجة تطبيقات أخرى في عائلة كتب Google API. على سبيل المثال، يمكنك استخدام الروابط الديناميكية لعرض زر المعاينة فقط إذا كان الكتاب قابلاً للتضمين، وبعد ذلك عندما ينقر المستخدم على الزر، أنشئ مثيلاً للمشاهد باستخدام عنوان URL للمعاينة الذي تعرضه استدعاء الروابط الديناميكية. وبالمثل، يمكنك إنشاء تطبيق غني للتصفح والمعاينة باستخدام واجهة برمجة تطبيقات الكتب، والتي تعرض العديد من معرّفات الصناعة المناسبة في خلاصات مجلداتها. انتقل إلى صفحة الأمثلة لإلقاء نظرة سريعة على بعض عمليات التنفيذ المتقدمة.

التعامل مع عمليات التهيئة الفاشلة

في بعض الحالات، قد يتعذّر الاتصال بالرقم load. يحدث هذا عادةً عندما يتعذر على واجهة برمجة التطبيقات العثور على كتاب مرتبط بالمعرّف الذي تم توفيره، أو عندما لا تتوفر معاينة للكتاب، أو عندما يتعذر تضمين معاينة الكتاب، أو عندما تمنع القيود الإقليمية المستخدم من مشاهدة هذا الكتاب تحديدًا. قد تريد أن يتم تنبيهك بهذا الفشل، بحيث يمكن للشفرة معالجة هذا الشرط بشكلٍ أنيق. لهذا السبب، تتيح لك الدالة load تمرير معلّمة ثانية اختيارية، notFoundCallback، والتي تشير إلى الدالة التي يجب استدعاؤها إذا تعذّر تحميل الكتاب. على سبيل المثال، سينشئ الرمز التالي مربع "تنبيه" جافا سكريبت إذا كان من الممكن تضمين الكتاب:

function alertNotFound() {
  alert("could not embed the book!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:1234', alertNotFound);
}

عرض مثال (book-notfound.html)

باستخدام رد الاتصال هذا، قد تقرر عرض خطأ مشابه، أو يمكنك اختيار إخفاء العنصر viewerCanvas تمامًا. معلمة الاستدعاء للإخفاق اختيارية، ولا يتم تضمينها في مثال "Hello World".

ملاحظة: قد لا تكون المعاينات متاحة لجميع الكتب ولجميع المستخدمين، لذا قد يكون من المفيد معرفة ما إذا كانت المعاينة متوفّرة قبل محاولة تحميل مشاهد لها. على سبيل المثال، قد ترغب في عرض زر أو صفحة أو قسم من خلال "معاينة Google" في واجهة المستخدم فقط في حالة توفر معاينة للمستخدم فعليًا. ويمكنك إجراء ذلك باستخدام واجهة برمجة تطبيقات الكتب أو الروابط الديناميكية، وكلاهما يوضح ما إذا كان سيتم توفير أحد الكتب لتضمينه باستخدام العارض أم لا.

التعامل مع عمليات التهيئة الناجحة

وقد يكون من المفيد أيضًا معرفة ما إذا تم تحميل الكتاب بنجاح ووقت تحميله. لهذا السبب، تسمح الدالة load بمَعلمة ثالثة اختيارية، successCallback، والتي سيتم تنفيذها في حال الانتهاء من تحميل كتاب ووقت الانتهاء منه.

function alertInitialized() {
  alert("book successfully loaded and initialized!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:0738531367', null, alertInitialized);
}

عرض مثال (book-success.html)

قد تكون معاودة الاتصال هذه مفيدة إذا كنت، على سبيل المثال، تريد عرض عناصر معينة على صفحتك فقط إذا كان المشاهد قد عرضها بالكامل.

عرض العارض عند التحميل

  google.books.setOnLoadCallback(initialize);

أثناء عرض صفحة HTML، يتم تضمين نموذج كائن المستند (DOM)، ويتم تلقي أي صور ونصوص برمجية خارجية وتضمينها في الكائن document. لضمان عدم وضع العارض على الصفحة إلا بعد تحميل الصفحة بالكامل، يتم استخدام الدالة google.books.setOnLoadCallback لتأجيل تنفيذ الدالة التي تنشئ العنصر DefaultViewer. بما أن setOnLoadCallback لن تستدعي initialize إلا عندما يتم تحميل واجهة برمجة التطبيقات للعارض المضمّن والجاهزة للاستخدام، وهذا سيجنّب السلوك غير المتوقّع ويضمن التحكم في طريقة رسم العارض ووقته.

ملاحظة: لزيادة التوافق عبر المتصفحات إلى أقصى حد، ننصحك بشدة بجدولة تحميل العارض باستخدام الدالة google.books.setOnLoadCallback، بدلاً من استخدام حدث onLoad على العلامة <body>.

تفاعلات المشاهدين

الآن وبعد أن أصبح لديك كائن DefaultViewer، يمكنك التفاعل معه. يشبه كائن العارض الأساسي ويتصرف إلى حد كبير العارض الذي تتفاعل معه على موقع كتب Google على الويب ويأتي به الكثير من السلوك المضمن.

ولكن يمكنك أيضًا التفاعل مع المشاهد آليًا. يدعم الكائن DefaultViewer عددًا من الطرق التي تغيّر حالة المعاينة مباشرةً. على سبيل المثال، تعمل الطرق zoomIn() وnextPage() وhighlight() على العارض آليًا، وليس من خلال تفاعل المستخدم.

يعرض المثال التالي معاينة الكتاب التي "يتم تحويلها" تلقائيًا إلى الصفحة التالية كل 3 ثوانٍ. إذا كانت الصفحة التالية في الجزء المرئي من العارض، فسيتم تحريك العارض بسلاسة إلى الصفحة، وإذا لم يكن كذلك، فسينتقل العارض مباشرةً إلى أعلى الصفحة التالية.

function nextStep(viewer) {
  window.setTimeout(function() {
    viewer.nextPage();
    nextStep(viewer);
  }, 3000);
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:0738531367');
  nextStep(viewer);
}

google.books.setOnLoadCallback(initialize);

عرض مثال (book-animate.html)

لاحظ أن الاستدعاءات الآلية للمشاهد ستخفق أو لن يكون لها أي تأثير حتى يبدأ العارض بالكامل في كتاب معين. لضمان استدعاء هذه الدوال عندما يكون المُشاهد جاهزًا، استخدِم المَعلمة successCallback إلى viewer.load كما هو موضّح أعلاه.

للحصول على معلومات حول جميع الدوال المتاحة في الكائن DefaultViewer، يمكنك الاطّلاع على الدليل المرجعي.

ملاحظات البرمجة

قبل البدء في الانتقال إلى واجهة برمجة التطبيقات للعارض المضمّن، يجب الأخذ في الاعتبار المخاوف التالية لضمان عمل تطبيقك بسلاسة عبر الأنظمة الأساسية المقصودة.

توافق المتصفِّح

تتوافق واجهة برمجة تطبيقات العارض المضمّن مع الإصدارات الأحدث من Internet Explorer وفايرفوكس وSafari—وكثيرًا ما تدعم المتصفحات الأخرى التي تستند إلى Gecko وWebKit مثل Camino وGoogle Chrome أيضًا.

تتطلب التطبيقات المختلفة أحيانًا سلوكيات مختلفة للمستخدمين الذين يستخدمون متصفحات غير متوافقة. لا تحتوي واجهة برمجة تطبيقات العارض المضمّن على أي سلوك تلقائي عند اكتشاف متصفح غير متوافق. لا تتحقق معظم الأمثلة في هذا المستند من توافق المتصفح، كما أنها لا تعرض رسالة خطأ للمتصفحات الأقدم. قد تفعل التطبيقات الحقيقية شيئًا أكثر توافقًا مع المتصفحات القديمة أو غير المتوافقة، ولكن يتم تجاهل عمليات التحقق هذه لجعل الأمثلة أكثر قابلية للقراءة.

ستواجه التطبيقات غير البسيطة تناقضات بين المتصفحات والأنظمة الأساسية. وتُعد مواقع مثل quirksmode.org موارد جيدة للعثور على حلول بديلة.

وضع XHTML والمراوغة

نحن ننصح باستخدام لغة XHTML المتوافقة مع المعايير في الصفحات التي تحتوي على العارض. عندما ترى المتصفحات رمز XHTML DOCTYPE في أعلى الصفحة، فإنها تعرض الصفحة في "وضع التوافق مع المعايير"، ما يزيد إمكانية توقّع التنسيق والسلوكيات كثيرًا عبر المتصفحات. وقد يتم عرض الصفحات التي لا تحتوي على هذا التعريف في "وضع المراوغة"، ما قد يؤدي إلى تنسيق غير منتظم.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

ملاحظة حول أمثلة واجهة برمجة التطبيقات للعارض المضمّن

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

تحديد المشاكل وحلّها

إذا لم يعمل الرمز، فيما يلي بعض الأساليب التي قد تساعدك في حل المشاكل: