Tệp kê khai ứng dụng web là tệp bạn tạo để cho trình duyệt biết cách bạn muốn nội dung web của mình 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 các 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 lựa chọn ưu tiên nâng cao, chẳng hạn như hướng và lối tắt ứng dụng mong muốn; và 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 bao gồm một tệp kê khai duy nhất 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 có thể cài đặt PWA của bạn. Tiện ích chính thức của tệp kê khai là .webmanifest, vì vậy, bạn có thể đặt tên cho tệp kê khai như 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 tệp văn bản có đối tượng JSON chứa ít nhấ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 phải biết tệp đó tồn tại.
Liên kết đến tệp kê khai của bạn
Để giúp trình duyệt biết được tệp kê khai ứng dụng web của bạn, bạn cần liên kết tệp kê khai đó với PWA bằng cách sử dụng phần tử HTML <link> và thuộc tính rel được đặt thành manifest trên tất cả các trang HTML của PWA. Điều này tương tự như cách bạn liên kết biểu định kiểu 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à Công cụ cho nhà phát triển trên 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 phần 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 như được trình duyệt phân tích cú pháp.
Đối với Firefox
- Mở Trình kiểm tra.
- Chuyển đến thẻ Application (Ứ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 như được trình duyệt phân tích cú pháp.
Thiết kế trải nghiệm PWA
Khi PWA hiện đã kết nối với tệp kê khai, đã đến lúc điền vào các trường còn lại để xác định trải nghiệm cho người dùng.
Trường cơ bản
Tập hợp trường đầu tiên trình bày thông tin chính về PWA của bạn. Chúng đượ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 ứng dụng khởi động. Các yếu tố này là:
name- Tên đầy đủ của PWA của bạn. Biểu tượng này sẽ xuất hiện cùng với biểu tượng trên màn hình chính, trình chạy, đế 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ó đủ dung lượng để hiển thị toàn bộ giá trị của trường
name. Đảm bảo tên miền dưới 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ó
src,type,sizesvà trườngpurposekhông bắt buộc, mô tả những hình ảnh nào nên đại diện cho PWA. start_url- URL mà PWA phải tải khi người dùng khởi động PWA 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à gốc của trang web, bạn có thể đặt đường dẫn này thành "/" để mở đường dẫn đó khi ứng dụng khởi động. Nếu bạn không cung cấp URL bắt đầu, thì trình duyệt có thể sử dụng URL mà PWA đã được cài đặt 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ề sản phẩm thay vì màn hình chính.
display- Một trong các
fullscreen,standalone,minimal-uihoặcbrowser, mô tả cách hệ điều hành sẽ 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 dùng để nhận dạng 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 thuộc tính này,
start_urlsẽ được dùng làm giá trị dự phòng. Xin lưu ý rằng nếu sau này thay đổistart_url(chẳng hạn như khi thay đổi giá trị chuỗi truy vấn), bạn có thể không còn khả năng phát hiện PWA đã được cài đặt của trình duyệt.
Biểu tượng
Biểu tượng của PWA là thông tin nhận dạng trực quan trên thiết bị của người dùng khi được cài đặt, nên bạn phải 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 tuỳ theo nhu cầu của trình duyệt và hệ điều hành mà trình duyệt đó đã cài đặt, các biểu tượng gần hơn với thông số kỹ thuật cần thiết.
Nếu bạn chỉ cần chọn một kích thước biểu tượng, kích thước đó nên là 512 x 512 pixel. Tuy nhiên, bạn cũng nên cung cấp thêm các kích thước hình ảnh có kích thước như 192 x 192, 384 x 384 và 1024 x 1024 pixel.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
Nếu bạn không cung cấp biểu tượng hoặc các biểu tượng không có kích thước đề xuất, thì bạn sẽ không đáp ứng được tiêu chí cài đặt trên một số nền tảng. 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ư qua ảnh chụp màn hình của PWA hoặc bằng cách sử dụng một biểu tượng chung.
Biểu tượng có thể che phủ
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, hình vuông hay hình vuông góc tròn. Để hỗ trợ các loại biểu tượng thích ứng này, bạn có thể cung cấp biểu tượng có thể che giấu bằng cách sử dụng trường purpose.
Để thực hiện việc này, hãy cung cấp tệp hình ảnh vuông có biểu tượng chính nằm trong "vùng an toàn", một vòng tròn nằm ở 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 dưới đây.) Các thiết bị hỗ trợ biểu tượng có thể che giấu sẽ che biểu tượng của bạn khi cần.
Dưới đây là ví dụ về một biểu tượng có thể che phủ được hiển thị ở một số hình dạng thường dùng:
Trong hình sau, nếu sử dụng biểu tượng ở bên trái làm biểu tượng có thể che giấu, bạn sẽ nhận được kết quả kém trên thiết bị khi áp dụng mặt nạ hình dạng.
Hình ảnh này có thể sử dụng được với nhiều khoảng đệm hơn.
Các biểu tượng che phủ phải có kích thước ít nhất là 512 x 512. Sau khi tạo một chiến dịch, bạn có thể thêm tệp đó vào bộ sưu tập icons của mình để cải thiện trải nghiệm khi dùng 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 không hiển thị chính xác, bạn có thể cải thiện biểu tượng đó 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 tra và tạo phiên bản biểu tượng có thể che giấu.
Các trường đề xuất
Nhóm trường tiếp theo mà bạn cần thêm là những trường sẽ cải thiện trải nghiệm người dùng (mặc dù không bắt buộc đối với khả năng cài đặt).
theme_color- Màu mặc định của ứ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 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). Bạn có thể ghi đè màu này bằng phần tử HTML
theme-color<meta>. background_color- Màu phần giữ chỗ sẽ hiển thị trong nền của ứng dụng trước khi biểu định kiểu được tải. 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 nội dung nào được và không được 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 bên ngoài phạm vi, thì trang đó sẽ xuất hiện trên trình duyệt trong ứng dụng thay vì trong cửa sổ PWA. Tuy nhiên, thao tác này sẽ không thay đổi phạm vi của trình chạy dịch vụ.
Hình ảnh tiếp theo cho thấy cách trường theme_color được sử dụng cho thanh tiêu đề trên thiết bị máy tính khi bạn cài đặt một ứng dụng web tiến bộ (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ê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 trong suốt như rgb() hoặc hsl(). Xem Chương thiết kế ứng dụng để biết thêm thông tin.
Thử ngay
Màn hình chờ
Trên một số thiết bị, hình ảnh tĩnh sẽ được hiển thị trong khi PWA của bạn đang được tải để cung cấp ý kiến phản hồi ngay lập tức 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 ứng dụng web tiến bộ (PWA) trên Android, thiết bị sẽ tạo một màn hình chờ chứa thông tin từ tệp kê khai của bạn như minh hoạ trong sơ đồ dưới đây.
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 đó, các ứng dụng này sử dụng hình ảnh được liên kết từ một phần tử <link> thuộc quyền sở hữu riêng, tương tự như cách họ xử lý các biểu tượng. Xem chương Các tính năng nâng cao để biết thêm thông tin chi tiết.
Trường mở rộng
Tập hợp 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- Một thẻ ngôn ngữ chỉ định ngôn ngữ chính của 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ó khả năng chỉ 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 bạn muốn cài đặt của ứng dụng sau khi cài đặt. Trò chơi có thể thiết lập chế độ này để yêu cầu hướng chỉ xem ngang. Một số giá trị được chấp nhận, nhưng nếu được đưa vào, thì giá trị này thường là
portraithoặclandscapemột cách rõ ràng.
Trường quảng cáo
Nhóm trường thứ tư cho phép bạn cung cấp thông tin quảng cáo về PWA, chẳng hạn như thông tin 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 mục đích 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 cần thuộc phải được dùng làm gợi ý cho trang thông tin, không bắt buộc phải có trong danh sách các danh mục đã biết. Các giá trị này thường là 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 có). Dữ liệu này dùng để 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 cáo này trong thực tế 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 các trường description và screenshots, thì trải nghiệm hộp thoại cài đặt sẽ chuyển đổi từ thanh thông tin "Thêm vào màn hình chính" đơn giản thành 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 cáo, như bạn có thể thấy trong video tiếp theo
Xem các trường quảng cáo này trong thực tế:
Trường chức năng
Cuối cùng, có một số trường liên quan đến nhiều 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_overrides như chúng tôi đã đề cập trong chương Các chức năng. Ngoài ra, còn có các trường như related_apps và prefer_related_apps (xem chương về Phát hiện để biết thêm thông tin), để kết nối PWA của bạn với các ứng dụng đã cài đặt, thường là từ một cửa hàng ứng dụng.
Nhiều trường mới có thể xuất hiện trong tương lai trong khi các trình duyệt thêm nhiều khả năng hơn vào Ứng dụng web tiến bộ.