Przewodnik dla programistów

Interfejs Embedded Wyświetlający API umożliwia umieszczanie treści z Książek Google bezpośrednio na stronach internetowych za pomocą kodu JavaScript. Ten interfejs API udostępnia też wiele narzędzi do manipulowania podglądem książek i często jest używany razem z innymi interfejsami API opisanymi w tej witrynie.

Kreator podglądu to narzędzie oparte na interfejsie Embedded Wyświetlający API, które umożliwia dodanie funkcji podglądu do witryny przez skopiowanie kilku wierszy kodu. Ten dokument jest przeznaczony dla bardziej zaawansowanych programistów, którzy chcą dostosować sposób wyświetlania osoby przeglądającej w swoich witrynach.

Odbiorcy

Ta dokumentacja jest przeznaczona dla osób znających JavaScript i koncepcje programowania zorientowanego na obiekt. Zapoznaj się też z Książkami Google z perspektywy użytkownika. W internecie dostępnych jest wiele samouczków na temat JavaScriptu.

Ta dokumentacja koncepcyjna nie jest kompletna ani wyczerpująca. Została zaprojektowana, by umożliwić Ci szybkie rozpoczęcie odkrywania i tworzenia ciekawych aplikacji za pomocą interfejsu Embedded Wyświetlający API. Doświadczeni użytkownicy mogą zainteresować się dokumentacją interfejsu Embedded Wyświetlający API, która zawiera szczegółowe informacje o obsługiwanych metodach i odpowiedziach.

Jak wspomnieliśmy powyżej, początkujący mogą zacząć od kreatora podglądu, który automatycznie generuje kod niezbędny do umieszczenia w witrynie podstawowych podglądów.

„Hello, World” interfejsu Embedded Wyświetlający API

Najłatwiejszym sposobem, aby dowiedzieć się więcej o interfejsie Embedded Wyświetlający API, jest zapoznanie się z prostym przykładem. Ta strona zawiera podgląd filmu Mountain View w formacie 600 x 500 autorstwa Nicholasa Perry'ego, numer ISBN 0738531367 (część serii „Images of America” firmy 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>

Możesz zobaczyć ten przykład, pobrać aplikację i ją edytować. Nawet w tym prostym przykładzie należy zwrócić uwagę na 5 rzeczy:

  1. Moduł Loader API zawiera tag script.
  2. Tworzymy element div o nazwie „viewerCanvas”, który zatrzymuje użytkownika.
  3. Piszemy funkcję JavaScriptu, aby utworzyć obiekt „viewer”.
  4. Wczytujemy książkę, używając jej unikalnego identyfikatora (w tym przypadku ISBN:0738531367).
  5. Wykorzystamy google.books.setOnLoadCallback do wywołania initialize po pełnym wczytaniu interfejsu API.

Poniżej omawiamy te etapy.

Wczytywanie interfejsu Embedded Wyświetlający API

Użycie platformy API Loader do wczytywania interfejsu Embedded Wyświetlający API jest stosunkowo proste. Ten proces składa się z 2 etapów:

  1. Dołącz bibliotekę Loader API: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Wywołaj metodę google.books.load. Metoda google.books.load wykorzystuje opcjonalny parametr listy, który określa funkcję lub język wywołania zwrotnego, jak wyjaśniono poniżej. 
    <script type="text/javascript">
  google.books.load();
</script>

Wczytywanie zlokalizowanej wersji interfejsu Embedded Wyświetlający API

Podczas wyświetlania informacji tekstowych, takich jak etykietki, nazwy elementów sterujących i tekst linków, interfejs Embedded Wyświetlający API domyślnie używa języka angielskiego. Jeśli chcesz zmienić interfejs Embedded Wyświetlający API, aby prawidłowo wyświetlał informacje w określonym języku, możesz dodać do wywołania google.books.load opcjonalny parametr language.

Aby na przykład wyświetlić moduł podglądu książki w języku interfejsu brazylijski portugalski:

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

Wyświetl przykład (book-language.html)

Obsługiwane obecnie kody języków RFC 3066 to af, ar, hy, bg, ca, zh-CN, zh-TW, hr, cs, da, nl, en, fil, fi, fr, de, el, he, hu, is, id, id, ja, ko, lv, lt, ms, pl, PT, PT, PT

