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 trực tiếp nội dung sách từ Google Sách vào các trang web của bạn bằng JavaScript. API 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à công cụ được xây dựng dựa trên API trình xem được nhúng, giúp dễ dàng thêm các khả năng xem trước vào trang web của bạn bằng cách chỉ sao chép một vài dòng mã. Tài liệu này dành cho những nhà phát triển nâng cao muốn tùy chỉnh cách người 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 đã quen thuộc với Google Sách từ góc nhìn của 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à đầy đủ; tài liệu đượ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 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, những người mới bắt đầu có thể muốn bắt đầu với 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 các bản xem trước cơ bản trên trang web của bạn.

"Hello, World" của API Trình xem 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 cho thấy bản xem trước 600x500 của Mountain View của Nicholas Perry, ISBN 0738531367 (một phần trong chuỗi "Image of America" 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 rồi tải xuống để chỉnh sửa và thử nghiệm. Ngay cả trong ví dụ đơn giản này, có 5 điều cần lưu ý:

  1. Chúng tôi bao gồm Trình tải API bằng cách sử dụng thẻ script.
  2. Chúng ta tạo một phần tử div có tên là "viewerCanvas" để lưu giữ trình xem.
  3. Chúng ta viết hàm JavaScript để tạo đối tượng "người xem".
  4. Chúng tôi tải sách bằng mã 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 đầ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 thông số danh sách không bắt buộc chỉ định chức năng hoặc ngôn ngữ gọi lại, như giải thích bên dưới. 
    <script type="text/javascript">
  google.books.load();
</script>

Tải phiên bản đã bản địa hoá của API Trình xem nhúng

Theo mặc định, API trình xem được nhúng sử dụng tiếng Anh khi hiển thị thông tin dạng văn bản như chú giải công cụ, tên chế độ điều khiển và văn bản liên kết. Nếu muốn thay đổi API Trình xem 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 với 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)

Hiện tại, các mã ngôn ngữ RFC 3066 được hỗ trợ

Khi sử dụng API Trình xem được nhúng trong các ngôn ngữ không phải là 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. Thực hiện việc này giúp đảm bảo các ký tự hiển thị chính xác trên tất cả các trình duyệt. Để biết thêm thông tin, hãy xem trang về W3C về cách đặ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 vị trí 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 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 của trình duyệt (DOM).

Ví dụ ở trên xác định một div có tên là "viewerCanvas" và đặt kích thước 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 để tự đị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 duy nhất trên trang là lớp DefaultViewer. (Bạn có thể tạo nhiều bản sao của lớp này – mỗi đối tượng sẽ xác định một trình xem riêng biệt 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 phiên bản mới của trình xem, bạn sẽ 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 của JavaScript và chúng tôi 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à một hàm dựng và định nghĩa của hàm này (được rút gọn để đảm bảo sự rõ ràng trong Tài liệu tham khảo API trình xem được nhúng) được thể hiện dưới đây:

Hàm dựng Mô tả
DefaultViewer(vùng chứa, chọn tham gia?) Tạo trình xem mới bên trong HTML đã cho, container 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 chuyển bằng cách sử dụng tham số opts không bắt buộc.

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 hoạt động 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".

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ể. Quá trình khởi động 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 giá trị identifier để cho API biết cuốn sách nào cần hiển thị. Phương thức này phải được gửi trước khi bất kỳ hoạt động nào khác được thực hiện trên đối tượng người xem.

Nếu biết nhiều giá trị nhận dạng cho một cuốn sách (mã ISBN của ấn bản bìa mềm hoặc số OCLC thay thế), 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 vào 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.

Giá trị 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ể. Trong đó có:

ISBN
Số điện thoại thương mại tiêu chuẩn quốc tế gồm 10 hoặc 13 chữ số Số sách chuẩn quốc tế.
Ví dụ: ISBN:0738531367
Số OCLC
Số duy nhất do OCLC chỉ định cho sách khi bản ghi của cuốn sách đó được thêm vào hệ thống danh mục của WorldCat.
Ví dụ: OCLC:70850767
của LCCN
Số kiểm soát của Thư viện Quốc hội do Thư viện Quốc hội giao cho.
Ví dụ: LCCN:2006921508
Mã tập của Google Sách
Chuỗi duy nhất mà Google Sách đã gán cho tập đó. 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ở ra một 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 dùng với các API khác trong nhóm API của 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, hãy tạo bản sao cho người xem bằng URL xem trước do lệnh gọi Đường liên kết động trả về. Tương tự như vậy, bạn có thể xây dựng một ứng dụng đa dạng duyệt qua và xem trước bằng API Sách. Ứng dụng 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. Truy cập trang mẫu để xem trước một số cách triển khai nâng cao.

Xử lý thao tác 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ực hiện được. Điều này thường xảy ra khi API không thể tìm thấy sách được 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, khi không thể nhúng bản xem trước sách hoặc khi các hạn chế về 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ả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, notFoundCallback. Tham số này cho biết hàm nào cần được gọi nếu không thể tải sách. Ví dụ: mã sau 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 lỗi tương tự hoặc ẩn hoàn toàn phần tử viewerCanvas. Thông số gọi lại lỗi không bắt buộc và không được đưa vào ví dụ "Hello World".

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

Xử lý việc khởi chạy thành công

Bạn cũng nên biết liệu thời điểm và khi sách có tải thành công hay không. Vì lý do này, hàm load hỗ trợ tham số thứ ba không bắt buộc, 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 chẳng hạn trong trường hợp 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ị trình 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 xây dựng, đồ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 trình xem của chúng tôi chỉ được đặt trên trang sau khi trang đã tải đầy đủ, hàm google.books.setOnLoadCallback sẽ đượ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 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 người xem 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 cho người 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

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 người xem cơ bản có giao diện và hoạt động rất giống với người xem mà bạn tương tác trên trang web của Google Sách cũng như có 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 phương thức lập trình. Đối tượng DefaultViewer hỗ trợ một số phương thức thay đổi trực tiếp trạng thái xem trước. Ví dụ: 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 tương tác của người dùng.

Ví dụ sau đây cho thấy bản xem trước 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à tới 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 đến người 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 đủ 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 như mô tả ở trên.

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

Ghi chú về việc lập trình

Trước khi bắt đầu đi sâu vào 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 mong muốn.

Khả năng tương thích với 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—và thường là các trình duyệt dựa trên Gecko-và Thao tác khác như Camino và Google Chrome.

Các ứng dụng khác nhau đôi khi yêu cầu những 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ó hành vi tự động nào khi phát hiện 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 tính tương thích của Trình duyệt, cũng như không hiển thị thông báo lỗi cho trình duyệt cũ hơn. Các ứng dụng thực tế có thể làm điều gì đó 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 thể tránh được sự không nhất quán giữa các trình duyệt và nền tảng. Các trang web như quirksmode.org cũng là tài nguyên hữu ích để tìm cách giải quyết.

XHTML và chế độ giật

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

Xin lưu ý rằng hầu hết ví dụ trong tài liệu này chỉ đưa ra mã JavaScript phù hợp, không phải 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 tệp HTML đầy đủ xuống cho mỗi ví dụ bằng cách nhấp vào đường liên kết sau ví dụ này.

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 đề: