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 đã ngừng hoạt động trong Chrome 18 và sẽ ngừng hỗ trợ theo lịch hỗ trợ phiên bản tệp kê khai 1. Các thay đổi từ phiên bản 1 sang phiên bản 2 thuộc 2 danh mục chính: 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 tiện ích Chrome từ phiên bản tệp kê khai 1 sang phiên bản 2, tiếp theo là bả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.

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 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 phải là một chuỗi).
Bạn có đang dùng thuộc tính chrome.self không?
Thay thế bằng chrome.extension.
Bạn có đang 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 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 khối tập lệnh cùng dòng trong các trang HTML không?
Xoá mã JS có trong thẻ <script> và đặt mã này vào tệp JS bên ngoài.
Bạn có đang sử dụng trình xử lý sự kiện cùng dòng (như nhấp, v.v.) không?
Hãy xoá các thành phần này khỏi mã HTML, di chuyển chúng vào 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 những trang Web cần truy cập vào tài nguyên (như hình ảnh và tập lệnh) có trong gói 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à Chính sách bảo mật nội dung riêng cho các tài nguyên đó (không bắt buộc)).
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.
Mã hoặc thư viện của bạn có đang sử dụng eval(), Function(), innerHTML, setTimeout() mới hay chuyể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 một thư viện phù hợp 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 có 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 tải thư viện xuống và đóng gói trong tiện ích, 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 đối với API

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

Các thay đổi đối với thao tác của trình duyệt

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

Các thuộc tính browser_actions và chrome.browserActions đã được thay thế bằng các thuộc tính 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. Những thành phần này được thay thế bằng:
default_icon cho biểu tượng huy hiệu hành động của 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 của trình duyệt (và giờ đây, URL này phải là một chuỗi, không thể là một đối tượng)

Các thay đổi đối với thao tác trên trang

Tương tự như các thay đổi đối với các thao tác trên trình duyệt, API thao tác 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 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. Những tính năng 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à giờ đây phải là một chuỗi, không thể là một đối tượng)

Đã xoá và thay đổi API

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

Thuộc tính background_page đã được thay thế bằng background.
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.
Thay thế các API chrome.extension.getTabContentses() và chrome.extension.getExtensionTabs() bằng chrome.extension.getViews( { "type" : "tab" } ).

Tóm tắt về 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ừ phiên bản tệp kê khai 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õ hệ quả của chính sách.

Không cho phép tập lệnh cùng dòng và trình xử lý sự kiện

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

<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 tệp bên ngoài và tham chiếu những nội dung đó bằng thuộc tính src='path_to_file.js'.

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

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

Những thao tác này không hoạt động trong các tiện ích của nền tảng Manifest V2. Xoá các trình xử lý sự kiện cùng dòng, đặt các trình xử lý này vào tệp JS bên ngoài và sử dụng addEventListener() để đăng ký trình xử lý sự kiện cho chúng. Ví dụ: trong mã JS của bạn, hãy sử dụng:

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

Đây là cách gọn gàng hơn để phân tách hành vi của tiện ích khỏi mã đánh dấu giao diện người dùng của tiện ích.

Nhúng nội dung

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

Nội dung của phần mở rộng trên trang web: Nếu tiện ích của bạn nhúng các tài nguyên (như hình ảnh, tập lệnh, kiểu CSS, v.v.) được 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 sao cho 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ập lệnh và đối tượng cục bộ tải từ gói của bạn, qua đó ngă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, đôi khi 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ư mã jQuery hoặc Google Analytics. Có 2 cách để thực hiện việc này:

Tải thư viện có liên quan cục bộ xuống (như jQuery) và đóng gói thư viện đó với phần mở rộng của bạn.
Bạn có thể hạn chế CSP bằng cách đưa các nguồn gốc HTTPS vào danh sách cho phép trong mục "content_security_policy" của tệp kê khai. Để đưa một thư viện như Google Analytics vào, đây là phương pháp cần thực hiện:
```
{
  ...,
  "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ó thể một trong những thay đổi lớn nhất trong lược đồ mới cho manifest v2 là các tiện ích không còn có thể sử dụng các kỹ thuật đánh giá tập lệnh động như eval() hay Function() mới hoặc chuyển các 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 nhất định) đượ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 trên nguồn gốc riêng của trang đó, và các trang bị từ chối quyền truy cập vào Chrome.* API. Để sử dụng eval() và các nội dung tương tự theo Chính sách bảo mật nội dung mới:

Tạo một 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 cách truyền thông báo qua postMessage() để giao tiếp với trang hộp cát.

Để biết thêm 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ế để định hướng nhà phát triển xây dựng các tiện ích và ứng dụng an toàn và mạnh mẽ hơn. Để xem danh sách đầy đủ các thay đổi từ tệp kê khai phiên bản 1 sang 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 nhằm tách biệt mã không an toàn, hãy đọc bài viết eval hộp cát. 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 của chúng tôi và đoạn giới thiệu hay về HTML5Rocks.