คู่มือรายการ Web App
รายการแอปพลิเคชันบนเว็บ (site.webmanifest) คือไฟล์ JSON ที่บอกเบราว์เซอร์ที่ติดตั้งได้เกี่ยวกับชื่อแอป สี โหมดการแสดงผล และขนาดไอคอนที่จะใช้บนหน้าจอหลัก การเชื่อมโยงกับ `<link rel='manifest' href='/site.webmanifest'>` จะเปิดใช้งานพร้อมท์การติดตั้ง Chrome และ Edge PWA บนเดสก์ท็อปและ Android จับคู่กับไอคอน 192×192 และ 512×512 PNG — ทั้งคู่ส่งออกโดย favicon generator — เพื่อให้การตั้งค่า favicon ของ PWA สมบูรณ์
ไฟล์ Manifest ของเว็บแอปคือไฟล์ข้อความ JSON ที่ใช้ประเภท `application/manifest+json` MIME โดยจะอยู่ที่ URL ใดๆ ที่คุณเลือก แต่แบบแผนคือ /site.webmanifest ที่รูทโดเมน คุณลิงก์จาก HTML ของคุณโดยใช้ `<link rel='manifest' href='/site.webmanifest'>` ภายในองค์ประกอบ `<head>` เบราว์เซอร์จะอ่านไฟล์ Manifest เมื่อกำลังประเมินว่าจะแสดงข้อความแจ้งการติดตั้งหรือวิธีแสดงผลแอปของคุณหลังการติดตั้ง
อาร์เรย์ไอคอนเป็นส่วนที่เกี่ยวข้องกับ favicon ที่สุดของรายการ แต่ละรายการจะระบุ src (URL ของรูปภาพ) ขนาด (ขนาดพิกเซล) ประเภท (ประเภท MIME) และวัตถุประสงค์ที่ไม่บังคับ (อาจเป็น 'ใดๆ', 'maskable' หรือ 'ใดๆ ที่ปกปิดได้') อย่างน้อยที่สุด ให้ระบุ 192×192 PNG สำหรับไอคอน Launcher และ 512×512 PNG สำหรับหน้าจอเริ่มต้น หากไม่มีสิ่งเหล่านี้ Chrome จะไม่แสดงพร้อมท์การติดตั้ง
Android Chrome ใช้ไอคอน 192×192 ในตัวเปิดแอป ตัวสลับแอปล่าสุด และหน้าต่างแจ้งเตือนเมื่อ PWA ของคุณส่งการแจ้งเตือนแบบพุชบนเว็บ ต้องเป็น PNG ซึ่งสามารถเข้าถึงได้จาก URL ที่ประกาศโดยไม่มีการเปลี่ยนเส้นทาง และแสดงพร้อมกับส่วนหัว CORS ที่เหมาะสม หากอยู่ในโดเมนอื่นจากรายการของคุณ favicon generator ส่งออก android-chrome-192x192.png พร้อมใช้งานโดยตรง
ไอคอน 512×512 ใช้สำหรับหน้าจอเริ่มต้น PWA ที่แสดงในขณะที่แอปโหลดหลังจากเปิดหน้าจอหลัก การแสดงตัวอย่างกล่องโต้ตอบการติดตั้งใน Chrome และ Edge บนเดสก์ท็อป และเครื่องเรียกใช้งานแอป Chrome OS รายการขนาด 512×512 ที่ขาดหายไปในรายการไม่ได้บล็อกการติดตั้ง แต่ส่งผลให้มีไอคอนเบราว์เซอร์ทั่วไปบนหน้าจอสแปลช รวมไว้เสมอเพื่อประสบการณ์การติดตั้งที่สวยงาม
ไอคอนที่ปิดบังได้เป็นการปรับปรุงเฉพาะของ Android ระบบไอคอนแบบปรับได้ Android ใช้มาสก์เรขาคณิต (วงกลม วงกลม หยดน้ำ สี่เหลี่ยมผืนผ้าโค้งมน) กับไอคอนแอป และรูปร่างจะแตกต่างกันไปตามผู้ผลิตอุปกรณ์ ไอคอน 'ใดๆ' มาตรฐานอาจมีขอบถูกตัดโดยมาสก์เหล่านี้ ไอคอน 'maskable' มีช่องว่างภายในโซนปลอดภัย — เก็บอาร์ตเวิร์กที่สำคัญไว้ตรงกลาง 80% ของรูปภาพ (วงกลมโซนปลอดภัย) — เพื่อให้สามารถใช้มาสก์ใดๆ ได้โดยไม่ต้องตัดโลโก้
หากต้องการประกาศไอคอนที่ปกปิดได้ในรายการ ให้เพิ่มรายการที่สองสำหรับขนาดเดียวกันด้วย `'purpose': 'maskable'`: `{ "src": "/android-chrome-512x512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }` คุณยังสามารถรวม: `'purpose': 'any maskable'` ไว้ในรายการเดียวได้ สร้างไอคอนที่มาสก์ได้ด้วยการเสริมพิเศษโดยใช้ตัวเลือกการส่งออกที่มาสก์ได้ของตัวสร้าง
ช่องชื่อและชื่อย่อจะควบคุมวิธีการติดป้ายกำกับแอปของคุณบนหน้าจอหลักและในลิ้นชักแอป `name` คือชื่อแอปแบบเต็มที่แสดงระหว่างข้อความแจ้งการติดตั้ง `short_name` คือป้ายกำกับใต้ไอคอนบนหน้าจอหลัก โปรดมีความยาวไม่เกิน 12 อักขระเพื่อหลีกเลี่ยงการตัดทอนบนหน้าจอขนาดเล็ก ต้องระบุทั้งสองช่องเพื่อให้ข้อความแจ้งการติดตั้งปรากฏขึ้น
ฟิลด์ theme_color จะกำหนดสีของแถบที่อยู่ของเบราว์เซอร์บน Android Chrome เมื่อผู้ใช้นำทางไปยังไซต์ของคุณ (ไม่ใช่แค่เมื่อมีการติดตั้ง PWA) นอกจากนี้ยังตั้งค่าสีของแถบเครื่องมือในโหมด PWA แบบสแตนด์อโลน ใช้สีหลักของแบรนด์เป็นค่าฐานสิบหก เพิ่ม `<meta name='theme-color' content='#YOUR_COLOR'>` ที่ตรงกันใน HTML ของคุณสำหรับเบราว์เซอร์ที่ไม่ได้อ่าน theme_color ของไฟล์ Manifest
ช่องสีพื้นหลังจะควบคุมสีพื้นหลังของหน้าจอเริ่มต้นที่แสดงระหว่างการเปิดตัว PWA และสีแรกของเนื้อหาแอปของคุณ ตั้งค่าให้ตรงกับพื้นหลังของแอป (โดยปกติจะเป็นสีขาวหรือสีหลักของแบรนด์) เพื่อป้องกันไม่ให้เกิดภาพสั่นไหว หาก background_color ไม่ตรงกับพื้นหลังแอปจริงของคุณ ผู้ใช้จะเห็นการเปลี่ยนสีระหว่างการเริ่มต้นระบบ
ฟิลด์แสดงผลจะกำหนดลักษณะที่ PWA จะปรากฏหลังการติดตั้ง `standalone` ซ่อนแถบที่อยู่ของเบราว์เซอร์และปุ่มนำทาง ทำให้แอปดูเหมือนแอปเนทีฟ `minimal-ui` เก็บแถบนำทางให้น้อยที่สุด `fullscreen` ลบทุกอย่างรวมถึงแถบสถานะด้วย `browser` แสดง UI เบราว์เซอร์เต็มรูปแบบ สำหรับ PWA ส่วนใหญ่ `standalone` คือตัวเลือกที่ถูกต้อง ข้อความแจ้งการติดตั้งจะไม่ปรากฏขึ้นหากตั้งค่าจอแสดงผลเป็น `browser`
ฟิลด์ start_url ระบุว่า URL ใดจะเปิดเมื่อผู้ใช้เปิด PWA ที่ติดตั้งจากหน้าจอหลัก รวมสิ่งนี้ไว้เสมอ หากไม่มี Android จะเปิด URL ที่พบไฟล์ Manifest ซึ่งอาจเป็นหน้าลิงก์ในรายละเอียดแทนที่จะเป็นหน้าแรกของคุณ ใช้ `'start_url': '/'` สำหรับเว็บไซต์ส่วนใหญ่ หรือใช้ URL เฉพาะหากแอปของคุณจำเป็นต้องเริ่มต้นในเส้นทางใดเส้นทางหนึ่ง
การแก้ไขจุดบกพร่องปัญหารายการนั้นตรงไปตรงมาใน Chrome DevTools เปิด DevTools (F12) ไปที่แท็บ Application แล้วคลิก Manifest ในแผงด้านซ้าย Chrome แสดงมุมมองแบบแยกวิเคราะห์ของไฟล์ Manifest ของคุณ ข้อผิดพลาดในการแยกวิเคราะห์ การดึงข้อมูลไอคอนล้มเหลว และรายการตรวจสอบ 'ความสามารถในการติดตั้ง' ที่อธิบายสาเหตุที่ข้อความแจ้งการติดตั้งอาจไม่แสดง ปัญหาทั่วไป ได้แก่ ไม่พบไอคอน (404) ประเภท MIME ไม่ถูกต้อง หรือไอคอนขนาด 192×192 หายไป
การแสดงไฟล์ Manifest อย่างถูกต้องจำเป็นต้องมีการกำหนดค่าฝั่งเซิร์ฟเวอร์ 2 รายการ ขั้นแรก ไฟล์จะต้องให้บริการด้วย `Content-Type: application/manifest+json` ประการที่สอง หากไอคอนของคุณอยู่บน CDN หรือแหล่งที่มาที่แตกต่างจากไฟล์ Manifest การตอบกลับของไอคอนจะต้องมีส่วนหัว CORS ที่เหมาะสม (`Access-Control-Allow-Origin: *` หรือโดเมนของคุณ) ส่วนหัว CORS ที่หายไปในไฟล์ไอคอนจะทำให้เบราว์เซอร์ถือว่าไฟล์ Manifest ไม่ถูกต้อง
สำหรับเฟรมเวิร์กที่สร้างรายการโดยอัตโนมัติ ให้ตรวจสอบว่าไฟล์ที่สร้างขึ้นมีขนาดและสีไอคอนตามจริงของคุณ Next.js สร้างรายการจากการส่งออก /app/manifest.ts ของคุณ สร้างแอป React สร้าง /public/manifest.json Vite จะไม่สร้างรายการตามค่าเริ่มต้น — สร้างรายการด้วยตนเอง ในทุกกรณี ให้อัปเดตอาร์เรย์ไอคอนเพื่ออ้างอิงไฟล์ไอคอนแบรนด์จริงของคุณ แทนที่จะอัปเดตไอคอนตัวยึดเริ่มต้น
วิธีการทำงาน
- 1
สร้างไอคอน 192×192 และ 512×512 PNG
อัปโหลดโลโก้ 512×512 ของคุณ PNG หรือ SVG ไปที่ [favicon generator](tool:favicon-generator) แพ็คเกจดาวน์โหลดประกอบด้วย android-chrome-192x192.png และ android-chrome-512x512.png ที่พร้อมใช้งานโดยตรง
- 2
สร้าง site.webmanifest
สร้างไฟล์ JSON ที่มีขั้นต่ำ: `name`, `short_name`, `icons` (192 และ 512 รายการ), `theme_color`, `background_color` และ `display: 'standalone'` แพ็คเกจตัวสร้างมีเทมเพลตรายการข้อมูลที่กรอกไว้ล่วงหน้า
- 3
แสดงรายการด้วยประเภท MIME ที่ถูกต้อง
กำหนดค่าเซิร์ฟเวอร์ของคุณให้ให้บริการไฟล์ .webmanifest ด้วย `Content-Type: application/manifest+json` บน Apache ให้เพิ่ม `AddType application/manifest+json .webmanifest` ลงใน .htaccess บน Nginx ให้เพิ่มประเภท MIME ลงใน mime.types
- 4
เชื่อมโยงรายการใน HTML
เพิ่ม `<link rel='manifest' href='/site.webmanifest'>` ไว้ใน `<head>` ของคุณ นอกจากนี้ ให้เพิ่ม `<meta name='theme-color' content='#YOUR_COLOR'>` สำหรับเบราว์เซอร์ที่ไม่อ่านไฟล์ Manifest theme_color
- 5
ยืนยันด้วย Chrome DevTools
เปิด Chrome DevTools > แอปพลิเคชัน > รายการ ยืนยันว่าไม่มีการแสดงข้อผิดพลาดและไอคอนทั้งหมดได้รับการแก้ไข ตรวจสอบส่วนความสามารถในการติดตั้งเพื่อดูเกณฑ์ที่ตรงตามหรือไม่ตรงตามพร้อมท์การติดตั้ง PWA
- 6
ทดสอบพร้อมท์การติดตั้ง
บน Android Chrome ให้นำทางไปยังไซต์ของคุณ หากตรงตามเกณฑ์ทั้งหมด Chrome จะแสดงแบนเนอร์การติดตั้งหรือตัวเลือก "เพิ่มไปที่หน้าจอหลัก" ในเมนูเบราว์เซอร์ หลังการติดตั้ง ให้ตรวจสอบสีพื้นหลังของหน้าจอสแปลชและไอคอนหน้าจอหลักที่แสดงผลอย่างถูกต้อง
ลองเลย
สร้างแพ็คเกจไอคอน PWA ของคุณ
เครื่องมือสร้าง Faviconคำถามที่พบบ่อย
จำเป็นต้องมีรายการแอปพลิเคชันเว็บสำหรับเว็บไซต์พื้นฐานหรือไม่+
ไม่ เฉพาะในกรณีที่คุณต้องการข้อความแจ้งการติดตั้งไปที่หน้าจอหลัก PWA บน Android และเดสก์ท็อป Chrome/Edge favicon.ico เพียงอย่างเดียวจัดการแท็บเบราว์เซอร์ เพิ่มรายการเมื่อคุณต้องการเปิดใช้งานประสบการณ์การติดตั้งบนมือถือและเดสก์ท็อปที่สมบูรณ์ยิ่งขึ้น
ขนาดไอคอนใดในรายการแอปพลิเคชันเว็บ+
ขั้นต่ำ: 192×192 (ตัวเรียกใช้งาน Android) และ 512×512 (หน้าจอเริ่มต้นและดูตัวอย่างการติดตั้ง) เพิ่มรูปแบบที่มาสก์ได้ทั้งสองขนาดเพื่อรองรับไอคอน Android ที่ปรับเปลี่ยนได้ และ 384×384 หากคุณต้องการการครอบคลุมความหนาแน่นเพิ่มเติม
อะไรคือความแตกต่างระหว่าง theme_color และ background_color ในรายการ?+
theme_color ตั้งค่าแถบที่อยู่ของเบราว์เซอร์และสีของแถบเครื่องมือ background_color ตั้งค่าสีพื้นหลังของหน้าจอสแปลชที่แสดงก่อนการเพ้นท์แรกของแอปของคุณ ตั้งค่าทั้งสองอย่างให้ตรงกับแบรนด์ของคุณเพื่อประสบการณ์การติดตั้งและการเปิดตัวที่ราบรื่น
เหตุใด Chrome จึงไม่แสดงพร้อมท์การติดตั้งสำหรับ PWA ของฉัน+
สาเหตุที่พบบ่อยที่สุด ได้แก่: ไฟล์ Manifest หายไปหรือไม่ถูกต้อง, ไอคอน 192×192 หายไป, ไอคอนส่งคืน 404, ไฟล์ Manifest ไม่แสดงด้วยประเภท MIME ที่ถูกต้อง หรือเว็บไซต์ไม่ได้ให้บริการผ่าน HTTPS ใช้ Chrome DevTools > Application > Manifest เพื่อดูสาเหตุของความล้มเหลวในการติดตั้งที่แน่นอน
ไอคอนที่ปกปิดได้คืออะไร และฉันจำเป็นต้องมีหรือไม่+
ไอคอนที่ปิดบังได้มีช่องว่างภายในโซนปลอดภัย ดังนั้น Android สามารถใช้มาสก์ทรงกลมหรือวงกลมโดยไม่ต้องตัดโลโก้ของคุณ คุณต้องมีไอคอนหนึ่งอันเพื่อให้ไอคอนบนหน้าจอหลักของคุณดูถูกต้องบนอุปกรณ์ Android ที่ใช้รูปร่างไอคอนแบบปรับเปลี่ยนได้ที่ไม่ใช่สี่เหลี่ยมจัตุรัส ประกาศด้วย `'purpose': 'maskable'` ในอาร์เรย์ไอคอนรายการ
ฉันสามารถใช้ไอคอน SVG ในรายการเว็บแอปได้หรือไม่+
Chromium รองรับ SVG ในบริบทของไอคอนรายการบางส่วน แต่ PNG เป็นค่าเริ่มต้นที่ปลอดภัยในระดับสากลสำหรับ UI การติดตั้งข้ามเบราว์เซอร์ รวมรายการ PNG 192 และ 512 เสมอ คุณสามารถเพิ่มรายการ SVG ข้างๆ รายการได้โดยไม่มีอันตรายใดๆ
ฉันจะตรวจสอบได้อย่างไรว่ารายการเว็บของฉันถูกต้องหรือไม่+
เปิด Chrome DevTools (F12) > แอปพลิเคชัน > รายการ Chrome แสดงข้อผิดพลาดในการแยกวิเคราะห์ ความล้มเหลวในการดึงไอคอน และรายการตรวจสอบความสามารถในการติดตั้งทั้งหมด แก้ไขปัญหาที่ได้รับรายงาน จากนั้นทดสอบพรอมต์การติดตั้งอีกครั้งโดยใช้ตัวเลือก "เพิ่มไปที่หน้าจอหลัก" จากแถบที่อยู่ของ Chrome