Hướng dẫn dành cho nhà phát triển

API Trình xem được nhúng cho phép bạn nhúng nội dung sách từ Google Sách trực tiếp vào các trang web của mình bằng JavaScript. API này cũng cung cấp một số tiện ích để thao tác với bản xem trước sách và thường được sử dụng cùng với các API khác được mô tả trên trang web này.

Trình hướng dẫn xem trước là một công cụ được tạo phía trên API Trình xem được nhúng, giúp bạn dễ dàng thêm khả năng xem trước vào trang web chỉ bằng cách sao chép vài dòng mã. Tài liệu này dành cho các nhà phát triển chuyên nghiệp hơn muốn tuỳ chỉnh cách trình xem xuất hiện trên trang web của họ.

Thẻ Đối tượng người xem

Tài liệu này dành cho những người đã làm quen với các khái niệm lập trình JavaScript và lập trình hướng đối tượng. Bạn cũng nên làm quen với Google Sách từ góc nhìn của người dùng. Có rất nhiều hướng dẫn về JavaScript trên web.

Tài liệu về khái niệm này chưa đầy đủ và đầy đủ. Tài liệu này được thiết kế để giúp bạn nhanh chóng bắt đầu khám phá và phát triển các ứng dụng thú vị bằng Embedded Users API (API Trình xem được nhúng). Người dùng nâng cao có thể sẽ quan tâm đến Tài liệu tham khảo về API Trình xem được nhúng. Tài liệu này cung cấp thông tin chi tiết toàn diện về các phương thức và phản hồi được hỗ trợ.

Như đã nêu ở trên, người mới bắt đầu có thể bắt đầu với Trình hướng dẫn xem trước. Trình hướng dẫn này tự động tạo mã cần thiết để nhúng các bản xem trước cơ bản vào trang web của bạn.

"Hello, World" của API Trình xem được nhúng

Cách dễ nhất để bắt đầu tìm hiểu về Embedded Player API là xem một ví dụ đơn giản. Trang web sau đây hiển thị bản xem trước 600x500 của Mountain View, của Nicholas Perry, ISBN 0738531367 (thuộc bộ sách "Hình ảnh Mỹ" của Nhà xuất bản Arcadia):

<!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>

Bạn có thể xem ví dụ này và tải xuống để chỉnh sửa và thao tác. Ngay cả trong ví dụ đơn giản này, có năm điều cần lưu ý:

  1. Chúng tôi đưa Trình tải API vào bằng thẻ script.
  2. Chúng ta tạo một phần tử div có tên là "viewerCanvas" để giữ trình xem.
  3. Chúng ta viết một hàm JavaScript để tạo đối tượng "người xem".
  4. Chúng ta tải sách bằng giá trị nhận dạng duy nhất của sách (trong trường hợp này là ISBN:0738531367).
  5. Chúng ta dùng google.books.setOnLoadCallback để gọi initialize khi API đã tải đầy đủ.

Bạn có thể xem phần giải thích cho các bước này như bến dưới.

Tải API Trình xem được nhúng

Việc sử dụng khung Trình tải API để tải API trình xem được nhúng tương đối đơn giản. Quá trình này bao gồm hai bước sau:

  1. Bao gồm thư viện Trình tải API: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Gọi phương thức google.books.load. Phương thức google.books.load lấy một tham số danh sách không bắt buộc để chỉ định một hàm hoặc ngôn ngữ gọi lại, như giải thích dưới đây. 
    <script type="text/javascript">
  google.books.load();
</script>

Tải phiên bản đã bản địa hoá của Embedded Player API

Theo mặc định, API Trình xem được nhúng sử dụng tiếng Anh khi hiển thị thông tin văn bản, chẳng hạn như phần chú thích, tên của các chế độ điều khiển và văn bản của đường liên kết. Nếu muốn thay đổi API Trình xem được nhúng để hiển thị chính xác thông tin bằng một ngôn ngữ cụ thể, bạn có thể thêm tham số language (không bắt buộc) vào lệnh gọi google.books.load.

Ví dụ: để hiển thị mô-đun xem trước sách bằng ngôn ngữ giao diện tiếng Bồ Đào Nha Brazil:

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

Xem ví dụ (book-language.html)

Mã ngôn ngữ RFC 3066 hiện được hỗ trợ bao gồm 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, pt-lt, ms, no, pl, pt-PT-

