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

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

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

الجمهور

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

هذه المستندات المفاهيمية ليست كاملة وشاملة، بل تم تصميمها للسماح لك ببدء استكشاف تطبيقات رائعة وتطويرها بسرعة باستخدام Embedded Viewer API. قد يهمّ المستخدمين المتقدّمين مرجع Embedded Viewer API الذي يقدّم تفاصيل شاملة عن الطُرق والردود المتوافقة.

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

العبارة "مرحبًا، يا عالم" لواجهة برمجة التطبيقات Embedded Viewer API

إنّ أسهل طريقة لبدء التعرّف على Embedded Viewer API هي الاطّلاع على مثال بسيط. تعرض صفحة الويب التالية معاينة بدقة 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. نكتب دالة JavaScript لإنشاء عنصر "عارض".
  4. يتم تحميل الكتاب باستخدام معرّفه الفريد (ISBN:0738531367 في هذه الحالة).
  5. نستخدم google.books.setOnLoadCallback للاتصال بـ initialize عند تحميل واجهة برمجة التطبيقات بالكامل.

نوضح في ما يلي هاتين الخطوتين.

تحميل واجهة برمجة تطبيقات Extended Viewer API

إنّ استخدام إطار عمل "أداة تحميل واجهة برمجة التطبيقات" لتحميل واجهة برمجة التطبيقات Visual Viewer API هو أمر بسيط نسبيًا. ويتضمّن ذلك الخطوتَين التاليتَين:

  1. أدرِج مكتبة API Loader: 
    <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>

تحميل نسخة مترجَمة من Embedded Viewer API

تستخدم Embedded Viewer API اللغة الإنجليزية تلقائيًا عند عرض المعلومات النصية، مثل معلومات التلميح وأسماء عناصر التحكّم ونص الروابط. إذا أردت تغيير واجهة برمجة التطبيقات Embedded Viewer API لعرض المعلومات بشكل صحيح بلغة معيّنة، يمكنك إضافة مَعلمة optional 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 وhe وhu وis وid وit وja وko وlv وlt وms وno وpl وpt-BR وpt-PT وro وru وsr وsk وsl وes وsv وtl وth وtr وuk وvi.

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

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

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

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

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

كائن defaultViewer

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

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

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

تحدِّد هذه التعليمة البرمجية متغيّرًا (يحمل الاسم viewer) وتخصّص هذا المتغيّر لعنصر DefaultViewer جديد. تُعرف الدالة DefaultViewer() باسم constructor وتعريفها (المكثّف من أجل الوضوح من مرجع Embedded Viewer API) موضح أدناه:

الشركة المصنِّعة الوصف
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 Books API. على سبيل المثال، يمكنك استخدام الروابط الديناميكية لعرض زر معاينة فقط إذا كان الكتاب قابلاً للتضمين، وبعد ذلك، عندما ينقر المستخدم على الزر، يمكنك إنشاء مثيل لمشاهد باستخدام عنوان URL للمعاينة الذي يعرضه طلب الروابط الديناميكية. وبالمثل، يمكنك إنشاء تطبيق غني بالميزات يتيح التصفّح والمعاينة باستخدام واجهة برمجة التطبيقات Books API، التي تعرض العديد من المعرّفات المناسبة للصناعة في خلاصات "الكتب". انتقِل إلى صفحة الأمثلة للاطّلاع على بعض عمليات التنفيذ المتقدّمة.

معالجة عمليات الإعداد التي تعذّر إكمالها

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

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" أو صفحة أو قسم في واجهة المستخدم فقط إذا كانت المعاينة متاحة للمستخدم فعليًا. يمكنك إجراء ذلك باستخدام Books API أو الروابط الديناميكية، وكلاهما يُبلغان عمّا إذا كان الكتاب متاحًا للتضمين باستخدام المُشاهد.

معالجة عمليات الإعداد الناجحة

قد يكون من المفيد أيضًا معرفة ما إذا تم تحميل كتاب بنجاح ووقت تحميله. لهذا السبب، تتيح الدالة 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 إلا عند تحميل Embedded Viewer API واستعداده للاستخدام، سيؤدي ذلك إلى تجنُّب السلوك غير المتوقّع وضمان التحكّم في كيفية رسم المُشاهد ووقت رسمه.

ملاحظة: لزيادة التوافق مع جميع المتصفّحات إلى أقصى حد، ننصحك بشدة بجدولة تحميل المشاهد باستخدام الدالة 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، اطّلِع على الدليل المرجعي.

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

قبل البدء في التعمّق في Embedded Viewer API، عليك مراعاة المخاوف التالية لضمان عمل تطبيقك بسلاسة على الأنظمة الأساسية المعنيّة.

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

تتوافق Embedded Viewer API مع أحدث إصدارات Internet Explorer وFirefox وSafari، بالإضافة إلى المتصفّحات الأخرى المستندة إلى Gecko وWebKit، مثل Camino و Google Chrome.

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

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

XHTML ووضع Quirks

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

<!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">

ملاحظة حول أمثلة على واجهة برمجة التطبيقات Visual Viewer API

يُرجى العِلم أنّ معظم الأمثلة الواردة في هذه المستندات لا تعرض سوى رمز JavaScript ذي الصلة، وليس ملف HTML الكامل. يمكنك توصيل رمز JavaScript بملف HTML الأساسي الخاص بك، أو يمكنك تنزيل ملف HTML الكامل لكل مثال من خلال النقر على الرابط بعد المثال.

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

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