本頁面由 Cloud Translation API 翻譯而成。

開發人員指南

Embedded Viewer API 可讓您在網頁中使用 JavaScript 直接嵌入 Google 圖書的圖書內容。API 也提供許多可操控書籍預覽的公用程式，通常會與網站上描述的其他 API 一起使用。

預覽精靈是內建於 Embedded Viewer API 的工具，您只需要複製幾行程式碼，就能輕鬆在網站中加入預覽功能。本文件適用對象為想要自訂檢視者在網站顯示方式的進階開發人員。

觀眾

本說明文件的適用對象為熟悉 JavaScript 程式設計和物件導向程式設計概念的開發人員。此外，您也應該要從使用者的角度熟悉 Google 圖書的介面操作。目前網路上有許多 JavaScript 教學課程可供參考。

本概念說明文件並未涵蓋完整內容，可協助您快速開始使用 Embedded Viewer API 探索並開發酷炫的應用程式。進階使用者可以參閱嵌入檢視器 API 參考資料，其中完整詳述支援方法和回應。

如上所述，新手可以先從「預覽精靈」開始著手；這項工具會自動產生必要的程式碼，方便您在網站上嵌入基本預覽。

嵌入式檢視器 API 的「Hello, World」

開始學習 Embedded Viewer API 時，最簡單的方法就是查看簡易範例。以下網頁顯示 600x500 的 Mountain View (由 Nicholas Perry 開發)，ISBN 0738531367 (屬於 Arcadia Publishing 的「Images of America」系列的一部分)：

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

您可以查看這個範例，然後下載該檔案，以便進行編輯和操作。就算這只是一個簡單的範例，仍有五件事情需要注意：

我們使用 script 標記加入 API 載入器。
我們建立名為「viewerCanvas」的 div 元素來容納檢視器。
我們編寫 JavaScript 函式以建立「檢視器」物件。
我們會使用書籍的專屬 ID (本例中為 ISBN:0738531367) 載入書籍。
當 API 完全載入時，我們會使用 google.books.setOnLoadCallback 呼叫 initialize。

這些步驟說明如下：

載入 Embedded Viewer API

使用 API 載入器架構載入 Embedded Viewer API 相對簡單。它包含下列兩個步驟：

包含 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 以正確顯示特定語言的資訊，您可以在 google.books.load 呼叫中加入選用的 language 參數。

舉例來說，如要顯示巴西葡萄牙文介面的書籍預覽模組，請按照以下步驟操作：

<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、lk、lk、lt、g

如果您以英文以外的語言使用 Embedded Viewer API，強烈建議您將 content-type 標頭設為 utf-8，或在網頁中加入對等的 <meta> 標記。以確保字元在所有瀏覽器中都能正確顯示。如需詳細資訊，請參閱 W3C 的設定 HTTP 字元集參數頁面。

檢視者 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 類別。(您可以建立這個類別的多個例項，每個物件都會在網頁上定義一個獨立的檢視器)。系統會使用 JavaScript new 運算子建立此類別的新例項。

建立新的檢視器執行個體時，您必須在頁面中指定 DOM 節點 (通常是 div 元素) 做為檢視器的容器。HTML 節點是 JavaScript document 物件的子項，而我們可以透過 document.getElementById() 方法取得此元素的參照。

此程式碼會定義變數 (名為 viewer)，並將該變數指派給新的 DefaultViewer 物件。DefaultViewer() 函式亦稱為「建構函式」，其定義 (請參閱「嵌入式檢視器 API 參考資料」一節) 的說明：

建構函式	說明
DefaultViewer(container, opts?)	在指定的 HTML `container` 中建立新的檢視器，此元素應為網頁上的區塊層級元素 (通常是 `DIV`)。進階選項會透過選用的 `opts` 參數傳遞。

請注意，建構函式中的第二個參數為選用參數，適用於不在本文件範圍內的進階實作，且會省略「Hello, World」範例。

初始化特定書籍的檢視器

  viewer.load('ISBN:0738531367');

透過 DefaultViewer 建構函式建立檢視器後，必須使用特定書籍進行初始化。系統會使用檢視器的 load() 方法完成這項初始化作業。load() 方法需要 identifier 值，用於向 API 說明要顯示的書籍。這個方法必須在對檢視器物件執行任何其他作業之前傳送。