Jeśli używasz interfejsu Embedded Preview API w językach innych niż angielski, zdecydowanie zalecamy wyświetlanie strony z nagłówkiem content-type ustawionym na utf-8 lub umieszczeniem na stronie odpowiedniego tagu <meta>. Zapewni to prawidłowe renderowanie znaków we wszystkich przeglądarkach. Więcej informacji na ten temat znajdziesz na stronie organizacji W3C poświęconej ustawianiu parametru zestawu znaków HTTP.

Elementy DOM przeglądającego

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

Aby książka była wyświetlana na stronie internetowej, należy zarezerwować dla niej miejsce. Zwykle polega to na utworzeniu elementu div o nazwie i uzyskaniu do niego odniesienia w obiektowym modelu dokumentu (DOM) przeglądarki.

W powyższym przykładzie zdefiniowano obiekt div o nazwie „viewerCanvas” i określa on jego rozmiar za pomocą atrybutów stylu. Wyświetlający domyślnie ustala rozmiar kontenera na podstawie jego rozmiaru.

Obiekt DefaultViewer

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

Klasa JavaScript, która tworzy pojedynczą przeglądarkę na stronie i steruje nią, to klasa DefaultViewer. (Możesz utworzyć więcej niż 1 instancję tej klasy – każdy obiekt będzie definiować osobną przeglądarkę na stronie). Nowa instancja tej klasy jest tworzona przy użyciu operatora JavaScript new.

Gdy tworzysz nową instancję przeglądarki, określasz węzeł DOM na stronie (zwykle element div) jako kontener dla przeglądającego. Węzły HTML są elementami podrzędnymi obiektu JavaScript document. Odniesienie do tego elementu uzyskujemy za pomocą metody document.getElementById().

Ten kod definiuje zmienną (o nazwie viewer) i przypisuje ją do nowego obiektu DefaultViewer. Funkcja DefaultViewer() jest nazywana konstruktorem, a jej definicja (skrócona w celu uniknięcia wątpliwości w dokumentacji interfejsu Embedded Wyświetlający API) została przedstawiona poniżej:

Zespół Opis
DefaultViewer(container, opts?) Tworzy nową przeglądarkę w obrębie podanego container kodu HTML, który powinien być elementem na poziomie bloku na stronie (zwykle DIV). Opcje zaawansowane są przekazywane za pomocą opcjonalnego parametru opts.

Drugi parametr w konstruktorze jest opcjonalny – przeznaczony dla zaawansowanych implementacji wykraczających poza zakres tego dokumentu – i jest pomijany w przykładzie „Hello, World”.

Inicjowanie widza przez wyświetlanie konkretnej książki

  viewer.load('ISBN:0738531367');

Po utworzeniu przeglądarki za pomocą konstruktora DefaultViewer należy ją zainicjować konkretną książką. Inicjowanie odbywa się za pomocą metody load() użytkownika. Metoda load() wymaga wartości identifier, która informuje interfejs API, jaka książka ma się wyświetlić. Metodę trzeba wysłać przed wykonaniem jakichkolwiek innych operacji na obiekcie wyświetlającego.

Jeśli znasz wiele identyfikatorów książki – ISBN wydania w miękkiej oprawie lub alternatywne numery OCLC – jako pierwszy parametr możesz przekazać do funkcji load() tablicę ciągów identyfikatorów. Przeglądający renderuje książkę, jeśli istnieje możliwość umieszczenia podglądu powiązanego z którymkolwiek identyfikatorem w tablicy.

Obsługiwane identyfikatory książek

Podobnie jak w przypadku linków dynamicznych interfejs Embedded Wyświetlający API obsługuje wiele wartości do identyfikowania konkretnej książki. Są to między innymi:

