เพิ่มไฟล์ Manifest ของเว็บแอป

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

ไฟล์ 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 เช่น คุณกำหนดสีสำหรับโหมดสว่างได้ 1 สี และอีกอันหนึ่งสำหรับโหมดมืด อย่างไรก็ตาม คุณไม่สามารถกำหนด ค่ากำหนดในไฟล์ 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 px และไม่เกิน 3840 px
• ด้านยาวสูงสุดต้องไม่เกิน 2.3 เท่าของความยาวต่ำสุด
• ภาพหน้าจอทั้งหมดที่ตรงกับรูปแบบของอุปกรณ์ที่เหมาะสมต้องมี ของคุณ
  • จาก Chrome 109 เฉพาะภาพหน้าจอที่ตั้งค่า form_factor เป็น "wide" จะแสดงบนเดสก์ท็อป
• จาก 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 Web App