通过 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>
您可以查看此示例,然后下载它来进行修改和修改它。即使在这个简单的示例中,也有五点需要注意:
- 我们使用
script
标记添加 API 加载器。 - 我们创建一个名为“viewerCanvas”的
div
元素来存放查看器。 - 我们编写了一个 JavaScript 函数以创建“viewer”对象。
- 我们使用其唯一标识符(在本例中为
ISBN:0738531367
)加载图书。 - 当该 API 完全加载后,我们会使用
google.books.setOnLoadCallback
调用initialize
。
下文介绍了这些步骤。
加载 Embed Viewer API
使用 API 加载器框架加载嵌入式查看器 API 相对比较简单。这涉及到以下两个步骤:
- 添加 API 加载器库:
<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
- 调用
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>
。
使用非英语的 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); }
您可以使用此回调来决定显示类似的错误,也可以选择完全隐藏 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); }
此回调在某些情况下可能很有用,例如您只想在浏览者完全呈现网页上显示某些元素时。
在加载时显示观看者
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);
请注意,在查看器使用特定图书完全初始化之前,对查看器的程序化调用将失败或不起作用。为了确保仅在观看者准备就绪时调用此类函数,请使用 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 文件。
问题排查
如果您的代码似乎不起作用,您可以尝试使用以下方法解决问题:
- 查找拼写错误。切记 JavaScript 是一种区分大小写的语言。
- 使用JavaScript调试程序。在 Firefox 中,您可以使用 JavaScript 控制台、Venkman Debugger 或 Firebug 插件。 在 IE 中,您可以使用 Microsoft 脚本调试程序。Google Chrome 浏览器内置了许多开发工具,其中包括 DOM 检查器和 JavaScript 调试程序。