Przewodnik dla programistów

Wbudowany interfejs API pozwala na umieszczanie treści książek z Książek Google bezpośrednio na stronach internetowych za pomocą kodu JavaScript. Interfejs API oferuje też szereg narzędzi do manipulowania podglądami książek. Jest często używany razem z innymi interfejsami API opisanymi na tej stronie.

Kreator podglądu to narzędzie opracowane na bazie interfejsu Umieśćy interfejs API do przeglądania, które ułatwia dodawanie funkcji podglądu do witryny przez skopiowanie kilku wierszy kodu. Ten dokument jest przeznaczony dla bardziej zaawansowanych programistów, którzy chcą dostosować wygląd przeglądarki do swoich witryn.

Odbiorcy

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

Ta koncepcyjna dokumentacja nie jest kompletna i wyczerpująca. Ma na celu szybkie rozpoczęcie i poznawanie świetnych aplikacji za pomocą interfejsu embed Viewer API. Doświadczeni użytkownicy powinni się zapoznać z Dokumentem API osadzonym w przeglądarce, który zawiera szczegółowe informacje na temat obsługiwanych metod i odpowiedzi.

Tak jak wspomniano wcześniej, początkujący mogą użyć kreatora podglądu, który automatycznie generuje kod niezbędny do umieszczenia w witrynie podstawowych podglądów.

„Hello, World” interfejsu Umieszczanie go na innych stronach

Najprostszym sposobem, aby dowiedzieć się więcej o interfejsie Umieszczanie go na stronach internetowych, jest prosty przykład. Na tej stronie internetowej wyświetlany jest podgląd w rozmiarze 600 x 500 Mountain View, autora Nicholas Perry, ISBN 0738531367 (część serii „Obrazy Ameryki” w Arcadia):

<!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 sprawdzić ten przykład i pobrać go, aby go edytować i bawić się tym. Nawet w tym prostym przykładzie należy pamiętać o 5 takich kwestiach:

  1. Plik SDK interfejsu API wstawiamy za pomocą tagu script.
  2. Tworzymy element div o nazwie „viewerCanvas”, w którym umieszcza się widza.
  3. Zapisujemy funkcję JavaScript, by utworzyć obiekt „viewer”.
  4. Wczytujemy książkę z użyciem jej unikalnego identyfikatora (w tym przypadku: ISBN:0738531367).
  5. Jeśli w pełni użyjemy interfejsu API, użyjemy wywołania google.books.setOnLoadCallback do wywołania elementu initialize.

Etapy te opisano poniżej.

Wczytywanie interfejsu API wbudowanej przeglądarki

Korzystanie z platformy SDK Loader do wczytywania interfejsu embed Viewer API jest stosunkowo proste. Proces obejmuje 2 kroki:

  1. Uwzględnij bibliotekę interfejsu 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 przyjmuje opcjonalny parametr listy określający funkcję wywołania zwrotnego lub język, zgodnie z opisem poniżej. 
    <script type="text/javascript">
  google.books.load();
</script>

Wczytywanie zlokalizowanej wersji interfejsu Static Viewer API

Podczas wyświetlania informacji tekstowych, takich jak etykietki, nazwy elementów sterujących i linki, interfejs Mozilla Wyświetlający API domyślnie używa języka angielskiego. Jeśli chcesz zmienić interfejs API Osadzonej przeglądarki, aby umożliwić prawidłowe wyświetlanie informacji 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 brazylijskim portugalskim:

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

Zobacz przykład (book-language.html)

Obecnie obsługiwane są następujące kody języków: RFC 3066.

Jeśli korzystasz z interfejsu Browser Viewer API w językach innych niż angielski, zalecamy wyświetlanie strony z nagłówkiem content-type ustawionym na utf-8 lub równoważnym tagiem <meta>. Dzięki temu znaki we wszystkich przeglądarkach będą renderowane prawidłowo. Więcej informacji znajdziesz na stronie organizacji W3C o ustawianiu parametru zestawu znaków HTTP.

Elementy DOM widza

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

Aby książka mogła być wyświetlana na stronie internetowej, należy zarezerwować jej miejsce. Zasadniczo odbywa się to przez utworzenie nazwanego elementu div i uzyskanie odwołania do tego elementu w modelu dokumentu dokumentu w przeglądarce (DOM).

W powyższym przykładzie określono atrybut div o nazwie „viewerCanvas” i ustawia rozmiar za pomocą atrybutów stylu. Przeglądarka domyślnie używa rozmiaru kontenera.

Obiekt DefaultViewer

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

Klasa JavaScript, która tworzy i kontroluje pojedynczego użytkownika na stronie, to klasa DefaultViewer. Możesz utworzyć więcej niż jedną instancję tej klasy – każdy obiekt definiuje na stronie osobnego przeglądającego. Nowa instancja tej klasy jest tworzona za pomocą operatora JavaScript new.

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

