ไฟล์ Manifest ของเว็บแอป

ไฟล์ Manifest ของเว็บแอปคือไฟล์ที่คุณสร้างขึ้นเพื่อบอกเบราว์เซอร์ว่าต้องการให้เนื้อหาเว็บแสดงเป็นแอปในระบบปฏิบัติการอย่างไร ไฟล์ Manifest สามารถมีข้อมูลพื้นฐาน เช่น ชื่อ ไอคอน และสีธีมของแอป การตั้งค่าขั้นสูง เช่น การวางแนวที่ต้องการและทางลัดของแอป ตลอดจนข้อมูลเมตาของแคตตาล็อก เช่น ภาพหน้าจอ

PWA แต่ละรายการควรมีไฟล์ Manifest รายการเดียวต่อแอปพลิเคชัน ซึ่งมักจะโฮสต์อยู่ในโฟลเดอร์รูท และลิงก์อยู่ในหน้า HTML ทั้งหมดที่ติดตั้ง PWA ได้ ส่วนขยายอย่างเป็นทางการคือ .webmanifest คุณจึงตั้งชื่อไฟล์ Manifest เป็น app.webmanifest ได้

การเพิ่มไฟล์ Manifest ของเว็บแอปลงใน PWA

หากต้องการสร้างไฟล์ Manifest ของเว็บแอป ให้สร้างไฟล์ข้อความที่มีออบเจ็กต์ JSON ซึ่งมีช่อง name ที่มีค่าสตริงเป็นอย่างน้อย ดังนี้

app.webmanifest:

{
   "name": "My First Application"
}

แต่การสร้างไฟล์นั้นยังไม่เพียงพอ เบราว์เซอร์ยังต้องรู้ว่าไฟล์มีอยู่ด้วย

การลิงก์กับไฟล์ Manifest

หากต้องการให้เบราว์เซอร์ทราบเกี่ยวกับไฟล์ Manifest ของเว็บแอป คุณต้องลิงก์ไฟล์ Manifest นั้นกับ PWA โดยใช้องค์ประกอบ HTML <link> และแอตทริบิวต์ rel ที่ตั้งค่าเป็น manifest ในหน้า HTML ทั้งหมดของ PWA ซึ่งคล้ายกับวิธีลิงก์สไตล์ชีต CSS กับเอกสาร

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

การแก้ไขข้อบกพร่องของไฟล์ Manifest

คุณสามารถใช้เครื่องมือตรวจสอบใน Firefox และเครื่องมือสำหรับนักพัฒนาเว็บในเบราว์เซอร์ทุกรุ่นที่ใช้ Chromium เพื่อให้แน่ใจว่าการตั้งค่าไฟล์ Manifest ถูกต้อง

สำหรับเบราว์เซอร์ Chromium

ในเครื่องมือสำหรับนักพัฒนาเว็บ

  1. เลือก Manifest ในส่วน Application ของแผงด้านซ้าย
  2. ตรวจสอบช่องของไฟล์ Manifest ที่เบราว์เซอร์แยกวิเคราะห์

สำหรับ Firefox

  1. เปิดเครื่องมือตรวจสอบ
  2. ไปที่แท็บแอปพลิเคชัน
  3. เลือกตัวเลือกไฟล์ Manifest ในแผงด้านซ้าย
  4. ตรวจสอบช่องของไฟล์ Manifest ที่เบราว์เซอร์แยกวิเคราะห์

การออกแบบประสบการณ์การใช้งาน PWA

เมื่อ PWA เชื่อมต่อกับไฟล์ Manifest แล้ว ก็ถึงเวลากรอกข้อมูลในช่องที่เหลือเพื่อกำหนดประสบการณ์การใช้งานให้กับผู้ใช้

ฟิลด์พื้นฐาน

ช่องชุดแรกแสดงข้อมูลหลักเกี่ยวกับ PWA ไฟล์เหล่านี้ใช้ในการสร้างไอคอนและหน้าต่างของ PWA ที่ติดตั้ง และกำหนดวิธีเริ่มต้น ดังนี้

name
ชื่อเต็มของ PWA โดยไอคอนจะปรากฏพร้อมกับไอคอนในหน้าจอหลัก ตัวเปิดแอป แท่นชาร์จ หรือเมนูของระบบปฏิบัติการ
short_name
ไม่บังคับ ชื่อ PWA ที่สั้นลง ซึ่งจะใช้เมื่อมีพื้นที่ไม่เพียงพอที่จะแสดงค่าทั้งหมดของช่อง name โปรดใช้อักขระไม่เกิน 12 ตัวเพื่อลดโอกาสที่ระบบจะตัดข้อความ
icons
อาร์เรย์ของออบเจ็กต์ไอคอนที่มีช่อง src, type, sizes และ purpose (ไม่บังคับ) ซึ่งอธิบายว่ารูปภาพใดควรแสดง PWA
start_url
URL ที่ PWA ควรโหลดเมื่อผู้ใช้เปิดจากไอคอนที่ติดตั้งไว้ เราขอแนะนำให้ใช้เส้นทางแบบสัมบูรณ์ ดังนั้นหากหน้าแรกของ PWA เป็นรูทของเว็บไซต์ คุณอาจตั้งค่าเป็น "/" เพื่อเปิดหน้าดังกล่าวเมื่อแอปเริ่มทำงาน หากคุณไม่ได้ระบุ URL เริ่มต้น เบราว์เซอร์จะใช้ URL ที่ติดตั้ง PWA เป็น URL เริ่มต้นได้ โดยอาจเป็น Deep Link เช่น รายละเอียดผลิตภัณฑ์แทนที่จะเป็นหน้าจอหลัก
display
ค่าใดค่าหนึ่งต่อไปนี้ fullscreen, standalone, minimal-ui หรือ browser ซึ่งอธิบายวิธีที่ระบบปฏิบัติการควรวาดหน้าต่าง PWA อ่านข้อมูลเพิ่มเติมเกี่ยวกับโหมดการแสดงผลต่างๆ ได้ในบทการออกแบบแอป กรณีการใช้งานส่วนใหญ่จะใช้ standalone
id
สตริงที่ระบุ PWA นี้ที่ไม่ซ้ำกับ PWA อื่นๆ ที่อาจโฮสต์อยู่ในต้นทางเดียวกัน หากไม่ได้ตั้งค่าไว้ ระบบจะใช้ start_url เป็นค่าสำรอง โปรดทราบว่าการเปลี่ยน start_url ในอนาคต (เช่น เมื่อเปลี่ยนค่าสตริงการค้นหา) อาจทำให้เบราว์เซอร์ตรวจไม่พบว่ามีการติดตั้ง PWA อยู่แล้ว

ไอคอน

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

หากต้องเลือกไอคอนเพียงขนาดเดียว ขนาดไอคอนควรเป็น 512 x 512 พิกเซล อย่างไรก็ตาม เราขอแนะนำให้ระบุรูปภาพขนาดอื่นๆ ด้วย เช่น 192 x 192, 384 x 384 และ 1024 x 1024 พิกเซล

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

หากไม่ได้ระบุไอคอนหรือไอคอนไม่ได้อยู่ในรูปแบบที่แนะนำ คุณจะไม่ผ่านเกณฑ์การติดตั้งในบางแพลตฟอร์ม ในแพลตฟอร์มอื่นๆ ระบบจะสร้างไอคอนโดยอัตโนมัติ เช่น จากภาพหน้าจอของ PWA หรือใช้ไอคอนทั่วไป

ไอคอนที่มาสก์ได้

ระบบปฏิบัติการบางระบบ เช่น Android จะปรับไอคอนให้มีขนาดและรูปร่างแตกต่างกัน เช่น ใน Android 12 ผู้ผลิตหรือการตั้งค่าต่างๆ สามารถเปลี่ยนรูปร่างของไอคอนจากวงกลมเป็นสี่เหลี่ยมจัตุรัสเป็นสี่เหลี่ยมจัตุรัสที่มีมุมมน หากต้องการรองรับไอคอนแบบปรับอัตโนมัติประเภทเหล่านี้ คุณสามารถระบุไอคอนที่มาสก์ได้โดยใช้ช่อง purpose

โดยให้ส่งไฟล์รูปภาพสี่เหลี่ยมจัตุรัสที่มีไอคอนหลักอยู่ใน "โซนปลอดภัย" ซึ่งเป็นวงกลมที่กึ่งกลางไอคอนและมีรัศมี 40 เปอร์เซ็นต์ของไอคอน (ดูรูปภาพด้านล่าง) อุปกรณ์ที่รองรับไอคอนที่มาสก์ได้จะมาสก์ไอคอนตามความจำเป็น

พื้นที่ปลอดภัยที่ระบุเป็นวงกลมรัศมี 40 เปอร์เซ็นต์ซึ่งอยู่ตรงกลางภายในไอคอนสี่เหลี่ยมจัตุรัส

