Trang này được dịch bởi Cloud Translation API.

Hướng dẫn: Di chuyển sang Manifest V2

Tệp kê khai phiên bản 1 không còn được dùng trong Chrome 18 và dịch vụ hỗ trợ sẽ ngừng hoạt động theo lịch hỗ trợ tệp kê khai phiên bản 1. Các thay đổi từ phiên bản 1 đến phiên bản 2 thuộc hai danh mục lớn: Thay đổi về API và Thay đổi về bảo mật.

Tài liệu này cung cấp danh sách kiểm tra để di chuyển các tiện ích Chrome của bạn từ tệp kê khai phiên bản 1 sang phiên bản 2, theo sau là phần tóm tắt chi tiết hơn về ý nghĩa của những thay đổi này và lý do thực hiện các thay đổi đó.

Danh sách kiểm tra các thay đổi về API

Bạn đang sử dụng thuộc tính browser_actions hay API chrome.browserActions?
Thay thế browser_actions bằng thuộc tính browser_action số ít.
Thay thế chrome.browserActions với chrome.browserAction.
Thay thế thuộc tính icons bằng default_icon.
Thay thế thuộc tính name bằng default_title.
Thay thế thuộc tính popup bằng default_popup (và thuộc tính này hiện phải là một chuỗi).
Bạn đang sử dụng thuộc tính page_actions hay API chrome.pageActions?
Thay thế page_actions với page_action.
Thay thế chrome.pageActions với chrome.pageAction.
Thay thế thuộc tính icons bằng default_icon.
Thay thế thuộc tính name bằng default_title.
Thay thế thuộc tính popup bằng default_popup (và thuộc tính này hiện phải là một chuỗi).
Bạn có đang sử dụng thuộc tính chrome.self không?
Thay thế bằng chrome.extension.
Bạn có đang sử dụng thuộc tính Port.tab không?
Thay thế bằng Port.sender.
Bạn đang sử dụng API chrome.extension.getTabContentses() hay chrome.extension.getExtensionTabs()?
Thay thế bằng chrome.extension.getViews( { "type" : "tab" } ).
Tiện ích của bạn có sử dụng trang nền không?
Thay thế thuộc tính background_page bằng thuộc tính background.
Thêm thuộc tính scripts hoặc page chứa mã cho trang.
Thêm một thuộc tính persistent và đặt thuộc tính đó thành false để chuyển đổi trang nền thành trang sự kiện

Danh sách kiểm tra các thay đổi về bảo mật

Bạn có đang sử dụng các khối tập lệnh nội tuyến trong trang HTML không?
Xoá mã JS có trong thẻ <script> và đặt mã đó vào một tệp JS bên ngoài.
Bạn có đang sử dụng trình xử lý sự kiện nội tuyến (như onclick, v.v.) không?
Xoá các tệp đó khỏi mã HTML, di chuyển các tệp đó vào một tệp JS bên ngoài và sử dụng addEventListener().
Tiện ích của bạn có chèn tập lệnh nội dung vào các trang web cần truy cập vào tài nguyên (chẳng hạn như hình ảnh và tập lệnh) có trong gói của tiện ích không?
Xác định thuộc tính web_accessible_resources và liệt kê các tài nguyên (và một Chính sách bảo mật nội dung riêng biệt cho các tài nguyên đó nếu muốn).
Tiện ích của bạn có nhúng các trang web bên ngoài không?
Xác định thuộc tính sandbox (hộp cát).
Mã hoặc thư viện của bạn có sử dụng eval(), Function() mới, innerHTML, setTimeout() hay truyền các chuỗi mã JS được đánh giá động không?
Sử dụng JSON.parse() nếu bạn đang phân tích cú pháp mã JSON thành một đối tượng.
Sử dụng thư viện thân thiện với CSP, ví dụ: AngularJS.
Tạo một mục nhập hộp cát trong tệp kê khai và chạy mã bị ảnh hưởng trong hộp cát, sử dụng postMessage() để giao tiếp với trang hộp cát.
Bạn có đang tải mã bên ngoài, chẳng hạn như jQuery hoặc Google Analytics không?
Hãy cân nhắc việc tải thư viện xuống và đóng gói thư viện đó trong tiện ích của bạn, sau đó tải thư viện đó từ gói cục bộ.
Đưa miền HTTPS phân phát tài nguyên vào danh sách cho phép trong phần "content_security_policy" của tệp kê khai.

