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

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

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

Аудитория

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

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

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

«Привет, мир» API встроенного средства просмотра

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

Эти шаги описаны ниже.

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

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

  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>

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

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, и VI.

При использовании API Embedded Viewer на языках, отличных от английского, мы настоятельно рекомендуем обслуживать вашу страницу с заголовком 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() . Средство просмотра отобразит книгу, если существует встраиваемый предварительный просмотр, связанный с любым из идентификаторов в массиве.

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

Как и функция динамических ссылок , 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 . Поскольку setOnLoadCallback будет вызывать initialize только тогда, когда 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 , смотрите в Справочном руководстве .

Замечания по программированию

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

Совместимость с браузером

API Embedded Viewer поддерживает последние версии Internet Explorer, Firefox и Safari, а также, как правило, другие браузеры на основе Gecko и WebKit, такие как Camino и Google Chrome .

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

Нетривиальные приложения неизбежно столкнутся с несогласованностью браузеров и платформ. Такие сайты, как 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">

Примечание к примерам API встроенного средства просмотра

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

Поиск неисправностей

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