Khi sử dụng API Trình xem được nhúng bằng các ngôn ngữ khác ngoài tiếng Anh, bạn nên phân phát trang của mình với tiêu đề content-type được đặt thành utf-8 hoặc bao gồm thẻ <meta> tương đương trong trang của bạn. Cách này giúp đảm bảo rằng các ký tự hiển thị chính xác trên tất cả trình duyệt. Để biết thêm thông tin, hãy xem trang của W3C về đặt tham số bộ ký tự HTTP.

Phần tử DOM của người xem

<div id="viewerCanvas" style="width: 600px; height: 500px"></div>

Để một cuốn sách xuất hiện trên trang web, người dùng phải đặt trước một chỗ cho cuốn sách đó. Thông thường, bạn có thể thực hiện việc này bằng cách tạo một phần tử div có tên và lấy thông tin tham chiếu đến phần tử này trong mô hình đối tượng tài liệu (DOM) của trình duyệt.

Ví dụ ở trên xác định một div có tên là "viewerCanvas" và đặt kích thước của thành phần đó bằng cách sử dụng các thuộc tính kiểu. Trình xem ngầm sử dụng kích thước của vùng chứa để xác định kích thước.

Đối tượng DefaultViewer

var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));

Lớp JavaScript tạo và kiểm soát một trình xem trên trang là lớp DefaultViewer. (Bạn có thể tạo nhiều thực thể của lớp này – mỗi đối tượng sẽ xác định một trình xem riêng trên trang.) Một thực thể mới của lớp này sẽ được tạo bằng toán tử JavaScript new.

Khi tạo một phiên bản trình xem mới, bạn chỉ định một nút DOM trong trang (thường là phần tử div) làm vùng chứa cho trình xem. Các nút HTML là con của đối tượng document JavaScript và chúng tôi lấy thông tin tham chiếu đến phần tử này thông qua phương thức document.getElementById().

Mã này xác định một biến (có tên là viewer) và chỉ định biến đó cho một đối tượng DefaultViewer mới. Hàm DefaultViewer() được gọi là hàm khởi tạo và định nghĩa của hàm này (được thu gọn để rõ ràng từ Tài liệu tham khảo API của trình xem được nhúng) như sau:

Hàm dựng Nội dung mô tả
DefaultViewer(container, opts?) Tạo một trình xem mới bên trong container HTML đã cho, vốn phải là phần tử cấp khối trên trang (thường là DIV). Các tuỳ chọn nâng cao được truyền bằng tham số opts tuỳ chọn.

Lưu ý rằng tham số thứ hai trong hàm khởi tạo là không bắt buộc — nhằm mục đích triển khai nâng cao ngoài phạm vi của tài liệu này — và tham số này bị bỏ qua trong ví dụ "Hello, World".

Giới thiệu cho người xem bằng một cuốn sách cụ thể

  viewer.load('ISBN:0738531367');

Sau khi tạo trình xem qua hàm khởi tạo DefaultViewer, chúng ta cần khởi chạy trình xem với một cuốn sách cụ thể. Quá trình khởi chạy này được thực hiện bằng cách sử dụng phương thức load() của người xem. Phương thức load() yêu cầu một giá trị identifier để API này biết cần hiển thị cuốn sách nào. Phương thức này phải được gửi trước khi thực hiện bất kỳ thao tác nào khác trên đối tượng của trình xem.

Nếu biết nhiều giá trị nhận dạng một cuốn sách – mã ISBN cho ấn bản bìa mềm hoặc số OCLC thay thế – bạn có thể truyền một loạt chuỗi giá trị nhận dạng dưới dạng tham số đầu tiên đến hàm load(). Người xem sẽ hiển thị sách nếu có bản xem trước có thể nhúng được liên kết với bất kỳ giá trị nhận dạng nào trong mảng.

Mã nhận dạng sách được hỗ trợ

Giống như tính năng Liên kết động, API Trình xem được nhúng hỗ trợ một số giá trị để xác định một cuốn sách cụ thể. Những quốc gia/khu vực này bao gồm:

