このページは Cloud Translation API によって翻訳されました。

デベロッパーガイド

Embedded Viewer API を使用すると、JavaScript を使用して、Google ブックスの書籍コンテンツをウェブページに直接埋め込むことができます。この API には、書籍のプレビューを操作するためのさまざまなユーティリティも用意されています。この API は、このサイトで説明している他の API と一緒によく使用されます。

プレビューウィザードは Embedded Viewer API の上に構築されているツールで、数行のコードをコピーするだけでサイトにプレビュー機能を簡単に追加できます。このドキュメントは、サイトでのビューアの表示方法をカスタマイズすることを検討している上級開発者を対象としています。

視聴者

このドキュメントは、JavaScript プログラミングとオブジェクト指向プログラミングの概念を理解しているデベロッパーを対象にしています。また、ユーザーの視点で Google ブックスについての知識があることも必要です。ウェブ上に多数ある JavaScript チュートリアルも参考にしてください。

このコンセプトドキュメントは完全で網羅的なものではありません。Embedded Viewer API を使った優れたアプリケーションの調査と開発をすぐに開始できるように設計されています。上級ユーザーの場合は、Embedded Viewer API リファレンスを参照してください。このリファレンスには、サポートされているメソッドとレスポンスに関する包括的な詳細情報が記載されています。

前述したように、初心者はプレビューウィザードから始めることをおすすめします。プレビューウィザードでは、サイトに基本的なプレビューを埋め込むために必要なコードが自動生成されます。

Embedded Viewer API の「Hello, World」

Embedded Viewer API の学習を始めるには、簡単な例を見るのが最も簡単な方法です。次のウェブページでは、Mountain View（著者: Nicholas Perry、ISBN 0738531367）（Arcadia Publishing の「Images of America」シリーズの一部）のプレビューを 600x500 で表示しています。

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

こちらの例をダウンロードして、編集したり試してみてください。簡単な例ですが、次の 5 つの点に注意してください:

script タグを使用して API ローダを追加します。
「viewerCanvas」という名前の div 要素を作成して、ビューアを保持します。
「viewer」オブジェクトを作成する JavaScript 関数を記述します。
一意の識別子（この場合は ISBN:0738531367）を使用して書籍を読み込みます。
API が完全に読み込まれたときに、google.books.setOnLoadCallback を使用して initialize を呼び出します。

上記のステップについて以下で説明します。

Embedded Viewer API の読み込み

API Loader フレームワークを使用して Embedded Viewer API を読み込むのは比較的簡単です。これには次の 2 つのステップがあります。

API ローダライブラリをインクルードします。

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

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、th、PT、r 、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、pt、pt、ms があります。

英語以外の言語で Embedded Viewer API を使用する場合は、content-type ヘッダーを utf-8 に設定してページを配信するか、同等の <meta> タグをページに含めることを強くおすすめします。これにより、すべてのブラウザで文字が正しくレンダリングされるようになります。詳しくは、W3C の HTTP charset パラメータの設定に関するページをご覧ください。

閲覧者の DOM 要素

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

ウェブページに書籍を表示するには、書籍用のスペースを確保する必要があります。名前付きの div 要素を作成し、ブラウザのドキュメントオブジェクトモデル（DOM）内でこの要素への参照を取得するのが一般的です。

上記の例では、「viewerCanvas」という名前の div を定義し、スタイル属性を使用してそのサイズを設定しています。ビューアは、コンテナのサイズを暗黙的に使用して自身のサイズを決定します。

DefaultViewer オブジェクト

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

ページ上の単一の閲覧者を作成して制御する JavaScript クラスは DefaultViewer クラスです。（このクラスのインスタンスは複数作成でき、各オブジェクトでページ上の閲覧者が 1 つずつ定義されます）。このクラスの新しいインスタンスは、JavaScript の new 演算子を使用して作成されます。

新しいビューアインスタンスを作成する場合は、ビューアのコンテナとしてページ内の DOM ノード（通常は div 要素）を指定します。HTML ノードは JavaScript document オブジェクトの子であり、この要素への参照を document.getElementById() メソッドで取得します。

このコードは、変数（名前は viewer）を定義し、その変数を新しい DefaultViewer オブジェクトに割り当てます。関数 DefaultViewer() はコンストラクタと呼ばれます。以下に、その定義（ Embedded Viewer API リファレンスから簡略化）を示します。

コンストラクタ	説明
DefaultViewer(container, opts?)	指定された HTML `container` 内に新しいビューアを作成します。このビューアは、ページ上のブロックレベルの要素（通常は `DIV`）です。詳細オプションは、オプションの `opts` パラメータで渡されます。

コンストラクタの 2 番目のパラメータはオプションであり、このドキュメントの範囲外の高度な実装を想定したものであり、「Hello, World」の例では省略されています。

特定の書籍でビューアを初期化する

  viewer.load('ISBN:0738531367');

DefaultViewer コンストラクタでビューアを作成したら、それを特定の書籍で初期化する必要があります。この初期化は、ビューアの load() メソッドを使用して行います。load() メソッドには、表示する書籍を API に指示する identifier 値が必要です。このメソッドは、ビューアオブジェクトに対して他のオペレーションが実行される前に送信される必要があります。