Tóm tắt các thay đổi về API

Tệp kê khai phiên bản 2 giới thiệu một số thay đổi đối với API hành động trên trình duyệt và API hành động trên trang, đồng thời thay thế một số API cũ bằng các API mới hơn.

Thay đổi đối với thao tác trên trình duyệt

API thao tác trên trình duyệt có một số thay đổi về cách đặt tên:

Các thuộc tính browser_actions và chrome.browserActions đã được thay thế bằng các thuộc tính tương ứng số ít browser_action và chrome.browserAction.
Trong thuộc tính browser_actions cũ, có các thuộc tính icons, name và popup. Các phương thức này đã được thay thế bằng:
default_icon cho biểu tượng huy hiệu thao tác trên trình duyệt
default_name cho văn bản xuất hiện trong chú giải công cụ khi bạn di chuột qua huy hiệu
default_popup cho trang HTML đại diện cho giao diện người dùng cho thao tác trong trình duyệt (và giờ đây, giá trị này phải là một chuỗi, không được là một đối tượng)

Thay đổi đối với hành động trên trang

Tương tự như các thay đổi đối với hành động trong trình duyệt, API hành động trên trang cũng đã thay đổi:

Các thuộc tính page_actions và chrome.pageActions đã được thay thế bằng các thuộc tính tương ứng số ít page_action và chrome.pageAction.
Trong thuộc tính page_actions cũ, có các thuộc tính icons, name và popup. Các hàm này đã được thay thế bằng:
default_icon cho biểu tượng huy hiệu hành động trên trang
default_name cho văn bản xuất hiện trong chú giải công cụ khi bạn di chuột qua huy hiệu
default_popup cho trang HTML đại diện cho giao diện người dùng cho thao tác trên trang (và hiện tại, đây phải là một chuỗi, không được là một đối tượng)

Xoá và thay đổi API

Một số API tiện ích đã bị xoá và thay thế bằng các API tương đương mới:

Thuộc tính background_page đã được thay thế bằng nền.
Thuộc tính chrome.self đã bị xoá, hãy sử dụng chrome.extension.
Thuộc tính Port.tab đã được thay thế bằng Port.sender.
API chrome.extension.getTabContentses() và chrome.extension.getExtensionTabs() đã được thay thế bằng chrome.extension.getViews( { "type" : "tab" } ).

Tóm tắt các thay đổi về bảo mật

Có một số thay đổi liên quan đến bảo mật đi kèm với việc chuyển từ tệp kê khai phiên bản 1 sang phiên bản 2. Nhiều thay đổi trong số này bắt nguồn từ việc Chrome áp dụng Chính sách bảo mật nội dung; bạn nên đọc thêm về chính sách này để hiểu rõ các tác động của chính sách này.

Không cho phép tập lệnh nội tuyến và trình xử lý sự kiện

Do việc sử dụng Chính sách bảo mật nội dung, bạn không thể sử dụng thẻ <script> cùng dòng với nội dung HTML được nữa. Bạn phải di chuyển các tệp này sang tệp JS bên ngoài. Ngoài ra, trình xử lý sự kiện nội tuyến cũng không được hỗ trợ. Ví dụ: giả sử bạn có mã sau trong tiện ích:

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

Mã này sẽ gây ra lỗi trong thời gian chạy. Để khắc phục vấn đề này, hãy di chuyển nội dung thẻ <script> sang các tệp bên ngoài và tham chiếu các tệp đó bằng thuộc tính src='path_to_file.js'.

Tương tự, trình xử lý sự kiện nội tuyến (một tính năng phổ biến và tiện lợi mà nhiều nhà phát triển Web sử dụng) sẽ không thực thi. Ví dụ: hãy xem xét các trường hợp phổ biến như:

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

