开发人员指南

借助嵌入式查看器 API，您可以使用 JavaScript 直接在网页中嵌入 Google 图书中的图书内容。该 API 还提供了一些用于操控图书预览的实用程序，并且通常与本网站上介绍的其他 API 搭配使用。

预览向导是基于嵌入式观看器 API 构建的工具，只需复制几行代码，即可更轻松地为您的网站添加预览功能。本文档适用于希望自定义查看器在其网站上的外观的更高级开发者。

观众

本文档面向熟悉 JavaScript 编程和面向对象编程概念的人员。此外，您还应从用户的角度熟悉 Google 图书。您可以在网上找到许多 JavaScript 教程。

本概念性文档并非详尽无遗，旨在帮助您快速着手了解 Embedded Viewer API 并利用它开发出酷炫的应用。高级用户可能对嵌入式观看器 API 参考文档感兴趣，其中详细介绍了支持的方法和响应。

如上所述，新手可能需要先使用预览向导，该向导会自动生成在您的网站上嵌入基本预览所需的代码。

嵌入式观看器 API 的“Hello, World”

若要开始了解 Embedded Viewer API，最简单的方法就是查看一个简单的示例。 以下网页显示了 Mountain View（作者：Nicholas Perry，ISBN 0738531367，属于 Arcadia Publishing 的“Images of America”系列图书）的 600 x 500 预览图：

<!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. 我们使用图书的唯一标识符（在本例中为 ISBN:0738531367）加载图书。
  5. 在 API 完全加载后，我们使用 google.books.setOnLoadCallback 调用 initialize。

下文介绍了这些步骤。

加载 Embedded Viewer API

使用 API 加载器框架加载嵌入式查看器 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 在显示提示、控件名称和链接文本等文本信息时使用英语。如果您希望更改嵌入式观看器 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() 称为“构造函数”，其定义（从 嵌入式观看器 API 参考文档中浓缩而来，以便于理解）如下所示：constructor

构造函数 说明
DefaultViewer(container, opts?) 在给定 HTML container 中创建新的观看器，该 container 应为网页上的块级元素（通常为 DIV）。使用可选的 opts 参数传递高级选项。

请注意，构造函数中的第二个参数是可选的，适用于本文档范围之外的高级实现，并且在“Hello, World”示例中省略了该参数。

使用特定图书初始化查看器

  viewer.load('ISBN:0738531367');

通过 DefaultViewer 构造函数创建查看器后，需要使用特定图书对其进行初始化。此初始化是使用观看器的 load() 方法完成的。load() 方法需要一个 identifier 值，用于告知 API 要显示哪本图书。必须先发送此方法，然后才能对观看器对象执行任何其他操作。

如果您知道图书的多个标识符（平装版的 ISBN 或备用 OCLC 编号），则可以将标识符字符串数组作为第一个参数传递给 load() 函数。如果有与数组中的任意标识符关联的可嵌入预览，观看器将呈现图书。

支持的图书标识符

与 Dynamic Links 功能一样，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

这些标识符通常与 Google 图书 API 系列中的其他 API 搭配使用。例如，只有在图书可嵌入时，您才能使用动态链接呈现预览按钮，然后在用户点击该按钮时，使用动态链接调用返回的预览网址实例化观看器。同样，您可以使用 Books API 构建丰富的浏览和预览应用，该 API 会在其“Volumes”Feed 中返回多个合适的行业标识符。如需了解一些高级实现，请访问示例页面。

处理失败的初始化

在某些情况下，load 调用可能会失败。这通常在以下情况下会发生：API 找不到与提供的标识符相关联的图书；未提供图书预览；无法嵌入图书预览；或地区限制导致最终用户无法查看这本特定图书。您可能希望收到此类失败的提醒，以便您的代码妥善处理这种情况。因此，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 或Dynamic Links 来实现此目的，这两者都会报告图书是否可供使用查看器嵌入。

处理成功的初始化

了解图书是否已成功加载以及加载时间可能也很有用。因此，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 对象支持的所有函数，请参阅参考指南。

编程说明

在开始深入了解嵌入式观看器 API 之前，您应注意以下问题，以确保您的应用能够在预期的平台上顺畅运行。

浏览器兼容性

Embedded Viewer API 支持最新版本的 Internet Explorer、Firefox 和 Safari，通常还支持其他基于 Gecko 和 WebKit 的浏览器，如 Camino 和 Google Chrome。

对于使用不兼容浏览器的用户，不同的应用有时需要不同的行为。嵌入式观看器 API 在检测到不兼容的浏览器时不会执行任何自动行为。本文档中的大多数示例都不会检查浏览器兼容性，也不会向旧版浏览器显示错误消息。实际应用可能会采取一些更适合旧版或不兼容的浏览器的做法，但为了使示例更易于阅读，我们省略了此类检查。

大型应用会不可避免地遇到浏览器和平台之间的不一致问题。quirksmode.org 等网站也是查找权宜解决方法的好资源。

XHTML 和 Quirks 模式

我们建议您在包含该查看器的网页上使用符合标准的 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 文件。

问题排查

如果您的代码似乎无法正常运行，请尝试以下方法来解决问题：