ไฟล์ Manifest ของเว็บแอปคือไฟล์ JSON ที่บอกเบราว์เซอร์ว่า Progressive Web App (PWA) ควรทำงานอย่างไรเมื่อติดตั้งในเดสก์ท็อปห��ืออุปกรณ์เคลื่อนที่ของผู้ใช้ อย่างน้อยที่สุด ไฟล์ Manifest โดยทั่วไปจะมีสิ่งต่อไปนี้
- ชื่อแอป
- ไอคอนที่แอปควรใช้
- URL ที่ควรเปิดเมื่อเปิดแอป
สร้างไฟล์ Manifest
ไฟล์ Manifest อาจมีชื่ออะไรก็ได้ แต่มักจะมีชื่อว่า manifest.json
และแสดงจากรูท (ไดเรกทอรีระดับบนสุดของเว็บไซต์) ข้อกำหนดระบุว่าส่วนขยายควรเป็น .webmanifest
แต่คุณอาจต้องใช้ไฟล์ JSON เพื่อทำให้ไฟล์ Manifest อ่านชัดเจนขึ้น
ไฟล์ Manifest ทั่วไปจะมีลักษณะดังนี้
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
พร็อพเพอร์ตี้หลักของไฟล์ Manifest
short_name
และname
คุณต้องระบุ short_name
หรือ name
อย่างน้อย 1 รายการในไฟล์ Manifest หากคุณระบุไว้ทั้ง 2 อย่าง ระบบจะใช้ name
เมื่อติดตั้งแอป และใช้ short_name
ในหน้าจอหลัก, Launcher หรือที่อื่นๆ ที่มีจำกัดพื้นที่
icons
เมื่อผู้ใช้ติดตั้ง PWA คุณจะกำหนดชุดไอคอนสำหรับเบราว์เซอร์เพื่อใช้ในหน้าจอหลัก, ตัวเปิดแอป, ตัวสลับงาน, หน้าจอแนะนำ และที่อื่นๆ ได้
พร็อพเพอร์ตี้ icons
คืออาร์เรย์ของออบเจ็กต์รูปภาพ แต่ละออบเจ็กต์ต้องมี src
, พร็อพเพอร์ตี้ sizes
และ type
ของรูปภาพ หากต้องการใช้ไอคอนที่มาสก์ได้ หรือที่บางครั้งเรียกว่าไอคอนแบบปรับอัตโนมัติใน Android ให้เพิ่ม "purpose": "any maskable"
ลงในพร็อพเพอร์ตี้ icon
สำหรับ Chromium คุณต้องระบุไอคอนขนาด 192x192 พิกเซลและไอคอนขนาด 512x512 พิกเซลเป็นอย่างน้อย หากไอคอนมีแค่ 2 ขนาดเท่านั้น Chrome จะปรับขนาดไอคอนให้พอดีกับอุปกรณ์โดยอัตโนมัติ หากต้องการปรับขนาดไอคอนของคุณเอง และปรับให้สมบูรณ์แบบของพิกเซล ให้ระบุไอคอนทีละน้อยครั้งละ 48 dp
id
พร็อพเพอร์ตี้ id
ช่วยให้คุณกำหนดตัวระบุที่ใช้สำหรับแอปพลิเคชันได้อย่างชัดเจน การเพิ่มพร็อพเพอร์ตี้ id
ลงในไฟล์ Manifest จะเป็นการนำทรัพยากร Dependency ของ start_url
หรือตำแหน่งของไฟล์ Manifest ออก และช่วยให้คุณอัปเดตได้ในอนาคต ดูข้อมูลเพิ่มเติมได้ที่การระบุ PWA แบบไม่ซ้ำด้วยพร็อพเพอร์ตี้รหัสไฟล์ Manifest ของเว็บแอป
start_url
start_url
เป็นพร็อพเพอร์ตี้ที่จำเป็น ซึ่งจะบอกเบราว์เซอร์ว่าแอปควรจะเริ่มต้นที่ใดเมื่อเปิดขึ้นมา และป้องกันไม่ให้แอปเริ่มต้นในหน้าใดก็ตามที่ผู้ใช้อยู่เมื่อผู้ใช้เพิ่มแอปลงในหน้าจอหลัก
start_url
ควรนำผู้ใช้ไปยังแอปของคุณโดยตรง ไม่ใช่หน้า Landing Page ของผลิตภัณฑ์ นึกถึงสิ่งที่ผู้ใช้ต้องการทำทันทีหลังจาก
เปิดแอปของคุณ และวางผู้ใช้ไว้ที่นั่น
background_color
ระบบจะใช้พร็อพเพอร์ตี้ background_color
ในหน้าจอแนะนำเมื่อแอปพลิเคชันเปิดใช้งานบนอุปกรณ์เคลื่อนที่เป็นครั้งแรก
display
คุณปรับแต่ง UI ของเบราว์เซอร์ที่จะแสดงได้เมื่อเปิดแอป เช่น คุณซ่อนแถบที่อยู่และองค์ประกอบอินเทอร์เฟซผู้ใช้ของเบราว์เซอร์ได้ นอกจากนี้ยังสามารถทำเกมให้เปิด
แบบเต็มหน้าจอได้อีกด้วย พร็อพเพอร์ตี้ display
จะใช้ค่าใดค่าหนึ่งต่อไปนี้
พร็อพเพอร์ตี้ | ลักษณะการทำงาน |
---|---|
fullscreen |
เปิดเว็บแอปโดยไม่มี UI ของเบราว์เซอร์และกินพื้นที่แสดงผลที่มีอยู่ทั้งหมด |
standalone |
เปิดเว็บแอปให้มีรูปลักษณ์เหมือนแอปแบบสแตนด์อโลน แอปจะทำงานในหน้าต่างของตัวเองโดยแยกจากเบราว์เซอร์ และซ่อนองค์ประกอบ UI มาตรฐานของ���บราว์เซอร์ เช่น แถบที่อยู่ |
minimal-ui |
โหมดนี้คล้ายกับ standalone แต่จะมอบชุดองค์ประกอบ UI แบบเรียบง่ายแก่ผู้ใช้สำหรับควบคุมการนำทาง เช่น ปุ่มย้อนกลับและปุ่มโหลดซ้ำ
|
browser |
ประสบการณ์การใช้งานเบราว์เซอร์มาตรฐาน |
display_override
หากต้องการเลือกวิธีแสดงเว็บแอป ให้ตั้งค่าโหมด display
ในไฟล์ Manifest ตามที่อธิบายไว้ก่อนหน้านี้ เบราว์เซอร์ไม่จำเป็นต้องรองรับโหมดการแสดงผลทุกโหมด แต่จำเป็นจะต้องรองรับเชนสำรองที่กำหนดโดยข้อกำหนด
("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
) หากแต่ละโหมดไม่รองรับโหมดการแสดงผล ผู้ใช้จะกลับไปใช้โหมดการแสดงผลถัดไปในเชน ในบางกรณีที่เกิดขึ้นไม่บ่อยนัก การใช้วิดีโอสำรองเหล่านี้อาจทำให้เกิดปัญหาได้ เช่น นักพัฒนาซอฟต์แวร์จะขอ "minimal-ui"
ไม่ได้หากไม่มีการบังคับให้กลับสู่โหมดการแสดงผล "browser"
เมื่อระบบไม่รองรับ "minimal-ui"
ลักษณะการทำงานในปัจจุบันยังทำให้ไม่สามารถแนะนำโหมดการแสดงผลใหม่ในรูปแบบที่เข้ากันได้แบบย้อนหลังได้ เนื่องจากโหมดดังกล่าวไม่มีตำแหน่งอยู่ในเชนโฆษณาสำรอง
คุณสามารถตั้งค่าลำดับสำรองของตั���เองโดยใช้พร็อพเพอร์ตี้ display_override
ซึ่งเบราว์เซอร์จะพิจารณาก่อนพร็อพเพอร์ตี้ display
ค่าของสตริงดังกล่าวเป็นลำดับสตริงที่จะได้รับการพิจารณาตามลำดับที่ระบุไว้ และมีการใช้โหมดการแสดงผลแรกที่รองรับ หากไม่มีการรองรับเลย เบราว์เซอร์จะกลับไปประเมินช่อง display
หากไม่มีช่อง display
เบราว์เซอร์จะไม่สนใจ display_override
ตัวอย่างวิธีใช้ display_override
มีดังนี้ รายละเอียดของ "window-control-overlay"
อยู่นอกขอบเขตของหน้านี้
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
เมื่อโหลดแอปนี้ เบราว์เซอร์จะพยายามใช้ "window-control-overlay"
ก่อน หากไม่พร้อมใช้งาน ค่าจะกลับไปเป็น "minimal-ui"
และกลับไปเป็น "standalone"
จากพร็อพเพอร์ตี้ display
หากไม่มีตัวเลือกที่กล่าวมาเลย เบราว์เซอร์จะกลับไปใช้เชนโฆษณาสำรองแบบมาตรฐาน
scope
scope
ของแอปคือชุด URL ที่เบราว์เซอร์ถือว่าเป็นส่วนหนึ่งของแอป โดย scope
จะควบคุมโครงสร้าง URL ที่รวมจุดเข้าและออกทั้งหมดไปยังแอป และเบราว์เซอร์จะใช้เพื่อระบุเวลาที่ผู้ใช้ออกจากแอป
หมายเหตุอื่นๆ เกี่ยวกับ scope
:
- หากคุณไม่รวม
scope
ในไฟล์ Manifest ค่าเริ่มต้นของscope
โดยนัยจะเป็น URL เริ่มต้น แต่นำชื่อไฟล์ คำค้นหา และส่วนย่อยออกแล้ว - แอตทริบิวต์
scope
อาจเป็นเส้นทางแบบสัมพัทธ์ (../
) หรือเส้นทางระดับสูงกว่า (/
) ที่ช่วยให้มีความครอบคลุมของการไปยังส่วนต่างๆ ในเว็บแอปเพิ่มขึ้น start_url
ต��องอยู่ในขอบเขตstart_url
สัมพันธ์กับเส้นทางที่กำหนดไว้ในแอตทริบิวต์scope
start_url
ที่ขึ้นต้นด้วย/
จะเป็นรูทของต้นทางเสมอ
theme_color
theme_color
จะกำหนดสีของแถบเครื่องมือ และสามารถแ��ดงในตัวอย่างของแอปในตัวสลับงานได้ theme_color
ควรตรงกับสีธีม meta
ที่ระบุในส่วนหัวของเอกสาร
theme_color
ในคำค้นหาสื่อ
คุณปรับ theme_color
ในการค้นหาสื่อได้โดยใช้แอตทริบิวต์ media
ขององค์ประกอบสีธีม meta
ตัวอย่างเช่น คุณจะกำหนดสีหนึ่งสำหรับโหมดสว่าง
และอีกสีหนึ่งสำหรับโหมดมืดด้วยวิธีนี้ แต่คุณจะกำหนดค่ากำหนดเหล่านี้ในไฟล์ Manifest ไม่ได้ ดูข้อมูลเพิ่มเติมได้ที่ปัญหา w3c/manifest#975 ใน GitHub
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
พร็อพเพอร์ตี้ shortcuts
คืออาร์เรย์ของออบเจ็กต์ทางลัดของแอปที่ให้คุณเข้าถึงงานสำคัญภายในแอปได้อย่างรวดเร็ว สมาชิกแต่ละคนจะเป็นพจนานุกรมที่มี name
และ url
เป็นอย่างน้อย
description
พร็อพเพอร์ตี้ description
อธิบายวัตถุประสงค์ของแอป
คำอธิบายใน Chrome จะมีความยาวสูงสุดอยู่ที่ 300 อักขระในทุกแพลตฟอร์ม หากคำอธิบายยาวกว่านั้น เบราว์เซอร์จะตัดคำอธิบายด้วยอักขระจุดไข่ปลา บน Android ���ำอธิบายต้องใช้ข้อความไม่เกิน 7 บรรทัด
screenshots
พร็อพเพอร์ตี้ screenshots
คืออาร์เรย์ของออบเจ็กต์รูปภาพที่แสดงถึงแอปของคุณในสถานการณ์การใช้งานทั่วไป แต่ละออบเจ็กต์ต้องมี src
, พร็อพเพอร์ตี้ sizes
และ type
ของรูปภาพ พร็อพเพอร์ตี้ form_factor
เป็นพร็อพเพอร์ตี้ที่ไม่บังคับ
คุณจะตั้งค่าเป็น "wide"
สำหรับภาพหน้าจอที่ใช้ได้กับหน้าจอกว้างเท่านั้น หรือ "narrow"
สำหรับภาพหน้าจอแบบแคบเท่านั้น
ใน Chrome รูปภาพต้องเป็นไปตามเกณฑ์ต่อไปนี้
- ความกว้างและความสูงอย่างน้อย 320 พิกเซลและไม่เกิน 3840 พิกเซล
- ขนาดสูงสุดต้องไม่เกิน 2.3 เท่าของความยาวของมิติข้อมูลขั้นต่ำ
- ภาพหน้าจอทั้งหมดที่ตรงกับรูปแบบของอุปกรณ์ที่เหมาะสมจะต้องมีสัดส่วนภาพเท่ากัน
- จาก Chrome 109 เฉพาะภาพหน้าจอที่กำหนด
form_factor
เป็น"wide"
เท่านั้นที่จะปรากฏบนเดสก์ท็อป
- จาก Chrome 109 เฉพาะภาพหน้าจอที่กำหนด
- จาก Chrome 109 ระบบจะไม่สนใจภาพหน้าจอที่มีการตั้งค่า
form_factor
เป็น"wide"
ใน Android ภาพหน้าจอที่ไม่มีform_factor
จะยังคงแสดงอยู่เพื่อ ความเข้ากันได้แบบย้อนหลัง
Chrome บนเดสก์ท็อปจะแสดงภาพหน้าจออย่างน้อย 1 ภาพและไม่เกิน 8 ภาพที่ตรงกับเกณฑ์เหล่านี้ โดยจะไม่สนใจภาพที่เหลือ
Chrome ใน Android จะแสดงภาพหน้าจออย่างน้อย 1 ภาพและไม่เกิน 5 ภาพที่ตรงกับเกณฑ์เหล่านี้ โดยจะไม่สนใจภาพที่เหลือ
เพิ่มไฟล์ Manifest ของเว็บแอปลงในหน้าเว็บ
หลังจากสร้างไฟล์ Manifest แล้ว ให้เพิ่มแท็ก <link>
ลงในทุกหน้าของ Progressive Web App เช่น
<link rel="manifest" href="/manifest.json">
ทดสอบไฟล์ Manifest
หากต้องการยืนยันว่าไฟล์ Manifest ได้รับการตั้งค่าอย่างถูกต้อง ให้ใช้แผงไฟล์ Manifest ในแผงแอปพลิเคชันของ Chrome DevTools
แผงนี้มีพร็อพเพอร์ตี้หลายรายการของไฟล์ Manifest ในเวอร์ชันที่มนุษย์อ่านได้ และช่วยให้คุณยืนยันว่ารูปภาพทั้งหมดโหลดอย่างถูกต้อง
หน้าจอแนะนำบนอุปกรณ์เคลื่อนที่
เมื่อเปิดแอปในอุปกรณ์เคลื่อนที่เป็นครั้งแรก เบราว์เซอร์อาจใช้เวลาสักครู่จึงจะเริ่มทำงานและเนื้อหาเริ่มต��นจะเริ่มแสดงผล แทนที่จะแสดงหน้าจอสีขาวที่อาจทำให้ผู้ใช้คิดว่าแอปไม่ทำงาน เบราว์เซอร์จะแสดงหน้าจอแนะนำจนกว่าจะลงสีครั้งแรก
Chrome จะสร้างหน้าจอแนะนำโดยอัตโนมัติจาก name
, background_color
และ icons
ที่ระบุไว้ในไฟล์ Manifest หากต้องการสร้างการเปลี่ยนจากหน้าจอแนะนำไปยังแอปอย่างราบรื่น ให้กำหนดbackground_color
สีเดียวกับหน้าโหลด
Chrome จะเลือกไอคอนที่ตรงกับความละเอียดของอุปกรณ์มากที่สุดสำหรับหน้าจอแนะนำ การระบุไอคอนขนาด 192 พิกเซล และ 512 พิกเซลก็เพียงพอแล้วสำหรับกรณีส่วนใหญ่ แต่คุณอาจเพิ่มไอคอนอีกเพื่อการจับคู่ที่ดีขึ้นได้
อ่านเพิ่มเติม
หากต้องการดูข้อมูลเกี่ยวกับพร็อพเพอร์ตี้อื่นๆ ที่คุณเพิ่มลงในไฟล์ Manifest ของเว็บแอปได้ โปรดดูเอกสารประกอบเกี่ยวกับไฟล์ Manifest ของเว็บแอป MDN