ISBN
Unikalny 10- lub 13-cyfrowy numer komercyjny International Standard Book Number.
Przykład: ISBN:0738531367
Numer OCLC
Unikalny numer przypisany do książki przez OCLC, gdy rekord książki jest dodawany do systemu katalogowego WorldCat.
Przykład: OCLC:70850767
Numer LCCN
Numer kontroli biblioteki Kongresu przypisany do rekordu przez Bibliotekę Kongresu.
Przykład: LCCN:2006921508
Identyfikator tomu w Książkach Google
Unikalny ciąg znaków przypisany do Książek Google, który pojawia się w adresie URL książki w Książkach Google.
Przykład: Py8u3Obs4f4C
URL podglądu w Książkach Google
Adres URL, który otwiera stronę podglądu książki w Książkach Google.
Przykład: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Te identyfikatory są często używane z innymi interfejsami API z rodziny interfejsów API Książek Google. Na przykład Linków dynamicznych możesz używać, aby renderować przycisk podglądu tylko wtedy, gdy książkę można umieścić na stronie, a następnie, gdy użytkownik kliknie przycisk, utworzyć wystąpienie przeglądarki przy użyciu adresu URL podglądu zwróconego przez wywołanie Linków dynamicznych. W podobny sposób można utworzyć zaawansowaną aplikację do przeglądania i wyświetlania podglądu za pomocą interfejsu Books API, który zwraca kilka odpowiednich identyfikatorów branży w plikach danych woluminów. Zaawansowane implementacje znajdziesz na stronie przykładów.

Obsługa nieudanych inicjacji

W niektórych przypadkach wywołanie load może się nie powieść. Zwykle dzieje się tak, gdy interfejs API nie może znaleźć książki powiązanej z podanym identyfikatorem, nie jest dostępny podgląd książki, gdy nie można umieścić podglądu książki lub gdy ograniczenia regionalne uniemożliwiają użytkownikowi wyświetlenie danej książki. Jeśli chcesz otrzymać ostrzeżenie o takiej awarii, Twój kod będzie mógł właściwie obsłużyć ten problem. Dlatego funkcja load umożliwia przekazanie opcjonalnego drugiego parametru notFoundCallback, który wskazuje, jaka funkcja powinna zostać wywołana, jeśli nie uda się wczytać książki. Na przykład ten kod wygeneruje pole „alert” JavaScript, jeśli książkę będzie można umieścić:

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

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

Wyświetl przykład (book-notfound.html)

Korzystając z tego wywołania zwrotnego, możesz wyświetlać podobny błąd lub całkowicie ukryć element viewerCanvas. Parametr wywołania zwrotnego niepowodzenia jest opcjonalny i nie został uwzględniony w przykładzie „Hello World”.

Uwaga: podgląd może nie być dostępny dla wszystkich książek i dla wszystkich użytkowników, dlatego zanim spróbujesz załadować podgląd, warto sprawdzić, czy jest on dostępny. Na przykład możesz chcieć wyświetlać przycisk „Podgląd Google”, stronę lub sekcję w swoim interfejsie tylko wtedy, gdy podgląd będzie dla niego dostępny. Możesz to zrobić za pomocą interfejsu Books API lub Linków dynamicznych. Oba te raporty informują, czy książkę można umieszczać w przeglądarce.

Obsługa udanych inicjacji

Przydatne mogą być też informacje o tym, czy i kiedy książka została wczytana. Z tego powodu funkcja load obsługuje opcjonalny trzeci parametr, successCallback, który jest wykonywany po zakończeniu wczytywania książki.

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);
}

Wyświetl przykład (book-success.html)

To wywołanie zwrotne może być przydatne, jeśli np. chcesz, by określone elementy strony były pokazywane tylko wtedy, gdy użytkownik wyrenderował wszystkie elementy.

Wyświetlanie przeglądarki po wczytaniu

  google.books.setOnLoadCallback(initialize);

Podczas renderowania strony HTML tworzony jest obiektowy model dokumentu (DOM), a wszelkie zewnętrzne obrazy i skrypty są odbierane i uwzględniane w obiekcie document. Aby przeglądarka znalazła się na stronie dopiero po jej pełnym wczytaniu, funkcja google.books.setOnLoadCallback odracza wykonanie funkcji, która tworzy obiekt DefaultViewer. Ponieważ setOnLoadCallback wywołuje initialize tylko wtedy, gdy interfejs Embedded Viewer API jest załadowany i gotowy do użycia, unika to nieprzewidywalnych zachowań i zapewnia kontrolę nad sposobem i czasem wyświetlania przeglądarki.