ISBN
Số sách theo tiêu chuẩn quốc tế, gồm 10 hoặc 13 chữ số cho quảng cáo thương mại.
Ví dụ: ISBN:0738531367
Số OCLC
Số duy nhất do OCLC gán cho một cuốn sách khi bản ghi của cuốn sách đó được thêm vào hệ thống phân loại của WorldCat.
Ví dụ: OCLC:70850767
LCCN (Mã số sản phẩm thương mại toàn cầu)
Số kiểm soát của Thư viện Quốc hội do Thư viện Quốc hội chỉ định cho hồ sơ.
Ví dụ: LCCN:2006921508
Mã tập của Google Sách
Chuỗi riêng biệt mà Google Sách đã gán cho tập, xuất hiện trong URL tới cuốn sách trên Google Sách.
Ví dụ: Py8u3Obs4f4C
URL xem trước Google Sách
URL mở ra trang xem trước của sách trên Google Sách.
Ví dụ: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Các giá trị nhận dạng này thường được dùng với các API khác trong Nhóm API Google Sách. Ví dụ: Bạn có thể sử dụng Đường liên kết động để chỉ hiển thị nút xem trước nếu cuốn sách có thể nhúng được. Sau đó, khi người dùng nhấp vào nút đó, tạo thực thể cho người xem bằng cách sử dụng URL của bản xem trước mà lệnh gọi Đường liên kết động trả về. Tương tự, bạn có thể tạo ứng dụng duyệt qua và xem trước đa dạng bằng Books API (API Sách). API này trả về nhiều giá trị nhận dạng ngành phù hợp trong nguồn cấp dữ liệu Tập. Hãy truy cập vào trang ví dụ để xem qua một số cách triển khai nâng cao.

Xử lý quá trình khởi chạy không thành công

Trong một số trường hợp, lệnh gọi load có thể không thành công. Lỗi này thường xảy ra khi API không tìm thấy sách liên kết với giá trị nhận dạng được cung cấp, khi sách không có bản xem trước, không thể nhúng bản xem trước của sách hoặc khi các quy định hạn chế theo lãnh thổ ngăn người dùng cuối nhìn thấy cuốn sách cụ thể này. Bạn nên được cảnh báo về lỗi này để mã của bạn có thể xử lý điều kiện này một cách linh hoạt. Vì lý do này, hàm load cho phép bạn truyền một tham số thứ hai (không bắt buộc) là notFoundCallback. Tham số này cho biết hàm nào sẽ được gọi nếu không thể tải sách. Ví dụ: mã sau đây sẽ tạo hộp "thông báo" JavaScript nếu sách có thể được nhúng:

function alertNotFound() {
  alert("could not embed the book!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:1234', alertNotFound);
}

Xem ví dụ (book-notfound.html)

Khi sử dụng lệnh gọi lại này, bạn có thể quyết định hiển thị lỗi tương tự hoặc chọn ẩn hoàn toàn phần tử viewerCanvas. Thông số gọi lại không thành công là không bắt buộc và không được đưa vào ví dụ "Hello World".

Lưu ý: Vì một số cuốn sách và người dùng có thể chưa có bản xem trước, nên bạn cần biết liệu có bản xem trước hay không trước khi tải bản xem trước cho người xem. Ví dụ: bạn có thể chỉ muốn cho thấy nút, trang hoặc mục "Xem trước trên Google" trong giao diện người dùng nếu người dùng thực sự có thể xem trước. Bạn có thể thực hiện việc này bằng cách sử dụng Books API hoặc Đường liên kết động, cả hai đều báo cáo việc sách có thể nhúng bằng trình xem hay không.

Xử lý quá trình khởi chạy thành công

Bạn cũng có thể cần biết liệu một cuốn sách đã tải thành công hay chưa và khi nào. Vì lý do này, hàm load hỗ trợ tham số thứ ba (không bắt buộc) là successCallback. Tham số này sẽ được thực thi nếu và khi sách tải xong.

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);
}

Xem ví dụ (book-Thành công.html)

Lệnh gọi lại này có thể hữu ích, chẳng hạn như khi bạn chỉ muốn hiển thị một số thành phần nhất định trên trang nếu người xem đã hiển thị đầy đủ.

Hiển thị người xem khi tải

  google.books.setOnLoadCallback(initialize);

Trong khi trang HTML hiển thị, mô hình đối tượng tài liệu (DOM) sẽ được tạo, đồng thời mọi hình ảnh cũng như tập lệnh bên ngoài sẽ được nhận và kết hợp vào đối tượng document. Để đảm bảo trình xem của chúng ta chỉ được đặt trên trang sau khi trang đã tải đầy đủ, hàm google.books.setOnLoadCallback được dùng để trì hoãn việc thực thi hàm tạo đối tượng DefaultViewer. Vì setOnLoadCallback sẽ chỉ gọi initialize khi API Trình xem được nhúng được tải và sẵn sàng sử dụng, nên điều này giúp tránh hành vi khó đoán và đảm bảo kiểm soát cách thức và thời điểm trình xem được vẽ.

Lưu ý: Để tăng tối đa khả năng tương thích trên nhiều trình duyệt, bạn nên lên lịch tải trình xem bằng hàm google.books.setOnLoadCallback, thay vì sử dụng sự kiện onLoad trên thẻ <body>.

