Diese Seite wurde von der Cloud Translation API übersetzt.

Entwicklerhandbuch

Mit der Embedded Viewer API kannst du Buchinhalte aus Google Books mit JavaScript direkt in deine Webseiten einbetten. Die API bietet außerdem eine Reihe von Dienstprogrammen zur Bearbeitung von Buchvorschauen und wird häufig zusammen mit den anderen auf dieser Website beschriebenen APIs verwendet.

Der Preview Wizard basiert auf der Embedded Viewer API. Mit diesem Tool können Sie Ihrer Website ganz einfach Vorschaufunktionen hinzufügen, indem Sie ein paar Zeilen Code kopieren. Dieses Dokument richtet sich an fortgeschrittene Entwickler, die die Darstellung des Viewers auf ihren Websites anpassen möchten.

Zielgruppe

Diese Dokumentation richtet sich an Personen, die mit der JavaScript und objektorientierten Programmierungskonzepten vertraut sind. Außerdem sollten Sie mit Google Books aus Sicht des Nutzers vertraut sein. Im Web sind viele JavaScript-Anleitungen verfügbar.

Diese konzeptuelle Dokumentation ist nicht vollständig und vollständig. Sie soll Ihnen einen schnellen Einstieg in die Verwendung und Entwicklung cooler Anwendungen mit der Embedded Viewer API ermöglichen. Fortgeschrittene Nutzer können sich für die Referenz zur eingebetteten Viewer API interessieren, die umfassende Informationen zu unterstützten Methoden und Antworten enthält.

Wie oben gezeigt, sollten Anfänger mit dem Vorschauassistenten beginnen. Dieser generiert automatisch den Code, der zum Einbetten der grundlegenden Vorschauen auf Ihrer Website erforderlich ist.

„Hello, World“ der Embedded Viewer API

