Thêm tệp kê khai ứng dụng web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Tệp kê khai ứng dụng web là một tệp JSON cho trình duyệt biết cách ứng dụng web tiến bộ (PWA) của bạn hoạt động khi được cài đặt trên máy tính hoặc thiết bị di động của người dùng. Tối thiểu, tệp kê khai thông thường bao gồm:

• Tên của ứng dụng
• Các biểu tượng mà ứng dụng nên dùng
• URL sẽ mở khi ứng dụng khởi chạy

Tạo tệp kê khai

Tệp kê khai có thể có tên bất kỳ, nhưng thường được đặt tên là manifest.json và được phân phát từ thư mục gốc (thư mục cấp cao nhất của trang web). Thông số kỹ thuật đề xuất rằng tiện ích phải là .webmanifest, nhưng bạn nên sử dụng tệp JSON để tệp kê khai của mình dễ đọc hơn.

Tệp kê khai thông thường có dạng như sau:

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's the weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's the weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

Các thuộc tính chính của tệp kê khai

short_name và name

Bạn phải cung cấp ít nhất một trong hai giá trị short_name hoặc name trong tệp kê khai. Nếu bạn cung cấp cả hai, name sẽ được dùng khi ứng dụng được cài đặt và short_name sẽ được dùng trên màn hình chính, trình chạy hoặc các vị trí khác có không gian hạn chế của người dùng.

icons

Khi người dùng cài đặt PWA, bạn có thể xác định một bộ biểu tượng để trình duyệt sử dụng trên màn hình chính, trình chạy ứng dụng, trình chuyển đổi tác vụ, màn hình chờ và ở các vị trí khác.

Thuộc tính icons là một mảng các đối tượng hình ảnh. Mỗi đối tượng phải bao gồm src, thuộc tính sizes và type của hình ảnh. Để sử dụng biểu tượng có thể che mắt, đôi khi được gọi là biểu tượng thích ứng trên Android, hãy thêm "purpose": "any maskable" vào thuộc tính icon.

Đối với Chromium, bạn phải cung cấp biểu tượng tối thiểu có kích thước 192x192 pixel và biểu tượng 512x512 pixel. Nếu chỉ cung cấp hai kích thước biểu tượng đó, Chrome sẽ tự động điều chỉnh tỷ lệ các biểu tượng cho vừa với thiết bị. Nếu bạn muốn điều chỉnh tỷ lệ biểu tượng của riêng mình để đạt được độ hoàn hảo về điểm ảnh, hãy cung cấp biểu tượng theo gia số 48 dp.

id

Thuộc tính id cho phép bạn xác định rõ giá trị nhận dạng được dùng cho ứng dụng. Việc thêm thuộc tính id vào tệp kê khai sẽ xoá phần phụ thuộc trên start_url hoặc vị trí của tệp kê khai, đồng thời cho phép cập nhật các phần phụ thuộc đó trong tương lai. Để biết thêm thông tin, hãy xem phần Nhận dạng duy nhất PWA bằng thuộc tính mã tệp kê khai ứng dụng web.

start_url

start_url là thuộc tính bắt buộc. Tệp này cho trình duyệt biết ứng dụng của bạn sẽ bắt đầu ở đâu khi khởi chạy và ngăn ứng dụng bắt đầu trên bất kỳ trang nào mà người dùng đang truy cập khi thêm ứng dụng của bạn vào màn hình chính.

start_url phải chuyển hướng người dùng đến thẳng ứng dụng của bạn, chứ không phải trang đích của sản phẩm. Hãy suy nghĩ về những việc người dùng sẽ muốn làm ngay sau khi mở ứng dụng của bạn và đặt chúng ở đó.

background_color

Thuộc tính background_color được sử dụng trên màn hình chờ khi ứng dụng khởi chạy trên thiết bị di động lần đầu tiên.

display

Bạn có thể tuỳ chỉnh giao diện người dùng trình duyệt hiển thị khi ứng dụng của bạn khởi chạy. Ví dụ: bạn có thể ẩn các phần tử giao diện người dùng của trình duyệt và thanh địa chỉ. Bạn thậm chí có thể tạo trò chơi để chạy ở chế độ toàn màn hình. Thuộc tính display nhận một trong các giá trị sau:

