Руководство разработчика

Embedded Viewer API позволяет встраивать содержимое книг из Google Книги непосредственно на веб-страницы с помощью JavaScript. API также предоставляет ряд утилит для управления предварительным просмотром книг и часто используется вместе с другими API, описанными на этом сайте.

Мастер предварительного просмотра — это инструмент, созданный на основе Embedded Viewer API, который упрощает добавление возможностей предварительного просмотра на ваш сайт, просто скопировав пару строк кода. Этот документ предназначен для более продвинутых разработчиков, желающих настроить отображение средства просмотра на своих сайтах.

Аудитория

Эта документация предназначена для людей, знакомых с программированием на JavaScript и концепциями объектно-ориентированного программирования. Вы также должны быть знакомы с Google Книгами с точки зрения пользователя. В Интернете доступно множество учебных пособий по JavaScript .

Эта концептуальная документация не является полной и исчерпывающей; он предназначен для того, чтобы вы могли быстро приступить к изучению и разработке интересных приложений с помощью Embedded Viewer API. Продвинутых пользователей может заинтересовать Справочник по API Embedded Viewer , в котором содержится исчерпывающая информация о поддерживаемых методах и ответах.

Как указано выше, новички могут начать с Мастера предварительного просмотра , который автоматически генерирует код, необходимый для встраивания основных предварительных просмотров на ваш сайт.

«Hello, World» API Embedded Viewer

Самый простой способ начать изучение Embedded Viewer API — просмотреть простой пример. На следующей веб-странице показан предварительный просмотр фильма « Маунтин-Вью » Николаса Перри, ISBN 0738531367, размером 600x500 (часть серии «Образы Америки» издательства 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. Мы включаем загрузчик API с помощью тега script .
  2. Мы создаем элемент div с именем «viewerCanvas» для хранения средства просмотра.
  3. Мы пишем функцию JavaScript для создания объекта «просмотрщик».
  4. Мы загружаем книгу, используя ее уникальный идентификатор (в данном случае ISBN:0738531367 ).
  5. Мы используем google.books.setOnLoadCallback для вызова initialize , когда API полностью загружен.

Эти шаги объясняются ниже.

Загрузка API встроенного средства просмотра

Использование платформы API Loader для загрузки Embedded Viewer API относительно просто. Он включает в себя следующие два шага:

  1. Включите библиотеку загрузчика API:
    <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 для правильного отображения информации на определенном языке, вы можете добавить необязательный 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 и ви.

При использовании Embedded 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() известна как конструктор , и ее определение (сокращенное для ясности из справочника по API Embedded Viewer ) показано ниже:

Конструктор Описание
DefaultViewer( контейнер , опции? ) Создает новое средство просмотра внутри заданного HTML- container , который должен быть блочным элементом на странице (обычно DIV ). Дополнительные параметры передаются с помощью необязательного параметра opts .

Обратите внимание, что второй параметр в конструкторе является необязательным — он предназначен для расширенных реализаций, выходящих за рамки этого документа, — и он опущен в примере «Hello, World».

Инициализация просмотра с определенной книгой

  viewer.load('ISBN:0738531367');

После того, как мы создали средство просмотра с помощью конструктора DefaultViewer , его необходимо инициализировать с помощью конкретной книги. Эта инициализация выполняется с использованием метода load() средства просмотра. Для метода load() требуется значение identifier , которое сообщает API, какую книгу показывать. Этот метод должен быть отправлен до того, как над объектом просмотра будут выполнены какие-либо другие операции.

Если вы знаете несколько идентификаторов книги — ISBN для издания в мягкой обложке или альтернативные номера OCLC — вы можете передать массив строк идентификаторов в качестве первого параметра функции load() . Средство просмотра отобразит книгу, если есть встроенный предварительный просмотр, связанный с любым из идентификаторов в массиве.

Поддерживаемые идентификаторы книг

Как и функция динамических ссылок , Embedded Viewer API поддерживает ряд значений для идентификации конкретной книги. Это включает:

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 .

Эти идентификаторы часто используются с другими API в семействе API Google Книг. Например, вы можете использовать динамические ссылки для отображения кнопки предварительного просмотра, только если книга является встраиваемой, а затем, когда пользователь нажимает кнопку, создавать экземпляр средства просмотра, используя URL-адрес предварительного просмотра, возвращаемый вызовом динамических ссылок . Точно так же вы можете создать многофункциональное приложение для просмотра и предварительного просмотра с помощью Books API , которое возвращает несколько подходящих отраслевых идентификаторов в своих каналах Volumes. Посетите страницу примеров, чтобы ознакомиться с некоторыми расширенными реализациями.

Обработка неудачных инициализаций

В некоторых случаях вызов load может завершиться ошибкой. Обычно это происходит, когда API не может найти книгу, связанную с предоставленным идентификатором, когда предварительный просмотр книги недоступен, когда предварительный просмотр книги не может быть встроен или когда территориальные ограничения не позволяют конечному пользователю увидеть эту конкретную книгу. Вы можете захотеть получить предупреждение о таком сбое, чтобы ваш код мог изящно обработать это состояние. По этой причине функция 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 или Dynamic Links , оба из которых сообщают, будет ли книга доступна для встраивания с помощью средства просмотра.

Обработка успешных инициализаций

Также может быть полезно узнать, была ли книга успешно загружена и когда. По этой причине функция 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 объект 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 и необычный режим

Мы рекомендуем использовать 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">

Примечание к примерам Embedded Viewer API

Обратите внимание, что в большинстве примеров в этой документации показан только соответствующий код JavaScript, а не полный HTML-файл. Вы можете вставить код JavaScript в свой собственный скелетный HTML-файл или загрузить полный HTML-файл для каждого примера, щелкнув ссылку после примера.

Исправление проблем

Если ваш код не работает, вот несколько подходов, которые могут помочь вам решить ваши проблемы: