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 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 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 xây dựng dựa trên API Trình xem được nhúng, giúp bạn dễ dàng thêm các tính năng xem trước vào trang web của mình chỉ bằng cách sao chép một vài dòng mã. Tài liệu này dành cho các nhà phát triển nâng cao 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 quen thuộc với lập trình JavaScript và các khái niệm lập trình hướng đối tượng. Bạn cũng phải nắm rõ Google Sách từ góc độ người dùng. Có nhiều hướng dẫn về JavaScript trên Web.

Tài liệu khái niệm này chưa đầy đủ và toàn diện; 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 API Trình xem được nhúng. Người dùng nâng cao có thể quan tâm đến Tài liệu tham khảo 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 nên bắt đầu bằng Trình hướng dẫn xem trước. Trình hướng dẫn này sẽ tự động tạo mã cần thiết để nhúng bản xem trước cơ bản trên 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ề API Trình xem được nhúng là xem một ví dụ đơn giản. Trang web sau đây hiển thị bản xem trước 600x500 của cuốn Mountain View, do Nicholas Perry viết, ISBN 0738531367 (thuộc bộ sách "Hình ảnh nước Mỹ" của 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>

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, bạn cũng cần lưu ý 5 điều sau:

  1. Chúng ta đư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 "viewer" (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 sử dụng google.books.setOnLoadCallback để gọi initialize khi API đã tải xong.

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. Thê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 nhận 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ư được 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, Embedded Viewer API sử dụng tiếng Anh khi hiển thị thông tin văn bản, chẳng hạn như chú giải công cụ, tên của các chế độ điều khiển và văn bản đườ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 một 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)

Các 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, lt, ms, no, pl, pt-BR, pt-PT, ro, ru, sr, sk, sl, es, sv, tl, th, tr, uk và vi.

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. Việc 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.

Các 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, bạn phải đặt trước vị trí cho cuốn sách đó. Thông thường, việc này được thực hiện bằng cách tạo một phần tử div được đặt tên và lấy 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 được tạo bằng toán tử new của JavaScript.

Khi tạo một thực thể 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à phần tử con của đối tượng document JavaScript và chúng ta lấy 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à gán biến đó cho một đối tượng DefaultViewer mới. Hàm DefaultViewer() được gọi là constructor và định nghĩa của hàm này (được tóm tắt để rõ ràng từ Tài liệu tham khảo API Trình xem được nhúng) như sau:

Hàm dựng Mô tả
DefaultViewer(container, opts?) Tạo một trình xem mới bên trong container HTML đã cho. Đây phải là một 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 không bắt buộc.

Xin lưu ý rằng tham số thứ hai trong hàm khởi tạo là không bắt buộc – dành cho các phương thức triển khai nâng cao nằm ngoài phạm vi của tài liệu này – và tham số này bị bỏ qua trong ví dụ "Xin chào thế giới".

Khởi chạy trình xem bằng một cuốn sách cụ thể

  viewer.load('ISBN:0738531367');

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

Nếu biết nhiều giá trị nhận dạng cho một cuốn sách (ví dụ: ISBN cho ấn bản sách bìa mềm hoặc số OCLC thay thế), bạn có thể truyền một mảng chuỗi giá trị nhận dạng làm tham số đầu tiên cho 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.

Các 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ể. bao gồm:

ISBN
Mã số tiêu chuẩn quốc tế cho sách thương mại gồm 10 hoặc 13 chữ số duy nhất.
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
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 bản ghi.
Ví dụ: LCCN:2006921508
Mã tập của Google Sách
Chuỗi duy nhất mà Google Sách đã chỉ định cho tập sách. Chuỗi này xuất hiện trong URL của cuốn sách trên Google Sách.
Ví dụ: Py8u3Obs4f4C
URL xem trước trên Google Sách
URL mở trang xem trước 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 để hiển thị nút xem trước chỉ khi sách có thể nhúng được. Sau đó, khi người dùng nhấp vào nút này, hãy tạo bản sao của trình xem bằng cách sử dụng URL xem trước do lệnh gọi Đường liên kết động trả về. Tương tự, bạn có thể tạo một ứng dụng duyệt xem và xem trước phong phú bằng API Sách. API này sẽ trả về một số giá trị nhận dạng phù hợp trong ngành trong nguồn cấp dữ liệu Tập sách. Truy cập vào trang ví dụ để xem một số cách triển khai nâng cao.

Xử lý các lần 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 không có bản xem trước của sách, không thể nhúng bản xem trước của sách hoặc khi các quy tắc 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 như vậ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, notFoundCallback, cho biết hàm nào sẽ được gọi nếu không tải được sách. Ví dụ: mã sau đây sẽ tạo hộp "cảnh 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ị một lỗi tương tự hoặc chọn ẩn hoàn toàn phần tử viewerCanvas. Tham số gọi lại khi gặp lỗi là không bắt buộc và không có trong ví dụ "Xin chào thế giới".

Lưu ý: Vì không phải sách nào cũng có bản xem trước và không phải người dùng nào cũng có thể xem trước, nên bạn nên biết liệu có bản xem trước hay không trước khi tải trình xem cho sách đó. Ví dụ: bạn chỉ nên hiển thị 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ợ một 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 một cuốn 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-Success.html)

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

