Tệp kê khai ứng dụng web là một tệp JSON cho trình duyệt biết cách hoạt động của Ứng dụng web tiến bộ (PWA) khi được cài đặt trên máy tính hoặc thiết bị di động của người dùng. Ở mức tối thiểu, tệp kê khai thông thường bao gồm:
- Tên của ứng dụng
- Biểu tượng mà ứng dụng sẽ sử dụng
- URL sẽ được 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ê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 tiện ích nên là .webmanifest, nhưng bạn nên sử dụng tệp JSON để làm cho 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"
}
]
}
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 số short_name hoặc name trong tệp kê khai. Nếu bạn cung cấp cả hai, thì 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ủa người dùng khi không gian bị giới hạn.
icons
Khi người dùng cài đặt PWA, bạn có thể xác định một tập hợp 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, đô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 nhất 192 x 192 pixel và biểu tượng 512 x 512 pixel. Nếu bạn 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 và điều chỉnh cho phù hợp với mức độ hoàn hảo về điểm ảnh, hãy cung cấp các 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 dùng cho ứng dụng của mình. 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 các thuộc tính này trong tương lai. Để biết thêm thông tin, hãy xem phần 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 ứng dụng của bạn sẽ bắt đầu từ đâu khi khởi chạy và ngăn ứng dụng bắt đầu trên bất cứ trang nào người dùng đang truy cập khi họ thêm ứng dụng vào màn hình chính.
start_url phải chuyển người dùng đến thẳng ứng dụng của bạn, không phải trang đích của sản phẩm. Hãy nghĩ về những hành động mà người dùng sẽ muốn làm ngay sau khi mở ứng dụng của bạn và đặt ứng dụ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 lần đầu trên thiết bị di động.
display
Bạn có thể tuỳ chỉnh giao diện người dùng của trình duyệt sẽ xuất hiện khi ứng dụng được khởi chạy. Ví dụ: bạn có thể ẩn thanh địa chỉ và các thành phần giao diện người dùng của trình duyệt. Trò chơi thậm chí có thể được thực hiện để khở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:
| Tài sản | Hành vi |
|---|---|
fullscreen |
Mở ứng dụng web mà không cần 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 để có giao diện như một ứng dụng độc lập. Ứng dụng 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 tiêu chuẩn 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 cho người dùng một tập hợp tối thiểu các phần tử trên giao diện người dùng để điều khiển thao tác, 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 ứng dụng web của bạn hiển thị, hãy đặt chế độ display trong tệp kê khai như đã giải thích trước đó. Các trình duyệt không bắt buộc phải hỗ trợ tất cả chế độ hiển thị, nhưng bắt buộc 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, các 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, 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 buộc phải 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ể ra mắt 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 là trước thuộc tính display. Giá trị của thuộc tính này là một chuỗi các chuỗi được xem xét theo thứ tự được liệt kê và chế độ hiển thị được hỗ trợ đầu tiên sẽ được áp dụng. Nếu không có trường 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" không thuộc 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ó sẵn, biến sẽ quay lại "minimal-ui", sau đó chuyển thành "standalone" từ thuộc tính display. Nếu không có kết quả nào trong số này, trình duyệt sẽ quay về chuỗi dự phòng tiêu 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 của ứng dụng. scope kiểm soát cấu trúc URL bao gồm tất cả điểm vào và điểm thoát của ứ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
scopevào tệp kê khai, thìscopengụ ý mặc định sẽ là URL bắt đầu, nhưng tên tệp, truy vấn và mảnh sẽ bị xoá. - Thuộc tính
scopecó 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 mức độ sử dụng các thành phần điều hướng trong ứng dụng web của bạn. start_urlphải nằm trong phạm vi.start_urltương ứng với đường dẫn được xác định trong thuộc tínhscope.start_urlbắ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 tuỳ chỉnh.
theme_color trong truy vấn phương tiện
Bạn có thể điều chỉnh theme_color trong truy vấn nội dung đa phương tiện bằng cách sử dụ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 lựa 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 cho phép truy cập nhanh vào các tác vụ chính trong ứng dụng của bạn. 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 tối đa của nội dung mô tả là 300 ký tự trên tất cả nền tảng. Nếu nội dung mô tả dài hơn thế, trình duyệt sẽ cắt bớt bằng ký tự 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 thuộc tính này thành "wide" cho ảnh chụp màn hình chỉ áp dụng cho màn hình rộng hoặc "narrow" cho ả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 chiều dài của phương diện tối thiểu.
- Tất cả ảnh chụp màn hình phù hợp với hệ số hình dạng thích hợp phải có cùng tỷ lệ khung hình.
- Từ Chrome 109, chỉ ả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.
- Từ Chrome 109, chỉ ảnh chụp màn hình có
- 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_factorvẫn 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 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 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 đúng cách, hãy sử dụng ngăn Tệp kê khai trong bảng điều khiển Ứ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 mà con người có thể đọc được của nhiều thuộc tính của tệp kê khai, đồng thời cho phép bạn xác minh rằng tất cả hình ảnh đang tải đúng cách.
Màn hình chờ trên thiết bị di động
Trong lần đầu ứng dụng của bạn chạy 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àn hình trắng có thể khiến người dùng nghĩ rằng ứng dụng đang không hoạt động, trình duyệt sẽ cho thấy 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. Để chuyển đổi suôn sẻ từ màn hình chờ sang ứng dụng, hãy 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 các trường hợp, chỉ cần cung cấp biểu tượng 192px và 512px. Tuy nhiên, bạn có thể cung cấp biểu tượng bổ sung để 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 MN.