ต่อไปนี้คือตัวอย่างไอคอนที่มาสค์ได้ซึ่งแสดงผลเป็นรูปร่างที่ใช้กันโดยทั่วไป

ในรูปภาพต่อไปนี้ หากคุณใช้ไอคอนทางด้านซ้ายเป็นไอคอนที่มาสก์ได้ ผลลัพธ์ที่ได้จะแย่ในอุปกรณ์เมื่อใช้มาสก์รูปร่าง

ไอคอนที่ไม่เหมาะสำหรับไอคอนที่มาสก์ได้

รูปภาพนี้อาจใช้งานได้หากเพิ่มระยะห่างจากขอบ

ไอคอนที่มีระยะห่างจากขอบมากขึ้นเหมาะสำหรับมาสก์

ไอคอนที่มาสก์ได้ควรมีขนาดอย่างน้อย 512 x 512 เมื่อสร้างแล้ว คุณสามารถเพิ่มลงในคอลเล็กชัน icons เพื่อปรับปรุงประสบการณ์การใช้งานสำหรับอุปกรณ์ที่รองรับ

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

ในกรณีส่วนใหญ่ หากไอคอนที่ปิดบังได้แสดงไม่ถูกต้อง คุณสามารถปรับปรุงได้โดยเพิ่มระยะห่างจากขอบ Maskable.app เป็นเครื่องมือออนไลน์ฟรีสำหรับทดสอบและสร้างไอคอนเวอร์ชันที่วางซ้อนได้

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

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

theme_color
สีเริ่มต้นสำหรับแอปพลิเคชัน ซึ่งบางครั้งอาจส่งผลต่อวิธีที่ระบบปฏิบัติการแสดงเว็บไซต์ (เช่น สีของหน้าต่างและแถบชื่อบนเดสก์ท็อป หรือสีของแถบสถานะในอุปกรณ์เคลื่อนที่) เอลิเมนต์ HTML theme-color <meta> สามารถลบล้างสีนี้ได้
background_color
สีตัวยึดตําแหน่งที่จะแสดงในพื้นหลังของแอปพลิเคชันก่อนที่จะโหลดสไตล์ชีต ปัจจุบัน Safari ใน iOS และ iPadOS รวมถึงเบราว์เซอร์บนเดสก์ท็อปส่วนใหญ่จะไม่สนใจช่องนี้
scope
เปลี่ยนขอบเขตการนําทางของ PWA ซึ่งช่วยให้คุณกําหนดสิ่งที่จะแสดงและไม่แสดงภายในหน้าต่างของแอปที่ติดตั้ง ตัวอย่างเช่น หากคุณลิงก์ไปยังหน้าที่อยู่นอกขอบเขต ระบบจะแสดงผลหน้านั้นในเบราว์เซอร์ในแอปแทนที่จะเป็นในหน้าต่าง PWA อย่างไรก็ตาม การดำเนินการนี้จะไม่เปลี่ยนขอบเขตของ Service Worker

รูปภาพถัดไปแสดงวิธีใช้ช่อง theme_color สำหรับแถบชื่อในอุปกรณ์เดสก์ท็อปเมื่อคุณติดตั้ง PWA

PWA เดียวกันที่ติดตั้งในเดสก์ท็อปซึ่งมีสีธีมต่างกัน

เมื่อกำหนดสีในไฟล์ Manifest เช่น ภายใน theme_color และ background_color คุณควรใช้สีที่มีชื่อของ CSS เช่น salmon หรือ orange, สี RGB เช่น #FF5500 หรือฟังก์ชันสีที่ไม่มีความโปร่งใส เช่น rgb() หรือ hsl() ดูข้อมูลเพิ่มเติมได้ที่บทการออกแบบแอป

ลองใช้

หน้าจอแนะนำ

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

Android ใช้ค่า theme_color, background_color และ icon เพื่อสร้างหน้าจอแนะนำ

เมื่อคุณติดตั้ง PWA ใน Android อุปกรณ์จะสร้างหน้าจอแนะนำที่มีข้อมูลจากไฟล์ Manifest ดังที่เห็นในแผนภาพต่อไปนี้

PWA ในหน้าจอเริ่มต้นของ Android ที่ใช้ค่าที่แตกต่างจากไฟล์ Manifest