Hiển thị trình xem khi tải

  google.books.setOnLoadCallback(initialize);

Trong khi một 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 và tập lệnh bên ngoài sẽ được nhận và tích hợp vào đối tượng document. Để đảm bảo rằng trình xem của chúng ta chỉ được đặt trên trang sau khi trang tải xong, 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 đã tải và sẵn sàng để sử dụng, nên điều này giúp tránh hành vi không thể dự đoán và đảm bảo kiểm soát cách thức cũng như thời điểm vẽ trình xem.

Lưu ý: Để tối đa hoá 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>.

Số lượt tương tác của người xem

Bây giờ, bạn đã có một đố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 giống như trình xem mà bạn tương tác trên trang web Google Sách, đồng thời có 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 phương thức 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 phương thức lập trình, thay vì thông qua hoạt động tương tác của người dùng.

Ví dụ sau đây hiển thị bản xem trước sách tự động "chuyển" sang trang tiếp theo sau mỗi 3 giây. Nếu trang tiếp theo nằm trong phần hiển thị của trình xem, thì trình xem sẽ di chuyển mượt mà đến trang đó; nếu không, trình 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)

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

Để biết thông tin về tất cả cá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 API Trình xem được nhúng, bạn nên lưu ý những vấn đề sau để đảm bảo ứng dụng của mình hoạt động trơn tru trên các nền tảng dự kiến.

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 mới đây của Internet Explorer, Firefox và Safari, cũng như thường là các trình duyệt khác dựa trên Gecko và WebKit như Camino và Google Chrome.

Đôi khi, các ứng dụng khác nhau yêu cầu hành vi khác nhau đối với 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 các ví dụ trong tài liệu này không kiểm tra khả năng tương thích với Trình duyệt cũng như 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 tế có thể làm một số việc 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ẽ bị bỏ qua để các ví dụ dễ đọc hơn.

Các ứng dụng không quan trọng chắc chắn sẽ gặp phải sự không nhất quán giữa 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 giải pháp.

XHTML và chế độ tương thích ngược

Bạn nên sử dụng XHTML tuân thủ các tiêu chuẩn trên các trang chứa trình xem. Khi thấy DOCTYPE XHTML ở đầu trang, trình duyệt sẽ hiển thị trang ở "chế độ tuân thủ tiêu chuẩn", giúp dự đoán bố cục và hành vi trên các trình duyệt dễ dàng hơn nhiều. 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ề API Trình xem được nhúng

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

Khắc phục sự cố

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