開發人員指南

Embedded Viewer API 可讓您在網頁中使用 JavaScript 直接嵌入 Google 圖書的圖書內容。這個 API 也提供許多用於操作書籍預覽的工具，通常會與本網站所述的其他 API 搭配使用。

預覽精靈是內建於 Embedded Viewer API 的工具，只要複製幾行程式碼，就能輕鬆為網站新增預覽功能。本文件適用於較進階的開發人員，他們想自訂觀看器在網站上的顯示方式。

觀眾

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

本概念說明文件並非完整且詳盡的說明文件，而是旨在協助您快速起步，探索如何使用 Embedded Viewer API 開發精彩的應用程式。進階使用者可能會對嵌入式檢視器 API 參考資料感興趣，因為這份資料會提供支援的方法和回應的詳細資訊。

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

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

開始學習 Embedded Viewer API 最簡單的方法，就是查看簡易範例。以下網頁顯示 Mountain View (ISBN 0738531367) 的 600 x 500 預覽畫面，作者為 Nicholas Perry (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>

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

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

這些步驟說明如下：

載入 Embedded Viewer API

使用 API Loader 架構載入嵌入式檢視器 API 相當簡單。這項程序包含下列兩個步驟：

  1. 加入 API Loader 程式庫：
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. 呼叫 google.books.load 方法。google.books.load 方法會採用選用的清單參數，指定回呼函式或語言，如下文所述。
    <script type="text/javascript">
  google.books.load();
</script>

載入內嵌式檢視器 API 的本地化版本

Embedded Viewer API 在顯示文字資訊時，預設會使用英文，例如工具提示、控制項名稱及連結文字。如果您想變更嵌入式檢視器 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、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 字元集參數頁面。

觀眾 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() 函式亦稱為「建構函式」constructor，其定義如下 (為方便說明，我們從 Embedded Viewer 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

與動態連結功能一樣，嵌入式檢視器 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 搭配使用。舉例來說，您可以使用動態連結，在書籍可嵌入時顯示預覽按鈕，然後在使用者點選按鈕時，使用動態連結呼叫傳回的預覽網址，將檢視器例項化。同樣地，您也可以使用 Books API 建構功能豐富的瀏覽及預覽應用程式，該 API 會在「Volumes」動態饋給中傳回多個適當的產業 ID。請前往範例頁面，搶先瞭解部分進階導入做法。

處理初始化失敗

在某些情況下，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」範例中。

注意：由於試閱功能可能不適用於所有書籍和使用者，因此建議您在嘗試載入觀看器之前，先確認是否有試閱功能。舉例來說，您可能只想在 UI 中顯示「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 物件支援的所有函式，請參閱參考指南。

程式設計注意事項

開始深入研究嵌入式檢視器 API 前，請先注意下列疑慮，確保應用程式可在預期平台上順利運作。

瀏覽器相容性

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

不同應用程式有時需要針對使用不相容瀏覽器的使用者採取不同的行為。當 Embedded Viewer API 偵測到不相容的瀏覽器時，不會有任何自動行為。本文件中的大部分範例都不會檢查瀏覽器相容性，也不會針對舊版瀏覽器顯示錯誤訊息。實際應用程式可能會針對舊版或不相容的瀏覽器提供更友善的服務，但為了讓範例更易讀，我們省略了這類檢查。

在非簡單的應用程式中，瀏覽器和平台之間的差異是不可避免的。quirksmode.org 等網站也是尋找解決方法的好資源。

XHTML 和相容模式

建議您在包含檢視器的網頁中使用符合標準的 XHTML。當瀏覽器在網頁頂端看到 XHTML DOCTYPE 時，就會以「標準相容模式」算繪網頁，讓各瀏覽器的版面配置和行為更容易預測。沒有該定義的網頁可能會以「quirks 模式」呈現，這可能導致版面配置不一致。

<!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 檔案。

疑難排解

如果程式碼似乎無法運作，以下幾種方法或許能協助您解決問題：