Ten kod definiuje zmienną (o nazwie viewer) i przypisuje ją do nowego obiektu DefaultViewer. Funkcja DefaultViewer() jest znana jako konstruktor, a jej definicja (skondensowana z łatwością dzięki dokumentacji interfejsu API wbudowanej przeglądarki) jest przedstawiona poniżej:

Zespół Opis
defaultViewer(kontener, opt.?) Tworzy nowego użytkownika w danych HTML container, który powinien być elementem na poziomie bloku na stronie (zwykle jest to DIV). Opcje zaawansowane są przekazywane za pomocą opcjonalnego parametru opts.

Drugi parametr w konstruktorze jest opcjonalny (zamierzony do zaawansowanych implementacji wykraczających poza zakres tego dokumentu) i jest pomijany w przykładzie „Hello, World”.

Inicjowanie widza za pomocą konkretnej książki

  viewer.load('ISBN:0738531367');

Gdy utworzysz go za pomocą konstruktora DefaultViewer, musi on zostać zainicjowany konkretną książką. Do zainicjowania tego elementu użyto metody load() wyświetlającego. Metoda load() wymaga wartości identifier, która informuje interfejs API, jaka książka ma być wyświetlana. Ta metoda musi zostać wysłana przed wykonaniem innych operacji na obiekcie przeglądarki.

Jeśli znasz wiele identyfikatorów książki – numer ISBN wydania w miękkiej oprawie lub alternatywne numery OCLC – możesz przekazać tablicę identyfikatorów jako pierwszy parametr funkcji load(). Przeglądarka wyrenderuje książkę, jeśli w tablicy jest umieszczony podgląd identyfikatorów.

Obsługiwane identyfikatory książek

Podobnie jak w przypadku funkcji Linki dynamiczne, interfejs API wbudowanej przeglądarki obsługuje kilka wartości do identyfikowania określonej książki. Mogą to być na przykład:

ISBN
Niepowtarzalny 10- lub 13-cyfrowy międzynarodowy standardowy numer książki.
Przykład: ISBN:0738531367
Numer OCLC
Niepowtarzalny numer przypisany do książki przez protokół OCLC po dodaniu rekordu książki do systemu katalogu WorldCat.
Przykład: OCLC:70850767
LCCN,
Numer kontrolny Biblioteki Kongresu przypisany do zapisu przez Bibliotekę Kongresu.
Przykład: LCCN:2006921508
Identyfikator woluminu Książek Google
Unikalny ciąg znaków przypisany przez Książki Google do woluminu, który pojawia się w adresie URL książki w Książkach Google.
Przykład: Py8u3Obs4f4C
URL podglądu w Książkach Google
URL otwierający 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 należącymi do rodziny Książek Google. Na przykład możesz użyć linków dynamicznych, by wyrenderować przycisk podglądu tylko wtedy, gdy można umieścić książkę. Gdy użytkownik kliknie ten przycisk, wywołasz widza, używając adresu URL podglądu zwróconego za pomocą linków dynamicznych. Podobnie aplikację do przeglądania i wyświetlania podglądu możesz też tworzyć za pomocą interfejsu Books API, który w plikach danych woluminów zwraca kilka odpowiednich identyfikatorów branżowych. Szczegółowe przykłady implementacji znajdziesz na stronie przykładów.

Inicjacje nieudane

W niektórych przypadkach wywołanie load może się nie udać. Zwykle ma to miejsce, gdy interfejs API nie może znaleźć książki powiązanej z podanym identyfikatorem, gdy podgląd książki jest niedostępny, gdy nie można umieścić podglądu książki lub gdy ograniczenia terytorialne uniemożliwiają użytkownikowi wyświetlenie danej książki. Możesz otrzymać alert o takim błędzie, żeby Twój kod działał bez problemu. Z tego powodu funkcja load umożliwia przekazanie opcjonalnego drugiego parametru, notFoundCallback, który wskazuje, która funkcja powinna zostać wywołana, jeśli nie udało się wczytać książki. Na przykład ten kod generuje pole alertu JavaScript, jeśli książka może zostać umieszczona:

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

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

Zobacz przykład (book-notfound.html)

Korzystając z tego wywołania zwrotnego, możesz wyświetlić podobny błąd lub całkowicie ukryć element viewerCanvas. Parametr wywołania zwrotnego błędu jest opcjonalny i nie należy go do przykładu „Hello World”.

Uwaga: podgląd może nie być dostępny dla wszystkich książek i dla wszystkich użytkowników, więc warto sprawdzić, czy podgląd jest dostępny przed, zanim spróbujesz wczytać go. Możesz na przykład wyświetlać w interfejsie przycisk, stronę lub sekcję „Podgląd Google”, tylko wtedy, gdy podgląd będzie faktycznie dostępny dla użytkownika. Możesz to zrobić za pomocą interfejsu Books API lub linków dynamicznych. Oba te przypadki określają, czy książkę można umieszczać w przeglądarce.