Thuộc tính	Hành vi
fullscreen	Mở ứng dụng web mà không có giao diện người dùng trình duyệt và chiếm toàn bộ khu vực hiển thị có sẵn.
standalone	Mở ứng dụng web để có giao diện như một ứng dụng độc lập. Ứng dụng này chạy trong một cửa sổ riêng, tách biệt với trình duyệt và ẩn các thành phần trên giao diện người dùng tiêu chuẩn của trình duyệt (chẳng hạn như thanh địa chỉ).
minimal-ui	Chế độ này tương tự như standalone nhưng cung cấp cho người dùng tập hợp tối thiểu các thành phần trên giao diện người dùng để điều khiển hoạt động điều hướng, chẳng hạn như nút quay lại và nút tải lại.
browser	Trải nghiệm trình duyệt tiêu chuẩn.

display_override

Để chọn cách hiển thị ứng dụng web, hãy đặt chế độ display trong tệp kê khai của ứng dụng như đã giải thích ở trên. Trình duyệt không bắt buộc phải hỗ trợ tất cả chế độ hiển thị, nhưng phải hỗ trợ chuỗi dự phòng được xác định theo thông số kỹ thuật ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Nếu không hỗ trợ một chế độ nhất định, trình duyệt sẽ quay lại chế độ hiển thị tiếp theo trong chuỗi. Trong một số ít trường hợp, các phương án dự phòng này có thể gây ra sự cố. Ví dụ: nhà phát triển không thể yêu cầu "minimal-ui" mà không bị buộc quay lại chế độ hiển thị "browser" khi "minimal-ui" không được hỗ trợ. Hành vi hiện tại cũng khiến bạn không thể giới thiệu các chế độ hiển thị mới theo cách tương thích ngược, vì các chế độ này không có vị trí trong chuỗi dự phòng.

Bạn có thể đặt trình tự dự phòng của riêng mình bằng cách sử dụng thuộc tính display_override mà trình duyệt sẽ xem xét trước thuộc tính display. Giá trị của lớp này là một trình tự các chuỗi được xem xét theo thứ tự trong danh sách, và áp dụng chế độ hiển thị được hỗ trợ đầu tiên. Nếu không có phương pháp nào được hỗ trợ, trình duyệt sẽ quay lại đánh giá trường display. Nếu không có trường display, trình duyệt sẽ bỏ qua display_override.

Sau đây là ví dụ về cách sử dụng display_override. Thông tin chi tiết về "window-control-overlay" nằm ngoài phạm vi của trang này.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Khi tải ứng dụng này, trình duyệt sẽ cố gắng sử dụng "window-control-overlay" trước. Nếu không có, thuộc tính này sẽ quay lại "minimal-ui", sau đó quay lại "standalone" từ thuộc tính display. Nếu không có phương thức nào trong số này, trình duyệt sẽ quay lại chuỗi dự phòng tiêu chuẩn.

scope

scope của ứng dụng là tập hợp các URL mà trình duyệt coi là một phần của ứng dụng. scope kiểm soát cấu trúc URL bao gồm tất cả các điểm truy cập và thoát vào ứng dụng, đồng thời trình duyệt sử dụng cấu trúc này để xác định thời điểm người dùng rời khỏi ứng dụng.

Một số lưu ý khác về scope:

• Nếu bạn không đưa scope vào tệp kê khai, thì scope ngụ ý mặc định sẽ là URL bắt đầu, nhưng đã xoá tên tệp, truy vấn và mảnh.
• Thuộc tính scope có thể là một đường dẫn tương đối (../) hoặc bất kỳ đường dẫn cấp cao hơn nào (/) cho phép tăng phạm vi điều hướng trong ứng dụng web.
• start_url phải nằm trong phạm vi.
• start_url tương ứng với đường dẫn được xác định trong thuộc tính scope.
• start_url bắt đầu bằng / sẽ luôn là gốc của nguồn gốc.

theme_color

theme_color đặt màu của thanh công cụ và có thể được phản ánh trong bản xem trước của ứng dụng trong trình chuyển đổi tác vụ. theme_color phải khớp với màu giao diện meta được chỉ định trong phần đầu tài liệu.

theme_color trong truy vấn nội dung đa phương tiện

Bạn có thể điều chỉnh theme_color trong truy vấn nội dung nghe nhìn bằng thuộc tính media của phần tử màu giao diện meta. Ví dụ: bạn có thể xác định một màu cho chế độ sáng và một màu khác cho chế độ tối theo cách này. Tuy nhiên, bạn không thể xác định các tuỳ chọn ưu tiên này trong tệp kê khai. Để biết thêm thông tin, hãy xem vấn đề về w3c/manifest#975 trên GitHub.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