書籍に複数の識別子（ペーパーバック版の ISBN または別の OCLC 番号）がわかっている場合は、識別子文字列の配列を load() 関数の最初のパラメータとして渡すことができます。配列内のいずれかの ID に関連付けられた埋め込み可能なプレビューがある場合、閲覧者は書籍をレンダリングします。

サポートされている書籍 ID

Dynamic Links 機能と同様に、Embedded Viewer API は特定の書籍を識別するためのさまざまな値をサポートしています。次のようなものがあります。

ISBN: 10 桁または 13 桁の固有の商用国際標準図書番号。
例: ISBN:0738531367
OCLC 番号: 書籍のレコードが WorldCat カタログシステムに追加されたときに OCLC が書籍に割り当てる一意の番号。
例: OCLC:70850767
LCCN: 米国議会図書館によって記録に割り当てられる米国議会図書館管理番号。
例: LCCN:2006921508
Google ブックスの巻 ID: Google ブックスが巻に割り当てた一意の文字列。Google ブックスの書籍の URL に表示されます。
例: Py8u3Obs4f4C
Google ブックスのプレビュー URL: Google ブックスで書籍のプレビューページを開く URL。
例: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

これらの識別子は、Google ブックス API ファミリーの他の API でよく使用されます。たとえば、Dynamic Links を使用して、書籍が埋め込み可能な場合にのみプレビューボタンをレンダリングし、ユーザーがそのボタンをクリックしたときに、Dynamic Links の呼び出しによって返されるプレビュー URL を使用してビューアをインスタンス化できます。同様に、Books API を使用して、ブラウジングとプレビューの機能豊富なアプリケーションを作成できます。この API は、ボリュームフィードでいくつかの適切な業界識別子を返します。高度な実装の例については、サンプルページをご覧ください。

失敗した初期化の処理

場合によっては、load の呼び出しが失敗することがあります。これは通常、指定された ID に関連付けられた書籍を API が見つけられなかった場合、利用できる書籍のプレビューがない場合、書籍のプレビューを埋め込めない場合、またはエンドユーザーがこの特定の書籍を表示できない場合に発生します。障害が発生した場合はアラートを受け取り、コードでこの条件を適切に処理できるようにしたい場合があります。そのため、load 関数では、オプションの 2 番目のパラメータ notFoundCallback を渡すことができます。これは、書籍を読み込めなかった場合にどの関数を呼び出すかを示します。たとえば次のコードは、書籍が埋め込まれる可能性がある場合に JavaScript の「alert」ボックスを生成します。

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 プレビュー」のボタン、ページ、セクションは、ユーザーが実際にプレビューを利用できる場合にのみ UI に表示します。これを行うには、Books API または Dynamic Links を使用します。どちらも、ビューアを使用して書籍を埋め込むことができるかどうかを報告します。

成功した初期化の処理

また、書籍が正常に読み込まれたかどうかや、いつ読み込まれたかを把握しておくと役に立つことがあります。そのため、load 関数はオプションの 3 番目のパラメータ 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 は、Embedded Viewer API が読み込まれて使用できる状態になった場合にのみ initialize を呼び出すため、予期しない動作を回避し、ビューアを描画する方法とタイミングを確実に制御できます。

注: ブラウザ間の互換性を最大限に高めるには、<body> タグで onLoad イベントを使用するのではなく、google.books.setOnLoadCallback 関数を使用してビューアの読み込みをスケジュール設定することを強くおすすめします。

視聴者の操作

これで 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-annotate.html）

なお、ビューアへのプログラムによる呼び出しは、閲覧者が特定の書籍で完全に初期化されるまで失敗するか効果がありません。ビューアの準備ができている場合にのみこのような関数を呼び出すには、上記のように successCallback パラメータを viewer.load に使用します。

DefaultViewer オブジェクトでサポートされているすべての関数については、リファレンスガイドをご覧ください。

プログラミングメモ

Embedded Viewer API の詳細に入る前に、目的のプラットフォームでアプリケーションがスムーズに動作することを確認するために、次の点に注意してください。

ブラウザの互換性

Embedded Viewer API は、Internet Explorer、Firefox、Safari の最新バージョンをサポートしています。また、通常は Camino や Google Chrome など、Gecko および WebKit ベースのその他のブラウザにも対応しています。

互換性のないブラウザを使用しているユーザーに対しては、アプリケーションごとに異なる動作が必要になる場合があります。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 ファイル全体をダウンロードすることもできます。

トラブルシューティング

コードが機能しない場合は、次のアプローチを参考にしてください。

入力ミスを探します。JavaScript では大文字と小文字が区別されることに注意してください。
JavaScript デバッガを使用します。Firefox では、JavaScript コンソール、 Venkman Debugger、または Firebug アドオンを使用できます。IE では、 Microsoft Script デバッガを使用できます。Google Chrome ブラウザには、DOM インスペクタや JavaScript デバッガなど、さまざまな開発ツールが組み込まれています。

デベロッパー ガイド

視聴者