Uwaga: aby zmaksymalizować zgodność z różnymi przeglądarkami, zdecydowanie zalecamy zaplanowanie wczytywania przeglądarki za pomocą funkcji google.books.setOnLoadCallback zamiast zdarzenia onLoad w tagu <body>.

Interakcje z widzami

Masz już obiekt DefaultViewer, więc możesz z nim korzystać. Podstawowy obiekt przeglądarki wygląda i działa bardzo podobnie do przeglądarki, z której korzystasz w Książkach Google, i ma wiele wbudowanych funkcji.

Możesz też wchodzić w interakcje z widzem w sposób zautomatyzowany. Obiekt DefaultViewer obsługuje wiele metod, które bezpośrednio zmieniają stan podglądu. Na przykład metody zoomIn(), nextPage() i highlight() działają w sposób zautomatyzowany, a nie w wyniku interakcji ze strony użytkownika.

Przykład poniżej przedstawia podgląd książki, który co 3 sekundy automatycznie „przewraca” na następną stronę. Jeśli następna strona znajduje się w widocznej części przeglądarki, użytkownik płynnie się w niej przesuwa, a w przeciwnym razie przeskakuje od razu na górę następnej.

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);

Wyświetl przykład (book-animate.html)

Pamiętaj, że automatyczne połączenia z użytkownikiem zakończą się niepowodzeniem lub nie będą miały żadnego efektu do momentu pełnego zainicjowania przez niego danej książki. Aby mieć pewność, że funkcje te będą wywoływane tylko wtedy, gdy przeglądarka jest gotowa, użyj parametru successCallback do funkcji viewer.load w opisany powyżej sposób.

Informacje o wszystkich funkcjach obsługiwanych przez obiekt DefaultViewer znajdziesz w Przewodniku.

Notatki dotyczące programowania

Zanim zaczniesz zagłębiać się w interfejs Embedded Wyświetlający API, weź pod uwagę poniższe kwestie, aby mieć pewność, że Twoja aplikacja będzie działać sprawnie na odpowiednich platformach.

Zgodność z przeglądarką

Interfejs Embedded Viewer API obsługuje najnowsze wersje przeglądarek Internet Explorer, Firefox i Safari, a także zwykle inne przeglądarki oparte na Gecko i WebKit, takie jak Camino i Google Chrome.

Różne aplikacje wymagają czasami innego działania w przypadku użytkowników korzystających z niekompatybilnych przeglądarek. Interfejs Embedded Wyświetlający API nie działa automatycznie po wykryciu niezgodnej przeglądarki. Większość przykładów w tym dokumencie nie sprawdza zgodności z przeglądarką i w przypadku starszych przeglądarek nie pojawia się komunikat o błędzie. Prawdziwe aplikacje mogą używać czegoś bardziej przyjaznego dla starszych lub niekompatybilnych przeglądarek, ale takie kontrole są pomijane, co zwiększa czytelność przykładów.

Proste aplikacje w nieunikniony sposób napotkają niespójności między przeglądarkami i platformami. Dobrymi zasobami są też takie witryny jak quirksmode.org.

Tryb XHTML i tryb osobliwości

Na stronach zawierających przeglądarkę zalecamy używanie zgodnego ze standardami języka XHTML. Gdy przeglądarki widzą kod XHTML DOCTYPE u góry strony, renderują stronę w „standardowym trybie zgodności”, co sprawia, że układ i działanie są znacznie bardziej przewidywalne w różnych przeglądarkach. Strony bez tej definicji mogą renderować się w „trybie osobliwości”, co może prowadzić do niespójnego układu.

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

Uwaga na temat przykładów interfejsu Embedded Wyświetlający API

Większość przykładów w tej dokumentacji pokazuje tylko odpowiedni kod JavaScript, a nie pełny plik HTML. Możesz umieścić kod JavaScript we własnym szkieletowym pliku HTML lub pobrać pełny plik HTML z każdego przykładu, klikając link za przykładem.

Rozwiązywanie problemów

Jeśli Twój kod wydaje się nie działać, oto kilka metod, które mogą pomóc Ci rozwiązać problemy: