开发人员指南

通过 Embed Viewer API，您可以使用 JavaScript 将 Google 图书中的图书内容直接嵌入您的网页。该 API 还提供了许多用于操控图书预览的实用程序，通常与本网站介绍的其他 API 结合使用。

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

观众

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

本概念性文档并不详尽，详尽无遗；旨在帮助您快速开始使用 Embed Viewer API 探索和开发出色的应用。高级用户可能会对 嵌入式查看器 API 参考文档感兴趣，其中提供了有关受支持的方法和响应的全面详情。

如上所述，初学者最好先使用预览向导，该工具会自动生成在网站上嵌入基本预览所需的代码。

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

若要开始了解嵌入式查看器 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>

您可以查看此示例，然后下载它来进行修改和修改它。即使在这个简单的示例中，也有五点需要注意：

  1. 我们使用 script 标记添加 API 加载器。
  2. 我们创建一个名为“viewerCanvas”的 div 元素来存放查看器。
  3. 我们编写了一个 JavaScript 函数以创建“viewer”对象。
  4. 我们使用其唯一标识符（在本例中为 ISBN:0738531367）加载图书。
  5. 当该 API 完全加载后，我们会使用 google.books.setOnLoadCallback 调用 initialize。

下文介绍了这些步骤。

加载 Embed 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 方法接受可选的 list 参数，以指定回调函数或语言，如下文所述。
    <script type="text/javascript">
  google.books.load();
</script>

加载本地化版本的 Embed Viewer API

在显示提示、控件名称和链接文本等文本信息时，嵌入式查看器 API 默认使用英语。如果您希望更改 Embed Viewer API 以以特定语言正确显示信息，可以向 google.books.load 调用添加可选的 language 参数。

例如，如需显示采用巴西葡萄牙语界面语言的图书预览模块，请执行以下操作：

<script type="text/javascript">
  google.books.load({"language": "pt-BR"});
</script>

查看示例 (book-language.html)

。

使用非英语的 Embed Viewer API 时，我们强烈建议您提供 content-type 标头设为 utf-8 的页面，或在页面中添加等效的 <meta> 标记。这样做有助于确保字符在所有浏览器中都能正确呈现。如需了解详情，请参阅关于设置 HTTP 字符集参数的 W3C 页面。

Viewer 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 要显示的图书。必须先发送此方法，然后再在查看器对象上执行任何其他操作。

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

支持的图书标识符

与 Dynamic Links 功能一样，嵌入式查看器 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 Books API 系列中的其他 API 一起使用。例如，您可以使用 Dynamic Links 仅在图书可嵌入时呈现预览按钮，然后在用户点击该按钮时，使用 Dynamic Links 调用返回的预览网址将观看者实例化。同样，您可以使用 Books API 构建内容丰富的预览应用，以便在 Volume 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-notfind.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 之前，您应该注意以下几点，以确保您的应用能够在预期平台上顺畅运行。

浏览器兼容性

嵌入式查看器 API 支持最新版本的 Internet Explorer、Firefox 和 Safari，通常也包括其他基于 Gecko 和 WebKit 的浏览器，例如 Camino 和 Google Chrome。

对于使用不兼容浏览器的用户，不同的应用有时会要求他们执行不同的操作。嵌入式浏览器 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 文件。

问题排查

如果您的代码似乎不起作用，您可以尝试使用以下方法解决问题：