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

การสนับสนุนเบราว์เซอร์

  • 39
  • 79
  • x
  • x

แหล่งที่มา

ไฟล์ 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 มาตรฐานของเบราว์เซอร์ เช่น แถบที่อยู่
ตัวอย่างหน้าต่าง PWA ที่มีจอแสดงผลแบบสแตนด์อโลน
UI แบบสแตนด์อโลน
minimal-ui โหมดนี้คล้ายกับ standalone แต่จะมอบชุดองค์ประกอบ UI แบบเรียบง่ายแก่ผู้ใช้สำหรับควบคุมการนำทาง เช่น ปุ่มย้อนกลับและปุ่มโหลดซ้ำ
ตัวอย่างหน้าต่าง PWA ที่มีการแสดงผล UI แบบเรียบง่าย
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 ที่ระบุในส่วนหัวของเอกสาร

ตัวอย่างหน้าต่าง PWA ที่มี "theme_color" ที่กำหนดเอง
ตัวอย่างหน้าต่าง PWA ที่มี theme_color ที่กำหนดเอง

theme_colorในคำค้นหาสื่อ

การสนับสนุนเบราว์เซอร์

  • 93
  • 93
  • 106
  • 15

แหล่งที่มา

คุณปรับ 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 ภาพที่ตรงกับเกณฑ์เหล่านี้ โดยจะไม่สนใจภาพที่เหลือ

ภาพหน้าจอของ UI การติดตั้งที่สมบูรณ์ยิ่งขึ้นบนเดสก์ท็อปและอุปกรณ์เคลื่อนที่
UI การติดตั้งที่สมบูรณ์ยิ่งขึ้นบนเดสก์ท็อปและอุปกรณ์เคลื่อนที่

หลังจากสร้างไฟล์ Manifest แล้ว ให้เพิ่มแท็ก <link> ลงในทุกหน้าของ Progressive Web App เช่น

<link rel="manifest" href="/manifest.json">

ทดสอบไฟล์ Manifest

หากต้องการยืนยันว่าไฟล์ Manifest ได้รับการตั้งค่าอย่างถูกต้อง ให้ใช้แผงไฟล์ Manifest ในแผงแอปพลิเคชันของ Chrome DevTools

แผงแอปพลิเคชันในเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome ที่เลือกแท็บไฟล์ Manifest อยู่
ทดสอบไฟล์ Manifest ในเครื่องมือสำหรับนักพัฒนาเว็บ

แผงนี้มีพร็อพเพอร์ตี้หลายรายการของไฟล์ Manifest ในเวอร์ชันที่มนุษย์อ่านได้ และช่วยให้คุณยืนยันว่ารูปภาพทั้งหมดโหลดอย่างถูกต้อง

หน้าจอแนะนำบนอุปกรณ์เคลื่อนที่

เมื่อเปิดแอปในอุปกรณ์เคลื่อนที่เป็นครั้งแรก เบราว์เซอร์อาจใช้เวลาสักครู่จึงจะเริ่มทำงานและเนื้อหาเริ่มต้นจะเริ่มแสดงผล แทนที่จะแสดงหน้าจอสีขาวที่อาจทำให้ผู้ใช้คิดว่าแอปไม่ทำงาน เบราว์เซอร์จะแสดงหน้าจอแนะนำจนกว่าจะลงสีครั้งแรก

Chrome จะสร้างหน้าจอแนะนำโดยอัตโนมัติจาก name, background_color และ icons ที่ระบุไว้ในไฟล์ Manifest หากต้องการสร้างการเปลี่ยนจากหน้าจอแนะนำไปยังแอปอย่างราบรื่น ให้กำหนดbackground_colorสีเดียวกับหน้าโหลด

Chrome จะเลือกไอคอนที่ตรงกับความละเอียดของอุปกรณ์มากที่สุดสำหรับหน้าจอแนะนำ การระบุไอคอนขนาด 192 พิกเซล และ 512 พิกเซลก็เพียงพอแล้วสำหรับกรณีส่วนใหญ่ แต่คุณอาจเพิ่มไอคอนอีกเพื่อการจับคู่ที่ดีขึ้นได้

อ่านเพิ่มเติม

หากต้องการดูข้อมูลเกี่ยวกับพร็อพเพอร์ตี้อื่นๆ ที่คุณเพิ่มลงในไฟล์ Manifest ของเว็บแอปได้ โปรดดูเอกสารประกอบเกี่ยวกับไฟล์ Manifest ของเว็บแอป MDN