Anhand eines einfachen Beispiels erhalten Sie am leichtesten einen Einstieg in die Embedded Viewer API. Auf der folgenden Webseite wird eine 600 x 500 große Vorschau von Mountain View von Nicholas Perry mit der ISBN 0738531367 angezeigt (Teil der Reihe "Images of America" von 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>

Sehen Sie sich dieses Beispiel an und laden Sie es herunter, um es zu bearbeiten und auszuprobieren. Auch für dieses einfache Beispiel müssen folgende fünf Schritte ausgeführt werden:

Wir integrieren den API-Loader mithilfe eines script-Tags.
Wir erstellen ein div-Element namens „viewerCanvas“, das den Betrachter aufnimmt.
Wir schreiben eine JavaScript-Funktion, um ein „viewer“-Objekt zu erstellen.
Wir laden das Buch anhand seiner eindeutigen ID (in diesem Fall ISBN:0738531367).
Wir verwenden google.books.setOnLoadCallback, um initialize aufzurufen, wenn die API vollständig geladen ist.

Diese Schritte sind nachfolgend beschrieben.

Embedded Viewer API laden

Die Verwendung des API Loader-Frameworks zum Laden der Embedded Viewer API ist relativ einfach. Dazu sind die folgenden zwei Schritte erforderlich:

Fügen Sie die API Loader-Bibliothek ein:

<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>

Rufen Sie die Methode google.books.load auf. Die Methode google.books.load verwendet einen optionalen Listenparameter, der eine Callback-Funktion oder Sprache angibt, wie unten erläutert.
```
<script type="text/javascript">
  google.books.load();
</script>
```

Lokalisierte Version der Embedded Viewer API laden

Die Embedded Viewer API verwendet standardmäßig Englisch, um Textinformationen wie Kurzinfos, Namen von Steuerelementen und Linktext anzuzeigen. Wenn Sie die Embedded Viewer API so ändern möchten, dass Informationen in einer bestimmten Sprache korrekt angezeigt werden, können Sie dem google.books.load-Aufruf einen optionalen language-Parameter hinzufügen.

So zeigen Sie beispielsweise ein Buchvorschau-Modul mit der Benutzeroberflächensprache Portugiesisch (Brasilien) an:

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

Beispiel ansehen (book-language.html)

Zu den derzeit unterstützten Sprachcodes gemäß RFC 3066 gehören 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-pt, no,

Wenn du die Embedded Viewer API in anderen Sprachen als Englisch verwendest, empfehlen wir dringend, für die Bereitstellung deiner Seite einen content-type-Header zu verwenden, der auf utf-8 gesetzt ist, oder ein entsprechendes <meta>-Tag in die Seite einzufügen. Dadurch wird sichergestellt, dass Zeichen in allen Browsern korrekt gerendert werden. Weitere Informationen finden Sie auf der W3C-Seite zum Festlegen des HTTP-Zeichensatzparameters.

DOM-Elemente des Betrachters

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

Damit ein Buch auf einer Webseite angezeigt wird, muss ein Platz dafür reserviert werden. Dazu wird normalerweise ein benanntes div-Element erstellt, auf das im DOM (Document Object Model) des Browsers verwiesen wird.

Im Beispiel oben wird ein div namens „viewerCanvas“ definiert und seine Größe mithilfe von Stilattributen festgelegt. Der Viewer verwendet implizit die Größe des Containers, um seine Größe festzulegen.

StandardViewer-Objekt

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

Die JavaScript-Klasse, mit der ein einzelner Viewer auf der Seite erstellt und gesteuert wird, ist die Klasse DefaultViewer. Sie können mehrere Instanzen dieser Klasse erstellen. Jedes Objekt definiert einen separaten Viewer auf der Seite. Mit dem JavaScript-Operator new wird eine neue Instanz dieser Klasse erstellt.

Wenn Sie eine neue Viewer-Instanz erstellen, geben Sie auf der Seite einen DOM-Knoten (in der Regel ein div-Element) als Container für den Betrachter an. HTML-Knoten sind untergeordnete Elemente des JavaScript-document-Objekts. Ein Verweis auf dieses Element wird über die Methode document.getElementById() hergestellt.

Mit diesem Code wird eine Variable mit dem Namen viewer definiert und einem neuen DefaultViewer-Objekt zugewiesen. Die Funktion DefaultViewer() wird als Konstruktor bezeichnet. Die Definition der Funktion (zur Verdeutlichung zusammengefasst aus der Referenz zur Embedded Viewer API) ist unten zu sehen:

Konstruktor	Beschreibung
DefaultViewer(container, opts?)	Erstellt einen neuen Viewer innerhalb des angegebenen HTML-`container`-Elements, das ein Element auf Blockebene auf der Seite sein sollte (in der Regel `DIV`). Erweiterte Optionen werden mit dem optionalen `opts`-Parameter übergeben.

Beachten Sie, dass der zweite Parameter im Konstruktor optional ist und für erweiterte Implementierungen über den Rahmen dieses Dokuments hinaus vorgesehen ist. Er wird im "Hello, World"-Beispiel ausgelassen.

Betrachter mit einem bestimmten Buch initialisieren

  viewer.load('ISBN:0738531367');

Nachdem wir über den DefaultViewer-Konstruktor einen Viewer erstellt haben, muss er mit einem bestimmten Buch initialisiert werden. Diese Initialisierung erfolgt mithilfe der load()-Methode des Betrachters. Die Methode load() erfordert einen identifier-Wert, der der API mitteilt, welches Buch angezeigt werden soll. Diese Methode muss gesendet werden, bevor andere Vorgänge für das Viewer-Objekt ausgeführt werden.

Wenn Sie mehrere IDs für ein Buch kennen – die ISBN für die Taschenbuchausgabe oder alternative OCLC-Nummern –, können Sie ein Array von ID-Strings als ersten Parameter an die Funktion load() übergeben. Der Betrachter rendert das Buch, wenn eine einbettbare Vorschau mit einer der IDs im Array verknüpft ist.

Unterstützte Buch-IDs

Wie die Funktion Dynamic Links unterstützt auch die Embedded Viewer API eine Reihe von Werten zur Identifizierung eines bestimmten Buches. Dazu gehören:

ISBN: Die eindeutige 10- oder 13-stellige kommerzielle International Standard Book Number.
Beispiel: ISBN:0738531367
OCLC-Nummer: Die eindeutige Nummer, die einem Buch vom OCLC zugewiesen wird, wenn der Datensatz des Buchs dem Katalogisierungssystem von WorldCat hinzugefügt wird.
Beispiel: OCLC:70850767
Logo: LCCN: Die Library of Congress Control Number, die von der Library of Congress zugeschrieben wurde.
Beispiel: LCCN:2006921508
Google Books-Band-ID: Der eindeutige String, den Google Books dem Band zugeordnet hat und in der URL des Buchs auf Google Books erscheint.
Beispiel: Py8u3Obs4f4C
Vorschau-URL für Google Books: Eine URL, über die eine Buchvorschauseite bei Google Books geöffnet wird.
Beispiel: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Diese IDs werden häufig mit anderen APIs in der Google Books API-Familie verwendet. Beispielsweise können Sie Dynamic Links verwenden, um eine Vorschauschaltfläche nur dann zu rendern, wenn das Buch eingebettet werden kann, und dann, wenn der Nutzer auf die Schaltfläche klickt, einen Betrachter mithilfe der vom Dynamic Links-Aufruf zurückgegebenen Vorschau-URL instanziieren. Mit der Books API, die mehrere geeignete Branchenbezeichnungen in ihren Volumes-Feeds zurückgibt, können Sie eine umfangreiche Anwendung zum Durchsuchen und Vorschau erstellen. Auf der Beispielseite können Sie sich einige erweiterte Implementierungen ansehen.

Fehlgeschlagene Initialisierungen verarbeiten

In einigen Fällen kann der load-Aufruf fehlschlagen. Dies geschieht in der Regel, wenn die API ein Buch, das der angegebenen ID zugeordnet ist, nicht finden konnte, wenn keine Vorschau des Buchs verfügbar ist, die Buchvorschau nicht eingebettet werden kann oder wenn aufgrund von Gebietsbeschränkungen der Endnutzer dieses bestimmte Buch nicht sehen kann. Möglicherweise möchten Sie über einen solchen Fehler informiert werden, damit Ihr Code diese Bedingung ordnungsgemäß verarbeiten kann. Aus diesem Grund ermöglicht Ihnen die Funktion load, den optionalen zweiten Parameter notFoundCallback zu übergeben, der angibt, welche Funktion aufgerufen werden soll, wenn das Buch nicht geladen werden kann. Der folgende Code generiert beispielsweise eine JavaScript-Benachrichtigungsfeld, wenn das Buch eingebettet werden kann:

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

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

Beispiel ansehen (book-notfound.html)

Mit diesem Callback können Sie einen ähnlichen Fehler anzeigen oder das viewerCanvas-Element vollständig ausblenden. Der Callback-Parameter für den Fehler ist optional und nicht im „Hello World“-Beispiel enthalten.

Hinweis: Da Vorschauen möglicherweise nicht für alle Bücher und nicht für alle Nutzer verfügbar sind, kann es nützlich sein zu wissen, ob eine Vorschau verfügbar ist, bevor Sie versuchen, eine Vorschau dafür zu laden. So können Sie beispielsweise eine Schaltfläche, eine Seite oder einen Bereich für die Google-Vorschau nur dann in Ihrer Benutzeroberfläche anzeigen, wenn eine Vorschau für den Nutzer tatsächlich verfügbar ist. Dazu können Sie die Books API oder Dynamic Links verwenden. Beide geben an, ob ein Buch über den Viewer eingebettet werden kann.

Erfolgreiche Initialisierungen verarbeiten

Es kann auch hilfreich sein zu wissen, ob und wann ein Buch erfolgreich geladen wurde. Aus diesem Grund unterstützt die load-Funktion den optionalen dritten Parameter successCallback, der ausgeführt wird, sobald ein Buch fertig geladen ist.

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

Beispiel ansehen (book-success.html)

Dieser Callback kann nützlich sein, wenn Sie beispielsweise bestimmte Elemente auf Ihrer Seite nur dann anzeigen möchten, wenn der Betrachter vollständig gerendert hat.

Viewer beim Laden zeigen

  google.books.setOnLoadCallback(initialize);

Während eine HTML-Seite gerendert wird, wird das DOM (Document Object Model) umgesetzt und alle externen Bilder und Skripts werden empfangen und in das document-Objekt aufgenommen. Damit der Viewer erst auf der Seite platziert wird, nachdem die Seite vollständig geladen wurde, wird die google.books.setOnLoadCallback-Funktion verwendet, um die Ausführung der Funktion zu verzögern, mit der das DefaultViewer-Objekt erstellt wird. Da setOnLoadCallback nur dann initialize aufruft, wenn die Embedded Viewer API geladen und einsatzbereit ist, wird unvorhersehbares Verhalten vermieden und es wird gesteuert, wie und wann der Viewer gezogen wird.

Hinweis:Um die browserübergreifende Kompatibilität zu maximieren, wird dringend empfohlen, das Laden des Betrachters mit der Funktion google.books.setOnLoadCallback zu planen, anstatt ein onLoad-Ereignis im <body>-Tag zu verwenden.

Zuschauerinteraktionen

Da Sie jetzt ein DefaultViewer-Objekt haben, können Sie mit ihm interagieren. Das grundlegende Viewer-Objekt sieht ähnlich aus wie der Nutzer, mit dem Sie auf der Google Books-Website interagieren, und verhält sich auch ähnlich. Es bietet zahlreiche integrierte Funktionen.

Du kannst aber auch programmatisch mit dem Zuschauer interagieren. Das DefaultViewer-Objekt unterstützt eine Reihe von Methoden, mit denen der Vorschaustatus direkt geändert werden kann. Die Methoden zoomIn(), nextPage() und highlight() werden beispielsweise programmatisch und nicht über Nutzerinteraktionen auf den Zuschauer angewendet.

Im folgenden Beispiel wird eine Buchvorschau angezeigt, bei der alle drei Sekunden automatisch zur nächsten Seite gewechselt wird. Befindet sich die nächste Seite im sichtbaren Teil des Betrachters, schwenkt er sie gleichmäßig. Andernfalls springt er direkt zum Anfang der nächsten Seite.

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

Beispiel ansehen (book-animate.html)

Programmatische Aufrufe an den Betrachter schlagen fehl oder werden erst wirksam, wenn der Betrachter mit einem bestimmten Buch vollständig initialisiert wurde. Damit diese Funktionen nur aufgerufen werden, wenn der Viewer bereit ist, verwenden Sie den successCallback-Parameter für viewer.load wie oben beschrieben.

Informationen zu allen vom Objekt DefaultViewer unterstützten Funktionen finden Sie im Referenzhandbuch.

Programmierhinweise

Bevor Sie sich mit der Embedded Viewer API befassen, sollten Sie die folgenden Punkte beachten, damit Ihre Anwendung auf den gewünschten Plattformen reibungslos funktioniert.

Browserkompatibilität

Die Embedded Viewer API unterstützt aktuelle Versionen von Internet Explorer, Firefox und Safari sowie normalerweise auch andere Gecko- und WebKit-basierte Browser wie Camino und Google Chrome.

Verschiedene Anwendungen erfordern manchmal unterschiedliches Verhalten bei Nutzern mit inkompatiblen Browsern. Die Embedded Viewer API verhält sich nicht automatisch, wenn sie einen inkompatiblen Browser erkennt. Die meisten Beispiele in diesem Dokument prüfen weder die Browserkompatibilität, noch zeigen sie eine Fehlermeldung für ältere Browser an. Echte Anwendungen funktionieren mit alten oder inkompatiblen Browsern möglicherweise nutzerfreundlicher. Solche Prüfungen werden jedoch weggelassen, um die Beispiele besser lesbar zu machen.

Bei herkömmlichen Anwendungen werden unweigerlich Inkonsistenzen zwischen Browsern und Plattformen auftreten. Websites wie quirksmode.org sind ebenfalls gute Ressourcen für die Suche nach Behelfslösungen.

XHTML- und Quirks-Modus

Wir empfehlen, auf Seiten, die den Viewer enthalten, standardkonforme XHTML zu verwenden. Wenn Browser den XHTML-DOCTYPE oben auf der Seite sehen, rendern sie die Seite im „Standards Compliance Mode“, wodurch Layout und Verhalten in verschiedenen Browsern besser vorhersehbar werden. Seiten ohne diese Definition werden möglicherweise im Quirks-Modus gerendert, was zu einem uneinheitlichen Layout führen kann.

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

Hinweis zu den Beispielen für die Embedded Viewer API

Beachten Sie, dass die meisten Beispiele in dieser Dokumentation nur den relevanten JavaScript-Code zeigen, nicht die vollständige HTML-Datei. Sie können den JavaScript-Code in Ihre eigene HTML-Basisdatei einfügen oder die vollständige HTML-Datei für jedes Beispiel herunterladen, indem Sie auf den Link nach dem Beispiel klicken.

Fehlerbehebung

Wenn Ihr Code nicht zu funktionieren scheint, finden Sie hier einige Ansätze, die Ihnen bei der Lösung Ihrer Probleme helfen könnten:

Suchen Sie nach Tippfehlern. Denken Sie daran, dass in JavaScript zwischen Groß- und Kleinschreibung unterschieden wird.
Verwenden Sie einen JavaScript-Debugger. In Firefox können Sie die JavaScript-Konsole, den Venkman Debugger oder das Firebug-Add-on verwenden. In IE können Sie den Microsoft Script Debugger verwenden. In Google Chrome sind zahlreiche Entwicklertools bereits integriert, darunter ein DOM Inspector und ein JavaScript-Debugger.