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ínhscope
.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, chỉ các ả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_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.