Hướng dẫn kê khai ứng dụng web
Tệp kê khai ứng dụng web (site.webmanifest) là tệp JSON cho trình duyệt có thể cài đặt biết tên, màu sắc, chế độ hiển thị của ứng dụng và kích thước biểu tượng nào sẽ sử dụng trên màn hình chính. Việc liên kết nó với `<link rel='manifest' href='/site.webmanifest'>` sẽ bật lời nhắc cài đặt Chrome và Edge PWA trên máy tính để bàn và Android. Ghép nối nó với các biểu tượng 192×192 và 512×512 PNG — cả hai đều được favicon generator xuất — để có thiết lập favicon PWA hoàn chỉnh.
Tệp kê khai ứng dụng web là tệp văn bản JSON được cung cấp với loại MIME `application/manifest+json`. Nó tồn tại ở bất kỳ URL nào bạn chọn, nhưng quy ước là /site.webmanifest ở gốc tên miền. Bạn liên kết nó từ HTML bằng cách sử dụng `<link rel='manifest' href='/site.webmanifest'>` bên trong phần tử `<head>`. Trình duyệt đọc tệp kê khai khi đang đánh giá xem có hiển thị lời nhắc cài đặt hay cách hiển thị ứng dụng của bạn sau khi cài đặt hay không.
Mảng biểu tượng là phần liên quan đến favicon nhất trong tệp kê khai. Mỗi mục nhập chỉ định một src (URL tới hình ảnh), kích thước (kích thước pixel), loại (loại MIME) và mục đích tùy chọn ('bất kỳ', 'có thể che được' hoặc 'bất kỳ có thể che được'). Tối thiểu, cung cấp 192×192 PNG cho biểu tượng trình khởi chạy và 512×512 PNG cho màn hình chờ. Nếu không có những thứ này, XXH3XX sẽ không hiển thị lời nhắc cài đặt.
Biểu tượng 192×192 được Android Chrome sử dụng trong trình khởi chạy ứng dụng, trình chuyển đổi ứng dụng gần đây và bóng thông báo khi PWA gửi thông báo đẩy web. Nó phải là PNG, có thể truy cập được tại URL đã khai báo mà không cần chuyển hướng và được cung cấp với các tiêu đề CORS thích hợp nếu nó nằm trên một miền khác với tệp kê khai của bạn. favicon generator xuất android-chrome-192x192.png sẵn sàng để sử dụng trực tiếp.
Biểu tượng 512×512 được sử dụng cho màn hình giới thiệu PWA hiển thị trong khi ứng dụng tải sau khi khởi chạy màn hình chính, bản xem trước hộp thoại cài đặt trong Chrome và Edge trên máy tính để bàn cũng như trình khởi chạy ứng dụng hệ điều hành Chrome. Mục nhập 512×512 bị thiếu trong tệp kê khai không chặn cài đặt nhưng dẫn đến biểu tượng trình duyệt chung trên màn hình chờ. Luôn bao gồm nó để có trải nghiệm cài đặt bóng bẩy.
Các biểu tượng có thể che được là một cải tiến dành riêng cho XXH0XX. Hệ thống biểu tượng thích ứng Android áp dụng mặt nạ hình học (hình tròn, hình tròn, hình giọt nước, hình chữ nhật tròn) cho các biểu tượng ứng dụng và hình dạng khác nhau tùy theo nhà sản xuất thiết bị. Biểu tượng 'bất kỳ' tiêu chuẩn có thể bị các cạnh của nó bị cắt bớt bởi các mặt nạ này. Biểu tượng 'có thể đeo mặt nạ' bao gồm phần đệm vùng an toàn - giữ tác phẩm nghệ thuật thiết yếu ở giữa 80% hình ảnh (vòng tròn vùng an toàn) - để có thể áp dụng bất kỳ mặt nạ nào mà không cần cắt bớt biểu tượng.
Để khai báo biểu tượng có thể che trong tệp kê khai, hãy thêm mục nhập thứ hai có cùng kích thước với `'purpose': 'maskable'`: `{ "src": "/android-chrome-512x512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }`. Bạn cũng có thể kết hợp: `'purpose': 'any maskable'` trên một mục. Tạo biểu tượng có thể che được của bạn với phần đệm bổ sung bằng cách sử dụng tùy chọn xuất có thể che được của trình tạo.
Các trường tên và short_name kiểm soát cách ứng dụng của bạn được gắn nhãn trên màn hình chính và trong ngăn kéo ứng dụng. `name` là tên ứng dụng đầy đủ được hiển thị trong lời nhắc cài đặt. `short_name` là nhãn bên dưới biểu tượng trên màn hình chính — hãy giữ nhãn dưới 12 ký tự để tránh bị cắt bớt trên màn hình nhỏ hơn. Cả hai trường đều được yêu cầu để lời nhắc cài đặt xuất hiện.
Trường theme_color đặt màu của thanh địa chỉ trình duyệt trên Android Chrome khi người dùng điều hướng đến trang web của bạn (không chỉ khi PWA được cài đặt). Nó cũng đặt màu thanh công cụ ở chế độ PWA độc lập. Sử dụng màu thương hiệu chính của bạn làm giá trị hex. Thêm `<meta name='theme-color' content='#YOUR_COLOR'>` phù hợp trong HTML của bạn cho các trình duyệt không đọc theme_color của tệp kê khai.
Trường color_color kiểm soát màu nền của màn hình chờ được hiển thị từ lần khởi chạy PWA đến lần sơn đầu tiên cho nội dung ứng dụng của bạn. Đặt màu này phù hợp với nền của ứng dụng (thường là màu trắng hoặc màu thương hiệu chính) để tránh ánh sáng chói lóa. Nếu nền_color không khớp với nền ứng dụng thực tế của bạn thì người dùng sẽ thấy màu nhảy trong khi khởi động.
Trường hiển thị xác định cách PWA xuất hiện sau khi cài đặt. `standalone` ẩn thanh địa chỉ trình duyệt và các nút điều hướng, làm cho ứng dụng trông giống như một ứng dụng gốc. `minimal-ui` giữ một thanh điều hướng tối thiểu. `fullscreen` xóa mọi thứ kể cả thanh trạng thái. `browser` hiển thị giao diện người dùng trình duyệt đầy đủ. Đối với hầu hết các PWA, `standalone` là lựa chọn chính xác. Lời nhắc cài đặt không xuất hiện nếu màn hình được đặt thành `browser`.
Trường start_url chỉ định URL nào sẽ mở khi người dùng khởi chạy PWA đã cài đặt từ màn hình chính. Luôn bao gồm phần này — nếu không có nó, Android sẽ mở URL nơi phát hiện tệp kê khai, URL này có thể là trang liên kết sâu chứ không phải trang chủ của bạn. Sử dụng `'start_url': '/'` cho hầu hết các trang web hoặc một URL cụ thể nếu ứng dụng của bạn cần bắt đầu ở một tuyến đường cụ thể.
Việc gỡ lỗi các vấn đề về bảng kê khai rất đơn giản trong Chrome DevTools. Mở DevTools (F12), điều hướng đến tab Ứng dụng và nhấp vào Bản kê khai ở bảng điều khiển bên trái. Chrome hiển thị chế độ xem được phân tích cú pháp của tệp kê khai, mọi lỗi phân tích cú pháp, lỗi tìm nạp biểu tượng và danh sách kiểm tra 'Khả năng cài đặt' giải thích lý do tại sao lời nhắc cài đặt có thể không hiển thị. Các sự cố thường gặp bao gồm không tìm thấy biểu tượng (404), loại MIME sai hoặc thiếu biểu tượng 192×192.
Việc cung cấp chính xác tệp kê khai yêu cầu hai cấu hình phía máy chủ. Đầu tiên, tệp phải được cung cấp với `Content-Type: application/manifest+json`. Thứ hai, nếu biểu tượng của bạn nằm trên CDN hoặc có nguồn gốc khác với tệp kê khai thì phản hồi biểu tượng phải bao gồm tiêu đề CORS thích hợp (`Access-Control-Allow-Origin: *` hoặc miền của bạn). Việc thiếu tiêu đề CORS trên tệp biểu tượng sẽ khiến trình duyệt coi tệp kê khai là không hợp lệ.
Đối với các khung tự động tạo tệp kê khai, hãy xác minh tệp được tạo có chứa kích thước và màu sắc biểu tượng thực tế của bạn. Next.js tạo một bảng kê khai từ quá trình xuất /app/manifest.ts của bạn. Tạo Ứng dụng React tạo ra /public/manifest.json. Vite không tạo tệp kê khai theo mặc định - hãy tạo tệp kê khai theo cách thủ công. Trong mọi trường hợp, hãy cập nhật mảng biểu tượng để tham chiếu các tệp biểu tượng được gắn thương hiệu thực tế của bạn thay vì các biểu tượng giữ chỗ mặc định.
Cách hoạt động
- 1
Tạo biểu tượng 192×192 và 512×512 PNG
Tải logo 512×512 PNG hoặc SVG của bạn lên [favicon generator](tool:favicon-generator). Gói tải xuống bao gồm android-chrome-192x192.png và android-chrome-512x512.png sẵn sàng để sử dụng trực tiếp.
- 2
Tạo site.webmanifest
Tạo tệp JSON có tối thiểu: `name`, `short_name`, `icons` (192 và 512 mục), `theme_color`, `background_color` và `display: 'standalone'`. Gói trình tạo bao gồm mẫu bảng kê khai được điền sẵn.
- 3
Phân phát tệp kê khai với loại MIME chính xác
Định cấu hình máy chủ của bạn để phân phát tệp .webmanifest với `Content-Type: application/manifest+json`. Trên Apache, thêm `AddType application/manifest+json .webmanifest` vào .htaccess. Trên Nginx, thêm loại MIME vào mime.types.
- 4
Liên kết tệp kê khai trong HTML
Thêm `<link rel='manifest' href='/site.webmanifest'>` bên trong `<head>` của bạn. Đồng thời thêm `<meta name='theme-color' content='#YOUR_COLOR'>` cho các trình duyệt không đọc tệp kê khai theme_color.
- 5
Xác minh bằng Chrome DevTools
Mở Chrome DevTools > Ứng dụng > Bản kê khai. Xác nhận không có lỗi nào được hiển thị và tất cả các biểu tượng đều được giải quyết. Kiểm tra phần Khả năng cài đặt để biết chính xác các tiêu chí đã đáp ứng hoặc chưa đáp ứng đối với lời nhắc cài đặt PWA.
- 6
Kiểm tra lời nhắc cài đặt
Trên Android Chrome, hãy điều hướng đến trang web của bạn. Nếu tất cả các tiêu chí đều được đáp ứng, Chrome sẽ hiển thị biểu ngữ cài đặt hoặc tùy chọn 'Thêm vào Màn hình chính' trong menu trình duyệt. Sau khi cài đặt, hãy xác minh màu nền của màn hình chờ và biểu tượng màn hình chính hiển thị chính xác.
Thử ngay
Tạo gói biểu tượng PWA của bạn
Tạo FaviconCâu hỏi thường gặp
Một bảng kê khai ứng dụng web có cần thiết cho một trang web cơ bản không?+
Không — chỉ khi bạn muốn lời nhắc cài đặt PWA vào màn hình chính trên Android và Chrome/Edge trên máy tính để bàn. favicon.ico một mình xử lý các tab trình duyệt. Thêm tệp kê khai khi bạn muốn mang lại trải nghiệm cài đặt trên thiết bị di động và máy tính để bàn phong phú hơn.
Kích thước biểu tượng nào có trong bảng kê khai ứng dụng web?+
Tối thiểu: 192×192 (trình khởi chạy Android) và 512×512 (màn hình giật gân và bản xem trước cài đặt). Thêm các biến thể có thể che được của cả hai kích thước để hỗ trợ biểu tượng Android thích ứng và 384×384 nếu bạn muốn có phạm vi phủ sóng mật độ bổ sung.
Sự khác biệt giữa theme_color và background_color trong tệp kê khai là gì?+
theme_color đặt màu thanh địa chỉ và thanh công cụ của trình duyệt. Background_color đặt màu nền của màn hình giật gân hiển thị trước lần sơn đầu tiên của ứng dụng. Đặt cả hai để phù hợp với thương hiệu của bạn để có trải nghiệm cài đặt và khởi chạy liền mạch.
Tại sao Chrome không hiển thị lời nhắc cài đặt cho XXH1XX của tôi?+
Các lý do phổ biến nhất là: tệp kê khai bị thiếu hoặc không hợp lệ, thiếu biểu tượng 192×192, biểu tượng trả về 404, tệp kê khai không được cung cấp đúng loại MIME hoặc trang web không được cung cấp qua HTTPS. Sử dụng Chrome DevTools > Ứng dụng > Bản kê khai để xem lý do lỗi cài đặt chính xác.
Biểu tượng có thể che được là gì và tôi có cần một biểu tượng không?+
Biểu tượng có thể che được bao gồm phần đệm vùng an toàn để Android có thể áp dụng mặt nạ hình tròn hoặc hình tròn mà không cần cắt bớt biểu trưng của bạn. Bạn cần một biểu tượng trên màn hình chính để trông chính xác trên các thiết bị Android sử dụng hình dạng biểu tượng thích ứng không vuông. Khai báo nó bằng `'purpose': 'maskable'` trong mảng biểu tượng tệp kê khai.
Tôi có thể sử dụng biểu tượng SVG trong bảng kê khai ứng dụng web không?+
Chrome hỗ trợ SVG trong một số ngữ cảnh biểu tượng tệp kê khai, nhưng PNG là mặc định an toàn chung cho giao diện người dùng cài đặt trên nhiều trình duyệt. Luôn bao gồm các mục PNG 192 và 512. Bạn có thể thêm mục SVG bên cạnh chúng mà không gây hại gì.
Làm cách nào để kiểm tra xem bảng kê khai web của tôi có hợp lệ không?+
Mở Chrome DevTools (F12) > Ứng dụng > Bản kê khai. Chrome hiển thị lỗi phân tích cú pháp, lỗi tìm nạp biểu tượng và danh sách kiểm tra khả năng cài đặt hoàn chỉnh. Khắc phục mọi sự cố được báo cáo, sau đó kiểm tra lại lời nhắc cài đặt bằng cách sử dụng tùy chọn 'Thêm vào Màn hình chính' từ thanh địa chỉ của Chrome.