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 những 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) 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 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"
}
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 đượ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. 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à Công cụ dành 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, 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ở 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. Đâ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ó đủ không gian để 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 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 bằng 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 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 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 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à danh tính trực quan 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 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 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 đượ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ộ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 biểu tượng có thể che mờ bằ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 ở 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 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.
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ủ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í để kiểm thử và tạo phiên bản có thể che 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 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ị ghi đè bởi phần tử
theme-color<meta>HTML. 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 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ị, 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 ứ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 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. 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 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ó 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ì 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 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 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ộ.