Obsługa inicjalizacji

Warto również sprawdzić, czy książka została wczytana i kiedy. 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);
}

Zobacz przykład (book-success.html)

Może to być przydatne, jeśli na przykład chcesz wyświetlać niektóre elementy na stronie tylko wtedy, gdy widz w pełni wyrenderuje jej zawartość.

Wyświetlanie widza po załadowaniu

  google.books.setOnLoadCallback(initialize);

Podczas renderowania strony zostaje utworzony model obiektu dokumentu (DOM), a wszystkie zewnętrzne obrazy i skrypty są odbierane i umieszczane w obiekcie document. Aby mieć pewność, że przeglądarka zostanie umieszczona na stronie tylko po pełnym wczytaniu strony, funkcja google.books.setOnLoadCallback opóźnia wykonanie funkcji konstruującej obiekt DefaultViewer. Ponieważ setOnLoadCallback wywoła metodę initialize tylko wtedy, gdy wbudowany interfejs API przeglądarki jest wczytany i gotowy do użycia, pozwala to uniknąć nieprzewidzianego zachowania i kontrolować sposób i sposób wyświetlania.

Uwaga: aby zmaksymalizować zgodność w różnych przeglądarkach, zdecydowanie zalecamy zaplanowanie wczytania przeglądarki przy użyciu funkcji google.books.setOnLoadCallback, zamiast używać zdarzenia onLoad w tagu <body>.

Interakcje widzów

Po utworzeniu obiektu DefaultViewer możesz z niego korzystać. Podstawowy obiekt przeglądarki wygląda i działa podobnie do przeglądarki, z której korzystasz w witrynie Książek Google, i ma wiele wbudowanych funkcji.

Możesz też automatycznie wchodzić w interakcję z widzem. Obiekt DefaultViewer obsługuje kilka metod bezpośrednio zmieniających stan podglądu. Na przykład metody zoomIn(), nextPage() i highlight() działają automatycznie w przeglądarce, a nie w wyniku interakcji użytkownika.

Poniższy przykład pokazuje podgląd książki, który automatycznie „przełącza” się na następną stronę co 3 sekundy. Jeśli kolejna strona jest widoczna w widocznej części przeglądarki, użytkownik płynnie porusza się po niej, a w przeciwnym razie przechodzi bezpośrednio na górę.

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

Zobacz przykład (book-animate.html)

Pamiętaj, że zautomatyzowane wywołania numeru zakończą się niepowodzeniem lub nie będą miały żadnego skutku, dopóki widz nie zainicjuje książki w całości. Aby wywoływać te funkcje tylko wtedy, gdy widz jest gotowy, użyj parametru successCallback, by viewer.load był opisany powyżej.

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

Notatki dotyczące programowania

Zanim zagłębisz się w interfejs API wbudowanej przeglądarki, zwróć uwagę na te kwestie, aby Twoja aplikacja działała bezproblemowo na zamierzonych platformach.

Zgodność z przeglądarką

Wbudowany interfejs API obsługuje najnowsze wersje przeglądarek Internet Explorer, Firefox i Safari oraz zwykle innych przeglądarek opartych na Gecko lub WebKit, takich jak Camino i Google Chrome.

Różne aplikacje mogą czasami zachowywać się inaczej w przypadku użytkowników z niezgodnymi przeglądarkami. Interfejs API umieszczonego interfejsu API nie zachowuje się automatycznie, gdy wykryje niezgodną przeglądarkę. Większość przykładów w tym dokumencie nie sprawdza zgodności z przeglądarkami ani nie wyświetla komunikatu o błędzie w przypadku starszych przeglądarek. Prawdziwe aplikacje mogą działać w sposób bardziej przyjazny dla starszych i niezgodnych przeglądarek, ale takie testy są pomijane, żeby przykłady były bardziej czytelne.

Nieproste aplikacje często niespójnie wyświetlają się w przeglądarkach i na platformach. Takie sposoby, jak np. quirksmode.org, też stanowią dobre sposoby na obejścia.

Tryb XHTML i osobliwości

Na stronach z przeglądarką zalecamy stosowanie zgodnych ze standardami XHTML. Gdy przeglądarka widzi kod {8/}DOCTYPE u góry strony, renderuje ją w „standardzie zgodności ze standardami”, dzięki czemu jej układ i zachowanie 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ójności 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 dotycząca przykładów użycia interfejsu embed Viewer API

Pamiętaj, że większość przykładów w tej dokumentacji zawiera tylko odpowiedni kod JavaScript, a nie pełny plik HTML. Możesz wstawić kod JavaScript do własnego pliku HTML szkieletu lub pobrać pełny plik HTML dla każdego przykładu, klikając link za przykładem.

Rozwiązywanie problemów

Jeśli Twój kod nie działa, oto kilka sposobów, które pomogą Ci rozwiązać problemy: