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

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

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

الجمهور

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

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

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

"مرحبًا، العالم" في واجهة برمجة تطبيقات المشاهد المضمّنة

أسهل طريقة لبدء التعرف على واجهة برمجة تطبيقات المشاهد المضمنة هي الاطلاع على مثال بسيط. تعرض صفحة الويب التالية معاينة بحجم 600×500 لـ ماونتن فيو، بقلم نيكولاس بيري، رقم ISBN 0738531367 (جزء من سلسلة "Images of America" لشركة 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 لإنشاء كائن "viewer".
  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>

تحميل نسخة مترجمة من واجهة برمجة التطبيقات inline Viewer API

تستخدم واجهة برمجة التطبيقات Visual Viewer API اللغة الإنجليزية تلقائيًا عند عرض المعلومات النصية مثل التلميحات وأسماء عناصر التحكم ونص الرابط. إذا أردت تغيير واجهة برمجة التطبيقات inline Viewer API لعرض المعلومات بلغة معيّنة بشكل صحيح، يمكنك إضافة معلَمة 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 وnopt وplru وcs".

عند استخدام واجهة برمجة التطبيقات Visual Viewer API بلغات أخرى غير الإنجليزية، نوصي بشدة بعرض صفحتك مع ضبط عنوان 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'));

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

عند إنشاء مثيل مُشاهد جديد، عليك تحديد عقدة DOM في الصفحة (تكون عادةً عنصر div) كحاوية للمُشاهد. عُقد HTML هي عناصر ثانوية لكائن document JavaScript، ونحصل على مرجع إلى هذا العنصر من خلال الطريقة 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 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 إلا عندما يتم تحميل واجهة برمجة التطبيقات inline 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، يمكنك الاطّلاع على الدليل المرجعي.

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

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

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

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

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

ستواجه التطبيقات غير التافهة حتمًا تناقضات بين المتصفحات والأنظمة الأساسية. تُعد مواقع مثل 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 الكامل لكل مثال عن طريق النقر على الرابط بعد المثال.

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

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