Tệp kê khai ứng dụng web là một tệp mà bạn tạo để cho trình duyệt biết cách bạn muốn nội dung web hiển thị dưới dạng ứng dụng trong hệ điều hành. Tệp kê khai có thể bao gồm thông tin cơ bản như tên, biểu tượng và màu giao diện của ứng dụng; các tuỳ chọn ưu tiên nâng cao, chẳng hạn như hướng mong muốn và lối tắt ứng dụng; cũng như siêu dữ liệu danh mục, chẳng hạn như ảnh chụp màn hình.
Mỗi PWA phải có một tệp kê khai cho mỗi ứng dụng, thường được lưu trữ trong thư mục gốc và được liên kết trên tất cả các trang HTML mà bạn có thể cài đặt PWA. Tên mở rộng chính thức của tệp này là .webmanifest, vì vậy, bạn có thể đặt tên tệp kê khai là app.webmanifest.
Thêm tệp kê khai ứng dụng web vào PWA
Để tạo tệp kê khai ứng dụng web, trước tiên, hãy tạo một tệp văn bản có đối tượng JSON chứa ít nhất một trường name có giá trị chuỗi:
app.webmanifest:
{
"name": "My First Application"
}
Nhưng việc tạo tệp là chưa đủ, trình duyệt cũng cần biết tệp đó tồn tại.
Liên kết đến tệp kê khai
Để trình duyệt nhận biết tệp kê khai ứng dụng web, bạn cần liên kết tệp kê khai đó với PWA bằng phần tử HTML <link> và đặt thuộc tính rel thành manifest trên tất cả các trang HTML của PWA. Cách này tương tự như cách bạn liên kết một tệp phông chữ CSS với một tài liệu.
index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
Gỡ lỗi tệp kê khai
Để đảm bảo tệp kê khai được thiết lập chính xác, bạn có thể sử dụng Trình kiểm tra trong Firefox và DevTools trong mọi trình duyệt dựa trên Chromium.
Đối với trình duyệt Chromium
Trong Công cụ cho nhà phát triển
- Trong ngăn bên trái, trong mục Application (Ứng dụng), hãy chọn Manifest (Tệp kê khai).
- Kiểm tra các trường của tệp kê khai do trình duyệt phân tích cú pháp.
Đối với Firefox
- Mở Inspector (Trình kiểm tra).
- Chuyển đến thẻ Ứng dụng.
- Chọn tuỳ chọn Tệp kê khai trong bảng điều khiển bên trái.
- Kiểm tra các trường của tệp kê khai do trình duyệt phân tích cú pháp.
Thiết kế trải nghiệm ứng dụng web tiến bộ (PWA)
Giờ đây, khi PWA đã được kết nối với tệp kê khai, bạn cần điền vào các trường còn lại để xác định trải nghiệm cho người dùng.
Các trường cơ bản
Nhóm trường đầu tiên thể hiện thông tin cốt lõi về PWA của bạn. Các tệp này được dùng để tạo biểu tượng và cửa sổ của PWA đã cài đặt, đồng thời xác định cách khởi động PWA. Các loại chiến dịch phụ đó là:
name- Tên đầy đủ của PWA. Tên ứng dụng sẽ xuất hiện cùng với biểu tượng trong màn hình chính, trình chạy, thanh dock hoặc trình đơn của hệ điều hành.
short_name- Không bắt buộc, tên ngắn hơn của PWA, được dùng khi không có đủ chỗ để hiển thị toàn bộ giá trị của trường
name. Hãy giữ cho tên không dài quá 12 ký tự để giảm thiểu khả năng bị cắt bớt. icons- Mảng các đối tượng biểu tượng có các trường
src,type,sizesvàpurpose(không bắt buộc), mô tả hình ảnh sẽ đại diện cho PWA. start_url- URL mà PWA sẽ tải khi người dùng khởi động ứng dụng từ biểu tượng đã cài đặt. Bạn nên sử dụng đường dẫn tuyệt đối. Vì vậy, nếu trang chủ của PWA là thư mục gốc của trang web, bạn có thể đặt đường dẫn này thành "/" để mở trang chủ khi ứng dụng khởi động. Nếu bạn không cung cấp URL bắt đầu, trình duyệt có thể sử dụng URL mà PWA được cài đặt làm URL bắt đầu. Đó có thể là một đường liên kết sâu, chẳng hạn như thông tin chi tiết về một sản phẩm thay vì màn hình chính.
display- Một trong các giá trị
fullscreen,standalone,minimal-uihoặcbrowser, mô tả cách hệ điều hành vẽ cửa sổ PWA. Bạn có thể đọc thêm về các chế độ hiển thị khác nhau trong chương Thiết kế ứng dụng. Hầu hết các trường hợp sử dụng đều triển khaistandalone. id- Một chuỗi giúp xác định duy nhất PWA này so với các PWA khác có thể được lưu trữ trên cùng một nguồn gốc. Nếu bạn không đặt giá trị này,
start_urlsẽ được dùng làm giá trị dự phòng. Xin lưu ý rằng bằng cách thay đổistart_urltrong tương lai (chẳng hạn như khi thay đổi giá trị chuỗi truy vấn), bạn có thể làm mất khả năng của trình duyệt phát hiện rằng một PWA đã được cài đặt.
Biểu tượng
Biểu tượng của PWA là bản sắc hình ảnh của ứng dụng trên thiết bị của người dùng khi được cài đặt, vì vậy, bạn cần xác định ít nhất một biểu tượng. Vì thuộc tính icons là một tập hợp các đối tượng biểu tượng, nên bạn có thể xác định một số biểu tượng ở nhiều định dạng để mang lại trải nghiệm biểu tượng tốt nhất cho người dùng. Mỗi trình duyệt sẽ chọn một hoặc nhiều biểu tượng dựa trên nhu cầu và hệ điều hành mà trình duyệt đó được cài đặt, các biểu tượng gần với thông số kỹ thuật cần thiết hơn.
Nếu bạn chỉ cần chọn một kích thước biểu tượng, kích thước đó phải là 512x512 pixel. Tuy nhiên, bạn cũng nên cung cấp thêm các kích thước khác, bao gồm cả hình ảnh có kích thước 192x192, 384x384 và 1024x1024 pixel.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
Nếu không cung cấp biểu tượng hoặc biểu tượng không có kích thước đề xuất, thì trên một số nền tảng, bạn sẽ không vượt qua được các tiêu chí cài đặt. Trên các nền tảng khác, biểu tượng sẽ được tạo tự động, chẳng hạn như từ ảnh chụp màn hình của PWA hoặc bằng cách sử dụng biểu tượng chung.
Biểu tượng có thể che mờ
Một số hệ điều hành, chẳng hạn như Android, điều chỉnh biểu tượng cho phù hợp với nhiều kích thước và hình dạng. Ví dụ: trên Android 12, các nhà sản xuất hoặc chế độ cài đặt khác nhau có thể thay đổi hình dạng của biểu tượng từ hình tròn sang hình vuông rồi sang hình vuông bo tròn các góc. Để hỗ trợ các loại biểu tượng thích ứng này, bạn có thể cung cấp một biểu tượng có thể che bằng cách sử dụng trường purpose.
Để làm như vậy, hãy cung cấp một tệp hình ảnh hình vuông có biểu tượng chính nằm trong "vùng an toàn", một vòng tròn ở chính giữa biểu tượng với bán kính bằng 40% chiều rộng của biểu tượng. (Xem hình ảnh bên dưới.) Những thiết bị hỗ trợ biểu tượng có thể che sẽ che biểu tượng của bạn nếu cần.
Dưới đây là ví dụ về một biểu tượng có thể che được hiển thị ở một số hình dạng thường dùng:
Trong hình ảnh sau, nếu sử dụng biểu tượng ở bên trái làm biểu tượng có thể che, bạn sẽ nhận được kết quả không tốt trên các thiết bị khi áp dụng mặt nạ hình dạng.
Bạn có thể sử dụng hình ảnh này bằng cách tăng khoảng đệm.
Biểu tượng có thể che phải có kích thước tối thiểu là 512x512. Sau khi tạo một tệp, bạn có thể thêm tệp đó vào bộ sưu tập icons để cải thiện trải nghiệm cho các thiết bị được hỗ trợ:
"icons": [
{
"src": "/icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "/icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
},
{
"src": "/icons/512-maskable.png",
"type": "image/png",
"sizes": "512x512",
"purpose": "maskable"
},
]
Trong hầu hết các trường hợp, nếu biểu tượng có thể che khuất của bạn không hiển thị tốt, bạn có thể cải thiện bằng cách thêm khoảng đệm. Maskable.app là một công cụ trực tuyến miễn phí để kiểm thử và tạo phiên bản có thể che của biểu tượng.
Nếu biểu tượng của bạn phục vụ các mục đích chung và có thể bị che khuất, bạn có thể đặt trường purpose thành "any maskable". Hãy tham khảo tài liệu về Tệp kê khai ứng dụng web của MDN để biết thông tin chi tiết.
Các trường đề xuất
Nhóm trường tiếp theo cần thêm là những trường sẽ cải thiện trải nghiệm của người dùng, mặc dù không bắt buộc phải có để có thể cài đặt.
theme_color- Màu mặc định cho ứng dụng, đôi khi ảnh hưởng đến cách hệ điều hành hiển thị trang web (ví dụ: màu cửa sổ và thanh tiêu đề trên máy tính hoặc màu thanh trạng thái trên thiết bị di động). Màu này có thể bị phần tử
theme-color<meta>HTML ghi đè. background_color- Màu của phần giữ chỗ để hiển thị trong nền của ứng dụng trước khi tải kiểu. Safari trên iOS và iPadOS cũng như hầu hết các trình duyệt dành cho máy tính hiện bỏ qua trường này.
scope- Thay đổi phạm vi điều hướng của PWA, cho phép bạn xác định những nội dung hiển thị và không hiển thị trong cửa sổ của ứng dụng đã cài đặt. Ví dụ: nếu bạn liên kết đến một trang nằm ngoài phạm vi, thì trang đó sẽ được hiển thị trong trình duyệt trong ứng dụng thay vì trong cửa sổ PWA. Tuy nhiên, điều này sẽ không làm thay đổi phạm vi của worker dịch vụ.
Hình ảnh tiếp theo cho thấy cách sử dụng trường theme_color cho thanh tiêu đề trên thiết bị máy tính khi bạn cài đặt một PWA.
Khi xác định màu trong tệp kê khai, chẳng hạn như trong theme_color và background_color, bạn nên sử dụng màu được đặt tên CSS, chẳng hạn như salmon hoặc orange, màu RGB như #FF5500 hoặc các hàm màu không có độ trong suốt như rgb() hoặc hsl(). Hãy xem Chương thiết kế ứng dụng để biết thêm thông tin.
Dùng thử
Màn hình chờ
Trên một số thiết bị, hình ảnh tĩnh sẽ được kết xuất trong khi PWA đang tải để cung cấp phản hồi tức thì cho người dùng.
Android sử dụng các giá trị theme_color, background_color và icon để tạo màn hình chờ.
Khi bạn cài đặt một PWA trên Android, thiết bị sẽ tạo một màn hình chờ có thông tin lấy từ tệp kê khai như trong sơ đồ sau.
Mặt khác, Safari trên iOS và iPadOS không sử dụng tệp kê khai ứng dụng web để tạo màn hình chờ. Thay vào đó, chúng sử dụng hình ảnh được liên kết từ phần tử <link> độc quyền tương tự như cách xử lý biểu tượng. Hãy xem Chương cải tiến để biết thêm thông tin chi tiết.
Trường mở rộng
Nhóm trường tiếp theo cung cấp thêm thông tin về PWA của bạn. Tất cả đều không bắt buộc.
lang- Thẻ ngôn ngữ chỉ định ngôn ngữ chính của các giá trị trong tệp kê khai, chẳng hạn như
encho tiếng Anh,pt-BRcho tiếng Bồ Đào Nha Brazil hoặcincho tiếng Hindi. dir- Hướng hiển thị các trường tệp kê khai có thể hiển thị hướng (chẳng hạn như
name,short_namevàdescription). Các giá trị hợp lệ làauto,ltr(từ trái sang phải) vàrtl(từ phải sang trái). orientation- Hướng mong muốn cho ứng dụng sau khi cài đặt. Một trò chơi có thể đặt giá trị này để yêu cầu hướng chỉ theo chiều ngang. Một số giá trị được chấp nhận, nhưng nếu có, giá trị đó thường là
portraithoặclandscapemột cách rõ ràng.
Trường khuyến mãi
Nhóm trường thứ tư cho phép bạn cung cấp thông tin quảng bá về PWA, chẳng hạn như trong quy trình cài đặt, trang thông tin và kết quả tìm kiếm.
description- Nội dung giải thích về chức năng của PWA.
screenshots- Mảng các đối tượng ảnh chụp màn hình có
src,typevàsizes(tương tự như đối tượngicons) nhằm giới thiệu PWA. Không có giới hạn về kích thước. categories- Mảng danh mục mà PWA thuộc về để dùng làm gợi ý cho trang thông tin, không bắt buộc trong danh sách danh mục đã biết. Các giá trị này thường được viết bằng chữ thường.
iarc_rating_id- Mã chứng nhận của Liên minh phân loại theo độ tuổi quốc tế cho PWA, nếu bạn có. Mục đích của thuộc tính này là xác định độ tuổi phù hợp với PWA của bạn.
Bạn có thể xem các trường quảng bá này hoạt động như thế nào ngay hôm nay. Ví dụ: trên Android, nếu PWA của bạn có thể cài đặt và bạn cung cấp giá trị cho ít nhất là các trường description và screenshots, thì hộp thoại cài đặt sẽ chuyển đổi từ một thanh thông tin "Thêm vào màn hình chính" đơn giản thành một hộp thoại cài đặt phong phú hơn tương tự như hộp thoại trong cửa hàng ứng dụng.
Trên Android, bạn có thể có giao diện người dùng cài đặt đẹp hơn nếu cung cấp giá trị cho các trường quảng bá, như bạn có thể thấy trong video tiếp theo
Hãy xem các trường khuyến mãi này trong thực tế:
Trường về chức năng
Cuối cùng, có một số trường liên quan đến các chức năng mà PWA có thể sử dụng trong các trình duyệt được hỗ trợ, chẳng hạn như các trường shortcuts, share_target, display_override như chúng ta đề cập trong chương về Chức năng. Ngoài ra, còn có các trường như related_apps và prefer_related_apps (xem chương Phát hiện để biết thêm thông tin) để kết nối PWA với các ứng dụng đã cài đặt, thường là từ một cửa hàng ứng dụng.
Trong tương lai, nhiều trường mới có thể xuất hiện trong khi trình duyệt bổ sung thêm chức năng cho Ứng dụng web tiến bộ.