แต่ Safari ใน iOS และ iPadOS จะไม่ใช้ไฟล์ Manifest ของเว็บแอปเพื่อสร้างหน้าจอแนะนำ แต่จะใช้รูปภาพที่ลิงก์จากองค์ประกอบ <link> ที่เป็นกรรมสิทธิ์แทน ซึ่งคล้ายกับวิธีจัดการไอคอน ดูรายละเอียดเพิ่มเติมได้ที่บทการเพิ่มประสิทธิภาพ

ฟิลด์แบบขยาย

ช่องชุดถัดไปจะให้ข้อมูลเพิ่มเติมเกี่ยวกับ PWA โดยคุณเลือกหรือไม่เลือกก็ได้

lang
แท็กภาษาที่ระบุภาษาหลักของค่าในไฟล์ Manifest เช่น en สำหรับภาษาอังกฤษ pt-BR สำหรับโปรตุเกสแบบบราซิล หรือ in สำหรับฮินดี
dir
ทิศทางในการแสดงช่องไฟล์ Manifest ที่รองรับทิศทาง (เช่น name, short_name และ description) ค่าที่ถูกต้องคือ auto, ltr (จากซ้ายไปขวา) และ rtl (จากขวาไปซ้าย)
orientation
การวางแนวที่ต้องการสำหรับแอปเมื่อติดตั้งแล้ว เกมอาจตั้งค่านี้เพื่อขอการวางแนวแนวนอนเท่านั้น ระบบยอมรับค่าหลายค่า แต่หากรวมไว้ โดยทั่วไปจะเป็น portrait หรือ landscape อย่างชัดแจ้ง

ช่องโปรโมชัน

ช่องชุดที่ 4 ช่วยให้คุณระบุข้อมูลโปรโมตเกี่ยวกับ PWA ได้ เช่น ในขั้นตอนการติดตั้ง ข้อมูล และผลการค้นหา

description
คำอธิบายว่า PWA ทํางานอย่างไร
screenshots
อาร์เรย์ของออบเจ็กต์ภาพหน้าจอที่มี src, type และ sizes (คล้ายกับออบเจ็กต์ icons) ซึ่งมีไว้เพื่อแสดง PWA ไม่มีการจำกัดขนาด
categories
อาร์เรย์ของหมวดหมู่ที่ PWA ควรมีเพื่อใช้เป็นคำแนะนำสำหรับข้อมูล ซึ่งสามารถเลือกได้จากรายการหมวดหมู่ที่รู้จัก โดยปกติแล้วค่าเหล่านี้จะเป็นตัวพิมพ์เล็ก
iarc_rating_id
รหัสการรับรองของสหพันธ์การจัดประเภทตามอายุสากลสำหรับ PWA (หากมี) โดยมีวัตถุประสงค์เพื่อใช้พิจารณาว่า PWA ของคุณเหมาะกับอายุใด

คุณดูช่องโปรโมตเหล่านี้ใช้งานได้แล้ววันนี้ ตัวอย่างเช่น ใน Android หาก PWA ติดตั้งได้และคุณระบุค่าสำหรับช่อง description และ screenshots เป็นอย่างน้อย กล่องโต้ตอบการติดตั้งจะเปลี่ยนจากแถบข้อมูล "เพิ่มลงในหน้าจอหลัก" แบบธรรมดาเป็นกล่องโต้ตอบการติดตั้งที่สมบูรณ์ยิ่งขึ้นซึ่งคล้ายกับกล่องโต้ตอบจาก App Store

ใน Android คุณจะได้รับ UI การติดตั้งที่ดูดีขึ้นหากระบุค่าสำหรับช่องโปรโมชัน ดังที่แสดงในวิดีโอถัดไป

ดูตัวอย่างการใช้งานช่องโปรโมชันต่อไปนี้

ช่องความสามารถ

สุดท้าย มีช่องหลายช่องที่เกี่ยวข้องกับความสามารถต่างๆ ที่ PWA ของคุณใช้ได้ในเบราว์เซอร์ที่รองรับ เช่น ช่อง shortcuts, share_target, display_override ตามที่เราได้อธิบายไว้ในบทความสามารถ นอกจากนี้ยังมีช่องต่างๆ เช่น related_apps และ prefer_related_apps (ดูข้อมูลเพิ่มเติมในบทการตรวจหา) เพื่อเชื่อมต่อ PWA กับแอปที่ติดตั้งไว้ ซึ่งมักมาจาก App Store

ช่องใหม่จำนวนมากอาจปรากฏขึ้นในอนาคตเมื่อเบราว์เซอร์เพิ่มความสามารถให้กับ Progressive Web App

แหล่งข้อมูล