เพิ่มไฟล์ 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 จะปรับขนาดไอคอนให้พอดีกับอุปกรณ์โดยอัตโนมัติ หากต้องการปรับขนาดไอคอนของคุณเองและปรับให้พอดีกับพิกเซล ให้ส่งไอคอนที่เพิ่มขึ้นทีละ 48dp

id

พร็อพเพอร์ตี้ id ช่วยให้คุณกำหนดตัวระบุที่ใช้สำหรับแอปพลิเคชันได้อย่างชัดเจน การเพิ่มพร็อพเพอร์ตี้ id ลงในไฟล์ Manifest จะทำให้ไม่ต้องใช้ 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

• หากไม่รวม 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 เป็นต้นไป ระบบจะไม่สนใจภาพหน้าจอที่มีการตั้งค่า 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