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

デベロッパーガイド

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

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

視聴者

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

このドキュメントでは概念を説明しており、読者が Embedded Viewer API を使用したアプリケーションについて学び、このようなアプリケーションの開発を始めることができるようにすることを目的としています。上級ユーザーの場合は、Embedded Viewer API リファレンスをご覧ください。サポートされているメソッドとレスポンスに関する包括的な情報が記載されています。

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

Embedded Viewer API の「Hello, World」

Embedded Viewer API について学習するには、シンプルな例を見るのが最も簡単な方法です。次のウェブページには、Nicholas Perry 著の Mountain View（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 要素を作成します。
JavaScript 関数を記述して「ビューア」オブジェクトを作成します。
一意の識別子（この場合は ISBN:0738531367）を使用して書籍を読み込みます。
API が完全に読み込まれたら、google.books.setOnLoadCallback を使用して initialize を呼び出します。

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

Embedded Viewer API の読み込み

API ローダーフレームワークを使用して Embedded Viewer API を読み込むのは比較的簡単です。次の 2 つのステップで構成されます。

API Loader ライブラリを含めます。

<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、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 があります。

英語以外の言語で 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 リファレンスからわかりやすく要約）を以下に示します。constructor

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

コンストラクタの 2 番目のパラメータは省略可能です。このパラメータは、このドキュメントの範囲を超える高度な実装を対象としており、「Hello, World」の例では省略されています。

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

  viewer.load('ISBN:0738531367');

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

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

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

初期化の失敗を処理する

場合によっては、load 呼び出しが失敗することがあります。通常、このエラーは、指定された ID に関連付けられた書籍が API で見つからない場合、書籍のプレビューが利用できないとき、書籍のプレビューを埋め込めない場合、または地域の制限によりエンドユーザーがこの特定の書籍を表示できない場合に発生します。このような障害が発生した場合に通知を受け取るようにして、コードでこの状態を適切に処理できるようにすることもできます。このため、load 関数では、2 番目のパラメータ（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 プレビュー」のボタン、ページ、セクションは、ユーザーが実際にプレビューを利用できる場合にのみ 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-animate.html）

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

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 Debugger を使用できます。Google Chrome ブラウザには、DOM インスペクタや JavaScript デバッガなど、さまざまな開発ツールが組み込まれています。

デベロッパー ガイド

視聴者