開發人員指南

嵌入式檢視器 API 可讓您使用 JavaScript，直接在 Google 圖書中嵌入書籍內容。此 API 也提供許多公用程式，可用來操控書籍預覽功能，並且經常與本網站描述的其他 API 搭配使用。

預覽精靈是以 嵌入式檢視器 API 為基礎打造的工具，只要複製兩行程式碼，即可輕鬆在網站上加入預覽功能。本文件的適用對象為想進一步自訂觀眾在網站上的顯示方式。

觀眾

本說明文件的適用對象為熟悉 JavaScript 程式設計和物件導向程式設計概念的使用者。您也應該從使用者的角度對 Google 圖書相當熟悉。網路上有許多 JavaScript 教學課程。

本概念說明文件的內容並不完整，旨在協助您透過 Embedded Viewer API 快速探索及開發酷炫的應用程式。進階使用者應考慮使用 Embedded Viewer API 參考資料，其中提供有關支援方法和回應的完整詳細資訊。

如上所述，初學者可以先從預覽精靈開始；這個精靈會自動產生必要的程式碼，在您的網站上嵌入基本預覽。

Embedded Viewer API 的「Hello, World」

如要開始瞭解 Embedded Viewer API，最簡單的方法就是查看簡單的範例。 以下網頁顯示由 Nicholas Perry 所提供 ISBN 0738531367 (Acacadia 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>

您可以參考這個範例並下載範例，以進行編輯和處理。就算這只是一個簡單的範例，仍有五件事情需要注意：

  1. 使用 script 標記來涵蓋 API 載入器。
  2. 我們建立了一個名為「viewerCanvas」的 div 元素來存放檢視器。
  3. 我們編寫 JavaScript 函式來建立「viewer」物件。
  4. 我們使用書籍專屬 ID (本例中為 ISBN:0738531367) 載入書籍。
  5. 當 API 已完整載入時，我們會使用 google.books.setOnLoadCallback 呼叫 initialize。

這些步驟說明如下：

載入 Embedded Viewer API

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

  1. 加入 API 載入器程式庫： 
    <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>

載入本地化版本的 Embedded Viewer API

根據預設，嵌入式檢視器 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、lv、lt、ms、mbpt 和 ms

以英文以外的語言使用 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

嵌入式檢視器 API 與動態連結功能一樣，都支援多個值，可用於識別特定書籍。包括：

ISBN
不重複的 10 位數或 13 位數商業國際標準書號。
範例：ISBN:0738531367
OCLC 編號
將書籍記錄加入 WorldCat 目錄系統時，OCLC 指派給書籍的專屬編號。
範例：OCLC:70850767
LCCN
由美國國會圖書館為相關記錄指派的美國國會圖書館控管編號。
範例：LCCN:2006921508
Google 圖書冊號
Google 圖書指派給書籍的不重複字串，顯示在 Google 圖書的書籍網址中。
範例：Py8u3Obs4f4C
Google 圖書試閱網址
在 Google 圖書上開啟書籍試閱頁面的網址。
範例：https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

這些 ID 經常與 Google Books API 系列中的其他 API 搭配使用。舉例來說，只有在書籍可以嵌入的情況下，您可以使用動態連結顯示預覽按鈕；這樣一來，當使用者點選按鈕時，系統就會使用動態連結呼叫傳回的預覽網址將檢視器執行個體化。同樣地，您可以使用 Books API 建構內容豐富的瀏覽與預覽應用程式，並在其「磁碟區」動態饋給中傳回數個適合的產業識別碼。請前往範例網頁，瞭解一些進階的實作方式。

處理失敗的初始化作業

在某些情況下，load 呼叫可能會失敗。這種情況通常會發生在 API 找不到與指定 ID 相關聯的書籍、沒有書籍開放試閱、書籍無法嵌入時，或是地區限制導致使用者無法看到特定書籍時。您可能會想要收到這類故障的快訊，以便程式碼妥善處理此狀況。因此，load 函式可讓您傳遞選用的第二個參數 notFoundCallback，該參數表示無法載入書籍時該呼叫哪一個函式。舉例來說，以下程式碼會產生書籍警示，讓使用者能夠嵌入書籍：

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 只會在 嵌入式檢視器 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">

Embedded Viewer API 範例說明

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

疑難排解

如果您的程式碼似乎無法運作，以下這些方法可協助您解決問題：