Thuộc tính shortcuts là một mảng các đối tượng lối tắt ứng dụng giúp truy cập nhanh vào các tác vụ chính trong ứng dụng. Mỗi thành phần là một từ điển chứa ít nhất một name và một url.

description

Thuộc tính description mô tả mục đích của ứng dụng.

Trong Chrome, độ dài mô tả tối đa là 300 ký tự trên tất cả các nền tảng. Nếu nội dung mô tả dài hơn, trình duyệt sẽ cắt bớt nội dung đó bằng dấu ba chấm. Trên Android, nội dung mô tả cũng phải sử dụng tối đa 7 dòng văn bản.

screenshots

Thuộc tính screenshots là một mảng các đối tượng hình ảnh đại diện cho ứng dụng của bạn trong các trường hợp sử dụng phổ biến. Mỗi đối tượng phải bao gồm src, thuộc tính sizes và type của hình ảnh. Thuộc tính form_factor là không bắt buộc. Bạn có thể đặt giá trị này thành "wide" đối với ảnh chụp màn hình chỉ áp dụng cho màn hình rộng hoặc "narrow" đối với ảnh chụp màn hình chỉ áp dụng cho màn hình hẹp.

Trong Chrome, hình ảnh phải đáp ứng các tiêu chí sau:

• Chiều rộng và chiều cao tối thiểu phải là 320 px và tối đa là 3840 px.
• Kích thước tối đa không được lớn hơn 2,3 lần kích thước tối thiểu.
• Tất cả ảnh chụp màn hình khớp với kiểu dáng phù hợp phải có cùng tỷ lệ khung hình.
  • Từ Chrome 109, chỉ những ảnh chụp màn hình có form_factor được đặt thành "wide" mới hiển thị trên máy tính.
• Kể từ Chrome 109, ảnh chụp màn hình có form_factor được đặt thành "wide" sẽ bị bỏ qua trên Android. Ảnh chụp màn hình không có form_factor vẫn sẽ được hiển thị để đảm bảo khả năng tương thích ngược.

Chrome trên máy tính hiển thị ít nhất một và nhiều nhất 8 ảnh chụp màn hình đáp ứng các tiêu chí này. Ảnh chụp màn hình còn lại sẽ bị bỏ qua.

Chrome trên Android hiển thị ít nhất một và tối đa 5 ảnh chụp màn hình đáp ứng các tiêu chí này. Ảnh chụp màn hình còn lại sẽ bị bỏ qua.

Thêm tệp kê khai ứng dụng web vào các trang

Sau khi tạo tệp kê khai, hãy thêm thẻ <link> vào tất cả các trang của Ứng dụng web tiến bộ. Ví dụ:

<link rel="manifest" href="/manifest.json">

Kiểm thử tệp kê khai

Để xác minh rằng tệp kê khai của bạn được thiết lập chính xác, hãy sử dụng ngăn Manifest (Tệp kê khai) trong bảng điều khiển Application (Ứng dụng) của Công cụ của Chrome cho nhà phát triển.

Ngăn này cung cấp phiên bản nhiều thuộc tính của tệp kê khai mà con người có thể đọc được và cho phép bạn xác minh rằng tất cả hình ảnh đều đang tải đúng cách.

Màn hình chờ trên thiết bị di động

Khi ứng dụng của bạn chạy lần đầu trên thiết bị di động, có thể mất một chút thời gian để trình duyệt khởi động và nội dung ban đầu bắt đầu hiển thị. Thay vì hiện một màn hình trắng có thể khiến người dùng nghĩ rằng ứng dụng hiện không hoạt động, trình duyệt sẽ hiện màn hình chờ cho đến lần hiển thị đầu tiên.

Chrome tự động tạo màn hình chờ từ name, background_color và icons được chỉ định trong tệp kê khai. Để tạo hiệu ứng chuyển đổi mượt mà từ màn hình chờ sang ứng dụng, hãy đặt background_color có cùng màu với trang tải.

Chrome chọn biểu tượng phù hợp nhất với độ phân giải của thiết bị cho màn hình chờ. Trong hầu hết trường hợp, bạn chỉ cần cung cấp biểu tượng có kích thước 192 px và 512 px, nhưng cũng có thể cung cấp thêm biểu tượng để hiển thị phù hợp hơn.

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

Để tìm hiểu về các thuộc tính khác mà bạn có thể thêm vào tệp kê khai ứng dụng web, hãy tham khảo tài liệu về tệp kê khai ứng dụng web của MDN.