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 trên 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 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 dưới dạng app.webmanifest.
Thêm tệp kê khai ứng dụng web vào PWA của bạn
Để tạo tệp kê khai ứng dụng web, trước tiên hãy tạo tệp văn bản bằng đố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"
}
Tuy nhiên, việc tạo tệp là chưa đủ, trình duyệt còn cần biết tệp đó tồn tại.
Liên kết đến tệp kê khai của bạn
Để trình duyệt nhận 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 đó với PWA của bạn 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. Thao tác 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 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, bên dưới 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 đượ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ẻ Ứ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 đượ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
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, cũng như 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. 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, thanh dock hoặc trình đơn của hệ điều hành.
short_name- Không bắt buộc. Đây là tên ngắn hơn của PWA. Đây là tên ngắn hơn được dùng khi không có đủ chỗ để hiển thị toàn bộ giá trị của trường
name. Hãy viết dưới 12 ký tự để giảm thiểu khả năng bị cắt bớt. icons- Mảng gồm các đối tượng biểu tượng có các trường
src,type,sizesvàpurposekhông bắt buộc, mô tả những hình ảnh nào sẽ đại diện cho PWA. start_url- URL mà PWA phải tải khi người dùng khởi động ứng dụng bằng biểu tượng đã cài đặt. Bạn nên 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, thì bạn có thể đặt đường dẫn này thành "/" để mở 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 từ đầu. Đây 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 số
fullscreen,standalone,minimal-uihoặcbrowsermô tả cách hệ điều hành nên 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 ứng dụng web 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 chính sách này,
start_urlsẽ được dùng làm giá trị dự phòng. Xin lưu ý rằng khi 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ể sẽ không cho trình duyệt phát hiện thấy PWA đã được cài đặt hay chưa.
Biểu tượng
Biểu tượng của PWA là hình ảnh nhận dạng trên trang web của người dùng khi được cài đặt, vì vậy bạn cần phải xác định ít nhất một thiết bị. 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 của trình duyệt và hệ điều hành mà trình duyệt đó được 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 thì nên là 512 x 512 pixel. Tuy nhiên, bạn cũng nên cung cấp thêm kích thước như hình ảnh có kích thước 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 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ư từ ả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
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, nhiều nhà sản xuất hoặc chế độ cài đặt có thể thay đổi hình dạng của các biểu tượng từ hình tròn thành hình vuông thành hình vuông bo tròn góc. Để 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 mờ bằng trường purpose.
Để thực hiện việc này, hãy cung cấp một tệp hình ảnh vuông có biểu tượng chính nằm trong “vùng an toàn”, một hình tròn được căn giữa trong 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 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 che mờ được hiển thị với 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 khuất, 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.
Có thể dùng được hình ảnh này với nhiều khoảng đệm hơn.
Các biểu tượng có thể che khuất tối thiểu phải là 512 x 512. 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ủa mình để cải thiện trải nghiệm trên 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ị tốt, bạn có thể cải thiện bằng cách thêm nhiều khoảng đệm hơn. Maskable.app là một công cụ trực tuyến miễn phí giúp bạn kiểm tra và tạo một phiên bản có thể che mắt của biểu tượng.
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 người dùng, mặc dù các trường này không bắt buộc để có thể 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 của thanh trạng thái trên thiết bị di động). Màu này có thể bị phần tử HTML
theme-color<meta>ghi đè. background_color- Màu giữ chỗ để 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 nằm ngoài phạm vi trang web, thì trang đó sẽ hiển thị trong trình duyệt trong ứng dụng thay vì trong cửa sổ PWA. Tuy nhiên, việc này sẽ không làm thay đổi phạm vi của trình chạy dịch vụ của bạn.
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 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 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ị, một hình ảnh tĩnh sẽ hiển thị trong khi PWA đang tải để đưa ra ý 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ư 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 biểu tượng này sử dụng hình ảnh được liên kết từ một phần tử <link> độc quyền tương tự như cách xử lý các biểu tượng. Hãy xem chương Bản nâng cao để biết thêm thông tin chi tiết.
Trường mở rộng
Nhóm trường tiếp theo sẽ 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 cho giá trị của 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ỉ đườ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. Trò chơi có thể thiết lập chế độ cài đặt này để yêu cầu hướng ngang. Một số giá trị được chấp nhận, nhưng nếu bạn thêm giá trị đó 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 bá về PWA của mình, 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- Thông tin giải thích về chức năng của PWA.
screenshots- Mảng gồm các đối tượng chụp ảnh màn hình có
src,typevàsizes(tương tự như đối tượngicons) dùng để hiển thị PWA. Không có quy định giới hạn về kích thước. categories- Mảng các danh mục mà PWA phải thuộc vào được dùng làm gợi ý cho trang thông tin, (không bắt buộ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ó). Ứng dụng này được dùng để xác định những độ 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 hoạt động 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ì trải nghiệm hộp thoại cài đặt sẽ chuyển đổi từ giao diện "Thêm vào màn hình chính" đơn giản thanh thông tin sang 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ể nhận đượ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ách các trường quảng cáo này hoạt động trong thực tế:
Trường chức năng
Sau cùng, có một số trường liên quan đến những chức năng khác nhau mà PWA có thể sử dụng trong những 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 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 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 tính năng hơn vào Progressive Web Apps.