如果您知道書籍的多個 ID (平裝本版本的 ISBN 或替代 OCLC 號碼)，可以將一系列 ID 字串做為第一個參數傳遞至 load() 函式。如果陣列中有與「任何」 ID 相關聯的可嵌入預覽，使用者就會在畫面上顯示書籍。

支援的書籍 ID

如同動態連結功能，Embedded Viewer API 支援多個值識別特定書籍。包括：

ISBN: 專屬的 10 或 13 位數商業國際標準書號。
範例：ISBN:0738531367
OCLC 號碼: 在 WorldCat 目錄系統中加入書籍記錄時，OCLC 指派給書籍的專屬編號。
範例：OCLC:70850767
LCCN: 美國國會圖書館指派給登記的國會控制號碼。
範例：LCCN:2006921508
Google 圖書書冊 ID: Google 圖書指派給書籍的專屬字串，顯示於 Google 圖書書籍的網址中。
例如：Py8u3Obs4f4C
Google 圖書預覽網址: 可在 Google 圖書中開啟書籍預覽頁面的網址。
例如：https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

這類 ID 通常會搭配 Google Books API 系列中的其他 API 一起使用。舉例來說，您可以使用動態連結，只在書籍可嵌入時顯示預覽按鈕，接著當使用者點選按鈕時，使用 Dynamic Links 呼叫傳回的預覽網址將檢視器執行個體化。同樣地，您可以使用 Books API 建構內容豐富的瀏覽與預覽應用程式，此 API 會在 Volumes 動態饋給中傳回數個適當的產業識別碼。請前往範例頁面，搶先瞭解部分進階導入做法。

處理失敗的初始化作業

在某些情況下，load 呼叫可能會失敗。發生這種情況，通常是因為 API 找不到與所提供 ID 相關聯的書籍、無法預覽書籍、無法嵌入書籍預覽，或是使用者無法看到書籍的地域限制時。建議您接收這類失敗的快訊，以便讓程式碼妥善處理這個狀況。因此，load 函式可讓您傳遞選用的第二個參數 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 預覽」按鈕、網頁或區段。方法是使用 Books API 或動態連結，這兩種方式會回報書籍能否透過檢視器嵌入。

處理成功初始化

此外，瞭解書籍是否成功載入以及何時成功載入也有幫助。因此，load 函式支援選用第三個參數 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，因此這樣可以避免發生無法預期的行為，並確保能夠控制檢視器的方式和時機。

注意：為了盡可能提高跨瀏覽器相容性，強烈建議您使用 google.books.setOnLoadCallback 函式排定檢視器載入時間，而不要在 <body> 標記上使用 onLoad 事件。

觀眾互動情形

現在，您已擁有 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)

請注意，在檢視者針對特定書籍完成初始化之前，程式輔助呼叫不會執行失敗，或完全沒有作用。為確保您只在檢視器準備就緒時呼叫這類函式，請如上所述，將 successCallback 參數用於 viewer.load。

如需 DefaultViewer 物件支援所有函式的相關資訊，請參閱參考指南。

程式設計注意事項

開始深入瞭解 Embedded Viewer API 之前，您應注意下列問題，以確保應用程式在預期平台上的運作順暢。

瀏覽器相容性

Embedded Viewer API 支援最新版 Internet Explorer、Firefox 和 Safari，通常是其他以 Gecko 和 WebKit 為基礎的瀏覽器，例如 Camino 和 Google Chrome。

不同的應用程式有時會針對使用不相容瀏覽器的使用者，要求不同的行為。當 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">

嵌入式檢視器 API 範例的注意事項

請注意，本文件中大部分的範例只會顯示相關的 JavaScript 程式碼，而非完整的 HTML 檔案。您可以將 JavaScript 程式碼插入自己的基本 HTML 檔案，也可以按一下範例後方的連結，下載每個範例的完整 HTML 檔案。

疑難排解

如果您的程式碼似乎無法運作，可以嘗試以下做法來解決問題：

檢查是否有錯字。請記住，JavaScript 語言須區分大小寫。
使用 JavaScript 除錯工具。在 Firefox 中，您可以使用 JavaScript 控制台、 Venkman Debugger 或 Firebug 外掛程式。在 IE 中，您可以使用 Microsoft Script Debugger。Google Chrome 瀏覽器內建多種開發工具，包括 DOM 檢查器和 JavaScript 偵錯工具。