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) phải hoạt động khi được cài đặt trên máy tính của người dùng hoặc thiết bị di động của bạn. Ở mức tối thiểu, một 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 nên được mở khi ứng dụng khởi chạy

Tạo tệp kê khai

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

Một tệp kê khai thông thường sẽ 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 được dùng khi ứng dụng được cài đặt và short_name là được sử dụng trên màn hình chính, trình chạy hoặc những nơi khác của người dùng có không gian bị hạn chế.

icons

Khi người dùng cài đặt PWA của bạn, bạn có thể xác định một bộ biểu tượng cho 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à những nơi 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 thích ứng, đôi khi được gọi là 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 nhất 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 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 mở rộng quy mô biểu tượng riêng và điều chỉnh chúng để đạt độ hoàn hảo về điểm ảnh, cung cấp biểu tượng theo từng phần 48 dp.

id

Thuộc tính id cho phép bạn xác định rõ giá trị nhận dạng dùng cho . 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 giúp bạn có thể cập nhật chúng trong tương lai. Để biết thêm thông tin, hãy xem Xác định duy nhất PWA bằng thuộc tính mã nhận dạng tệp kê khai ứng dụng web.

start_url

start_url là một thuộc tính bắt buộc. Mã này cho trình duyệt biết vị trí ứng dụng sẽ khởi động khi khởi chạy và ngăn ứng dụng khởi động bất kỳ trang nào người dùng đã truy cập khi họ 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 thẳng đến ứng dụng của bạn chứ không phải sản phẩm trang đích. Hãy nghĩ xem người dùng sẽ muốn làm gì ngay sau khi họ mở ứng dụng của bạn rồi đặt chúng vào đó.

background_color

Thuộc tính background_color được 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 của trình duyệt nào sẽ xuất hiện khi ứng dụng của bạn được phát hành. Cho 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ỉ. Trò chơi thậm chí có thể chạy ở chế độ toàn màn hình. Thuộc tính display sẽ lấy 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 của trình duyệt và chiếm tất cả khu vực hiển thị có sẵn.
standalone	Mở ứng dụng web để giao diện như một ứng dụng độc lập. Ứng dụng chạy trong cửa sổ riêng, tách biệt với trình duyệt và ẩn thẻ chuẩn các phần tử trên giao diện người dùng 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 người dùng có một tập hợp tối thiểu gồm các phần tử 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 chuẩn.

display_override

Để chọn cách hiển thị ứng dụng web của bạn, hãy đặt chế độ display trong tệp kê khai dưới dạng nội dung giải thích ở phần trước. Trình duyệt không bắt buộc phải hỗ trợ tất cả màn hình các chế độ cài đặt khác, nhưng chúng cần phải có các chế độ đó để hỗ trợ chuỗi dự phòng theo quy cách ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Nếu không hỗ trợ một chế độ nhất định, chúng sẽ quay lại chế độ hiển thị tiếp theo trong chuỗi. Trong trong một số ít trường hợp, những 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 màn hình "browser" khi "minimal-ui" không được hỗ trợ. Hành vi hiện tại cũng giúp không thể giới thiệu các chế độ hiển thị mới theo cách tương thích ngược, bởi vì chúng 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 thuộc tính này là chuỗi được xem xét theo thứ tự được liệt kê và chuỗi đầu tiên sẽ áp dụng chế độ hiển thị hỗ trợ. Nếu không có phương pháp nào được hỗ trợ, trình duyệt sẽ quay lại sử dụng để đánh giá trường display. Nếu không có trường display thì trình duyệt 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 cho 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ố sử dụng "window-control-overlay" đầu tiên. Nếu không dùng được, hệ thống sẽ chuyển lại về "minimal-ui", sau đó là "standalone" trong thuộc tính display. Nếu không có đề xuất nào trong số này, sau đó quay lại chuỗi dự phòng chuẩn.

scope

scope của ứng dụng là tập hợp URL mà trình duyệt coi là một phần ứng dụng của bạn. scope kiểm soát cấu trúc URL bao gồm tất cả các mục nhập và thoát trỏ đến ứng dụng và trình duyệt sẽ sử dụng điểm này để xác định thời điểm người dùng đã rời đ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ì mặc định sẽ ngụ ý scope là URL bắt đầu, nhưng tên tệp, truy vấn và mảnh của nó đã bị xoá.
• Thuộc tính scope có thể là một đường dẫn tương đối (../) hoặc bất kỳ cấp nào cao hơn đường dẫn (/) giúp tăng phạm vi điều hướng trong ứng dụng web của bạn.
• 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 Đã chỉ định màu giao diện meta trong phần đầu tài liệu của bạn.

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

Bạn có thể điều chỉnh theme_color trong truy vấn phương tiện bằng cách sử dụng thuộc tính media của giá trị 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 thiết bị khác cho chế độ tối theo cách này. Tuy nhiên, bạn không thể xác định các lựa chọn ưu tiên trong tệp kê khai của bạn. Để biết thêm thông tin, hãy xem vấn đề 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 lối tắt ứng dụng giúp bạn truy cập nhanh vào các công việc chính trong ứng dụng. Mỗi thành viên là từ điển chứa tối thiểu name và 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 mô tả dài hơn thế, trình duyệt sẽ cắt bớt bằng một ký tự dấu ba chấm. Trên Android, phần 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, 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ể thiết lập thuộc tính này thành "wide" đối với ảnh chụp màn hình áp dụng cho màn hình rộng hoặc "narrow" đối với chỉ ảnh chụp 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 độ dài của kích thước tối thiểu .
• Tất cả ảnh chụp màn hình khớp với hệ số hình dạng phù hợp đều phải có cùng tỷ lệ khung hình.
  • Từ Chrome 109, chỉ các ảnh chụp màn hình có form_factor được đặt thành "wide" đều hiển thị trên máy tính.
• 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 được hiển thị trong khả năng tương thích ngược.

Chrome trên máy tính hiển thị ít nhất 1 và tối đa 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 1 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 của bạn

Sau khi tạo tệp kê khai, hãy thêm thẻ <link> vào tất cả các trang trong tệp kê khai Ứ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 đúng cách, 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ụ cho nhà phát triển của Chrome.

Ngăn này cung cấp phiên bản mà con người có thể đọc được của nhiều tệp kê khai thuộc tính 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 để bắt đầu và nội dung ban đầu để bắt đầu kết xuất. Thay vì hiển thị màn hình trắng có thể khiến người dùng nghĩ rằng ứng dụng không hoạt động, trình duyệt hiển thị 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 của bạn. Để tạo trải nghiệm mượt mà chuyển đổi từ màn hình chờ sang ứng dụng, giúp bạn background_color cùng màu với trang tải.

Chrome sẽ 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ờ. Việc cung cấp biểu tượng có kích thước 192 px và 512 px là đủ cho hầu hết các trường hợp, nhưng bạn có thể cung cấp các biểu tượng khác để kết quả phù hợp hơn.

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

Để tìm hiểu về những 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 MDN.