Tương tác với người xem

Giờ đây, khi đã có đối tượng DefaultViewer, bạn có thể tương tác với đối tượng đó. Đối tượng trình xem cơ bản có giao diện và hoạt động rất giống với trình xem mà bạn tương tác trên trang web Google Sách và đi kèm với rất nhiều hành vi tích hợp sẵn.

Tuy nhiên, bạn cũng có thể tương tác với người xem theo cách có lập trình. Đối tượng DefaultViewer hỗ trợ một số phương thức trực tiếp thay đổi trạng thái xem trước. Ví dụ: các phương thức zoomIn(), nextPage() và highlight() hoạt động trên trình xem theo cách lập trình, thay vì thông qua tương tác của người dùng.

Ví dụ sau đây thể hiện bản xem trước của cuốn sách tự động "chuyển" sang trang tiếp theo 3 giây một lần. Nếu trang tiếp theo nằm trong phần hiển thị của người xem, thì người xem sẽ di chuyển mượt mà đến trang; nếu không, người xem sẽ chuyển thẳng đến đầu trang tiếp theo.

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);

Xem ví dụ (book-animate.html)

Lưu ý rằng các lệnh gọi có lập trình tới trình xem sẽ không thực hiện được hoặc không có hiệu lực cho đến khi người xem được khởi chạy hoàn toàn với một cuốn sách cụ thể. Để đảm bảo bạn chỉ gọi các hàm như vậy khi trình xem đã sẵn sàng, hãy sử dụng tham số successCallback cho viewer.load theo mô tả ở trên.

Để biết thông tin về tất cả hàm mà đối tượng DefaultViewer hỗ trợ, hãy xem Hướng dẫn tham khảo.

Ghi chú lập trình

Trước khi bắt đầu tìm hiểu kỹ về Embedded Player API, bạn nên lưu ý những vấn đề sau để đảm bảo ứng dụng của bạn hoạt động trơn tru trên các nền tảng dự định.

Khả năng tương thích của trình duyệt

API Trình xem được nhúng hỗ trợ các phiên bản gần đây của Internet Explorer, Firefox và Safari, cũng như thường là các trình duyệt dựa trên Gecko và WebKit khác, chẳng hạn như Camino và Google Chrome.

Các ứng dụng khác nhau đôi khi yêu cầu các hành vi khác nhau cho người dùng có trình duyệt không tương thích. API Trình xem được nhúng không có bất kỳ hành vi tự động nào khi phát hiện thấy một trình duyệt không tương thích. Hầu hết ví dụ trong tài liệu này không kiểm tra khả năng tương thích của Trình duyệt và cũng không hiển thị thông báo lỗi cho các trình duyệt cũ. Các ứng dụng thực có thể hoạt động thân thiện hơn với các trình duyệt cũ hoặc không tương thích, nhưng các bước kiểm tra như vậy sẽ được bỏ qua để làm cho ví dụ dễ đọc hơn.

Các ứng dụng không quan trọng sẽ không tránh khỏi những điểm không thống nhất giữa các trình duyệt và nền tảng. Các trang web như quirksmode.org cũng là những tài nguyên hữu ích để tìm cách giải quyết.

Chế độ XHTML và quirks

Bạn nên sử dụng ngôn ngữ tương thích với tiêu chuẩn trên các trang có chứa trình xem. Khi các trình duyệt thấy DOCTYPE\" ở đầu trang, trình duyệt sẽ hiển thị trang ở "chế độ tuân thủ tiêu chuẩn". Điều này giúp bố cục và hành vi dễ dự đoán hơn trên các trình duyệt. Các trang không có định nghĩa đó có thể hiển thị ở "chế độ tương thích ngược", điều này có thể khiến bố cục không nhất quán.

<!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">

Lưu ý về các ví dụ về Embedded Users API (API Trình xem được nhúng)

Xin lưu ý rằng hầu hết ví dụ trong tài liệu này chỉ hiển thị mã JavaScript liên quan chứ không hiển thị tệp HTML đầy đủ. Bạn có thể cắm mã JavaScript vào tệp HTML skeleton của riêng mình hoặc bạn có thể tải xuống tệp HTML đầy đủ cho từng ví dụ bằng cách nhấp vào liên kết sau ví dụ.

Khắc phục sự cố

Nếu mã của bạn có vẻ như không hoạt động, thì sau đây là một số phương pháp có thể giúp bạn giải quyết vấn đề: