开发人员指南

借助 Embedded Viewer API，您可以使用 JavaScript 将 Google 图书中的图书内容直接嵌入到您的网页中。该 API 还提供了许多用于处理图书预览的实用程序，并且经常与本网站上介绍的其他 API 一起使用。

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

观众

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

本概念性文档并不完整，也并非详尽无遗；旨在帮助您快速着手了解 Embedded Viewer API 并利用它开发酷炫应用。高级用户可能对 Embedded Viewer API 参考文档感兴趣，其中提供了有关受支持方法和响应的全面详细信息。

如上所述，初学者可能希望先使用预览向导，它会自动生成在网站上嵌入基本预览所需的代码。

Embedded Viewer API 的“Hello, World”

若要开始了解 Embedded Viewer API，最简单的方法就是查看一个简单的示例。 以下网页显示了 Mountain View 的 600x500 预览，作者：Nicholas Perry，ISBN 0738531367（属于 Arcadia Publishing 的《美国图片》的一部分）：

<!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 加载器框架加载 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

默认情况下，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、lv、lt、pt、pt、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() 称为构造函数，其定义（在 Embedded Viewer API 参考文档中进行了精简提述）如下所示：

构造函数 说明
DefaultViewer(container, opts?) 在指定的 HTML 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:2006921508
Google 图书卷 ID
Google 图书为书卷指定的唯一字符串，显示在 Google 图书上相应图书的网址中。
示例：Py8u3Obs4f4C
Google 图书预览网址
用于在 Google 图书上打开图书预览页面的网址。
示例：https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

这些标识符通常与 Google Books API 系列中的其他 API 一起使用。例如，仅当图书是可嵌入的时，才能使用动态链接来呈现预览按钮；然后，当用户点击按钮时，使用动态链接调用返回的预览网址对查看器进行实例化。同样，您可以使用 Books API 构建内容丰富的浏览和预览应用，该 API 会在其卷 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 仅在 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 和 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">

关于 Embedded Viewer API 示例的说明

请注意，本文档中的大部分示例仅显示相关的 JavaScript 代码，而非完整的 HTML 文件。您可以将 JavaScript 代码插入到自己的 HTML 框架文件中，也可以点击示例后面的链接，下载每个示例的完整 HTML 文件。

问题排查

如果您的代码不起作用，则下面的一些方法可能可以帮助您解决问题：