Các tiện ích này sẽ không hoạt động trong tiện ích của tệp kê khai phiên bản 2. Xoá trình xử lý sự kiện nội tuyến, đặt các trình xử lý sự kiện đó vào tệp JS bên ngoài và sử dụng addEventListener() để đăng ký trình xử lý sự kiện cho các trình xử lý sự kiện đó. Ví dụ: trong mã JS, hãy sử dụng:

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

Đây là cách tách biệt hành vi của tiện ích với mã đánh dấu giao diện người dùng rõ ràng hơn nhiều.

Nhúng nội dung

Trong một số trường hợp, tiện ích của bạn có thể nhúng nội dung có thể sử dụng bên ngoài hoặc đến từ một nguồn bên ngoài.

Nội dung tiện ích trong trang web: Nếu tiện ích của bạn nhúng các tài nguyên (chẳng hạn như hình ảnh, tập lệnh, kiểu CSS, v.v.) được sử dụng trong tập lệnh nội dung được chèn vào trang web, thì bạn cần sử dụng thuộc tính web_accessible_resources để đưa các tài nguyên này vào danh sách cho phép để các trang web bên ngoài có thể sử dụng:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

Nhúng nội dung bên ngoài: Chính sách bảo mật nội dung chỉ cho phép tải tập lệnh và đối tượng cục bộ từ gói của bạn, giúp ngăn chặn kẻ tấn công bên ngoài đưa mã không xác định vào tiện ích của bạn. Tuy nhiên, có trường hợp bạn muốn tải các tài nguyên được phân phát bên ngoài, chẳng hạn như jQuery hoặc mã Google Analytics. Có hai cách để thực hiện điều này:

Tải thư viện có liên quan xuống máy (như jQuery) và đóng gói thư viện đó bằng tiện ích của bạn.
Bạn có thể nới lỏng CSP theo cách hạn chế bằng cách đưa các nguồn gốc HTTPS vào danh sách cho phép trong phần "content_security_policy" của tệp kê khai. Để đưa một thư viện như Google Analytics vào, bạn có thể làm như sau:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Sử dụng tính năng đánh giá tập lệnh động

Có lẽ một trong những thay đổi lớn nhất trong lược đồ tệp kê khai v2 mới là các tiện ích không thể sử dụng các kỹ thuật đánh giá tập lệnh động như eval() hoặc Function() mới, hoặc truyền chuỗi mã JS đến các hàm sẽ khiến eval() được sử dụng, chẳng hạn như setTimeout(). Ngoài ra, một số thư viện JavaScript thường dùng, chẳng hạn như Google Maps và một số thư viện tạo mẫu, được biết là sử dụng một số kỹ thuật này.

Chrome cung cấp một hộp cát để các trang chạy trong nguồn gốc của riêng chúng. Các trang này bị từ chối quyền truy cập vào Chrome.* API. Để sử dụng eval() và các tính năng tương tự theo Chính sách bảo mật nội dung mới:

Tạo mục nhập hộp cát trong tệp kê khai.
Trong mục nhập hộp cát, hãy liệt kê các trang bạn muốn chạy trong hộp cát.
Sử dụng tính năng truyền tin qua postMessage() để giao tiếp với trang trong hộp cát.

Để biết thêm thông tin chi tiết về cách thực hiện việc này, hãy xem tài liệu về Sandboxing Eval.

Tài liệu đọc thêm

Những thay đổi trong tệp kê khai phiên bản 2 được thiết kế để hướng dẫn nhà phát triển xây dựng các tiện ích và ứng dụng có cấu trúc mạnh mẽ và an toàn hơn. Để xem danh sách đầy đủ các thay đổi từ tệp kê khai phiên bản 1 đến phiên bản 2, hãy xem tài liệu về tệp kê khai. Để biết thêm thông tin về cách sử dụng hộp cát để tách biệt mã không an toàn, hãy đọc bài viết sandboxing eval. Bạn có thể tìm hiểu thêm về Chính sách bảo mật nội dung bằng cách truy cập vào hướng dẫn liên quan đến tiện ích và hướng dẫn hữu ích về HTML5Rocks.