یک مانیفست برنامه وب اضافه کنید

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

مانیفست برنامه وب یک فایل JSON است که به مرورگر می‌گوید برنامه وب پیشرو (PWA) شما هنگام نصب روی دسکتاپ یا دستگاه تلفن همراه کاربر چگونه باید رفتار کند. حداقل، یک فایل مانیفست معمولی شامل:

• نام برنامه
• نمادهایی که برنامه باید استفاده کند
• آدرس اینترنتی که باید هنگام راه‌اندازی برنامه باز شود

فایل مانیفست را ایجاد کنید

فایل مانیفست می تواند هر نامی داشته باشد، اما معمولا به نام manifest.json است و از ریشه (دایرکتوری سطح بالای وب سایت شما) ارائه می شود. مشخصات نشان می‌دهد که پسوند باید .webmanifest باشد، اما ممکن است بخواهید از فایل‌های JSON برای خواندن واضح‌تر مانیفست‌های خود استفاده کنید.

یک مانیفست معمولی به شکل زیر است:

{
  "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"
    }
  ]
}

ویژگی های مانیفست کلیدی

short_name و name

باید حداقل یکی از short_name یا name در مانیفست خود وارد کنید. اگر هر دو را ارائه کنید، name هنگام نصب برنامه استفاده می‌شود و short_name در صفحه اصلی کاربر، راه‌انداز یا مکان‌های دیگری که فضا محدود است استفاده می‌شود.

icons

وقتی کاربر PWA شما را نصب می‌کند، می‌توانید مجموعه‌ای از نمادها را برای مرورگر تعریف کنید تا در صفحه اصلی، راه‌انداز برنامه، تعویض‌کننده وظیفه، صفحه نمایش اسپلش و در مکان‌های دیگر استفاده کند.

ویژگی icons آرایه ای از اشیاء تصویر است. هر شی باید شامل src ، ویژگی sizes و type تصویر باشد. برای استفاده از نمادهای ماسک پذیر ، که گاهی اوقات در اندروید به آنها نمادهای تطبیقی ​​نیز گفته می شود، "purpose": "any maskable" به ویژگی icon اضافه کنید.

برای Chromium، باید حداقل یک نماد 192x192 پیکسل و یک نماد 512x512 پیکسل ارائه دهید. اگر فقط آن دو اندازه نماد ارائه شده باشد، Chrome به‌طور خودکار نمادها را متناسب با دستگاه تغییر می‌دهد. اگر ترجیح می‌دهید آیکون‌های خود را مقیاس کنید و آنها را برای کامل‌تر بودن پیکسل تنظیم کنید، آیکون‌ها را با افزایش 48dp ارائه کنید.

id

ویژگی id به شما امکان می دهد شناسه مورد استفاده برای برنامه خود را به صراحت تعریف کنید. افزودن ویژگی id به مانیفست وابستگی به start_url یا مکان مانیفست را حذف می کند و امکان به روز رسانی آنها را در آینده ممکن می کند. برای اطلاعات بیشتر، به شناسایی منحصر به فرد PWA ها با ویژگی شناسه مانیفست برنامه وب مراجعه کنید.

start_url

start_url یک ویژگی ضروری است. این به مرورگر می‌گوید که برنامه شما هنگام راه‌اندازی از کجا باید شروع شود و از شروع برنامه در صفحه‌ای که کاربر در هنگام افزودن برنامه شما به صفحه اصلی خود در آن بوده است، جلوگیری می‌کند.

start_url شما باید کاربر را مستقیماً به برنامه شما هدایت کند، نه صفحه فرود محصول. به این فکر کنید که کاربر بلافاصله پس از باز کردن برنامه شما می خواهد چه کاری انجام دهد و آنها را در آنجا قرار دهید.

background_color

هنگامی که برنامه برای اولین بار در تلفن همراه راه اندازی می شود، از ویژگی background_color در صفحه اسپلش استفاده می شود.

display

می‌توانید رابط کاربری مرورگر را که هنگام راه‌اندازی برنامه شما نشان داده شود، سفارشی کنید. به عنوان مثال، می توانید نوار آدرس و عناصر رابط کاربری مرورگر را پنهان کنید. حتی می توان بازی ها را به صورت تمام صفحه راه اندازی کرد. ویژگی display یکی از مقادیر زیر را می گیرد:

اموال	رفتار
fullscreen	برنامه وب را بدون هیچ رابط کاربری مرورگر باز می کند و تمام فضای نمایش موجود را اشغال می کند.
standalone	برنامه وب را باز می کند تا شبیه یک برنامه مستقل به نظر برسد. این برنامه در پنجره خود، جدا از مرورگر اجرا می شود و عناصر استاندارد رابط کاربری مرورگر مانند نوار آدرس را پنهان می کند.
minimal-ui	این حالت شبیه به standalone است، اما حداقل مجموعه ای از عناصر رابط کاربری را برای کنترل ناوبری، مانند دکمه های بازگشت و بارگذاری مجدد، در اختیار کاربر قرار می دهد.
browser	یک تجربه مرورگر استاندارد.

display_override

برای انتخاب نحوه نمایش برنامه وب خود، یک حالت display در مانیفست آن را همانطور که قبلا توضیح داده شد تنظیم کنید. مرورگرها برای پشتیبانی از همه حالت‌های نمایش لازم نیستند، اما باید از زنجیره بازگشتی تعریف‌شده با مشخصات پشتیبانی کنند ( "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 پیش‌فرض ضمنی URL شروع است، اما نام فایل، پرس و جو و قطعه آن حذف شده است.
• مشخصه scope می تواند یک مسیر نسبی ( ../ ) یا هر مسیر سطح بالاتر ( / ) باشد که امکان افزایش پوشش پیمایش ها را در برنامه وب شما فراهم می کند.
• start_url باید در محدوده باشد.
• start_url نسبت به مسیر تعریف شده در ویژگی scope است.
• یک start_url که با / شروع می شود همیشه ریشه مبدا خواهد بود.

theme_color

theme_color رنگ نوار ابزار را تعیین می‌کند و می‌تواند در پیش‌نمایش برنامه در Task switcher منعکس شود. theme_color باید با رنگ تم meta مشخص شده در سر سند شما مطابقت داشته باشد.

theme_color در پرسش‌های رسانه‌ای

می‌توانید theme_color در یک درخواست رسانه با استفاده از ویژگی media عنصر رنگ تم meta تنظیم کنید. برای مثال می توانید یک رنگ را برای حالت روشن و یک رنگ دیگر را برای حالت تاریک به این صورت تعریف کنید. با این حال، نمی‌توانید این اولویت‌ها را در مانیفست خود تعریف کنید. برای اطلاعات بیشتر، به موضوع 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 هدف برنامه شما را توصیف می کند.

در کروم، حداکثر طول توضیحات 300 کاراکتر در همه پلتفرم‌ها است. اگر توضیحات طولانی تر از آن باشد، مرورگر آن را با یک کاراکتر بیضی کوتاه می کند. در اندروید، توضیحات باید حداکثر از هفت خط متن استفاده کند.

screenshots

ویژگی screenshots آرایه ای از اشیاء تصویری است که برنامه شما را در سناریوهای استفاده رایج نشان می دهد. هر شی باید شامل src ، ویژگی sizes و type تصویر باشد. ویژگی form_factor اختیاری است. می‌توانید آن را روی "wide" برای اسکرین‌شات‌هایی که فقط برای صفحه‌نمایش‌های عریض قابل اعمال است یا "narrow" فقط برای عکس‌های باریک تنظیم کنید.

در کروم، تصویر باید معیارهای زیر را داشته باشد:

• عرض و ارتفاع باید حداقل 320 پیکسل و حداکثر 3840 پیکسل باشد.
• حداکثر بعد نمی تواند بیش از 2.3 برابر طول حداقل بعد باشد.
• همه اسکرین شات هایی که با فاکتور فرم مناسب مطابقت دارند باید نسبت تصویر یکسانی داشته باشند.
  • از Chrome 109، فقط اسکرین شات هایی با form_factor روی "wide" در دسک تاپ نمایش داده می شوند.
• از Chrome 109، اسکرین‌شات‌هایی که form_factor روی "wide" تنظیم شده است در Android نادیده گرفته می‌شوند. اسکرین شات های بدون form_factor همچنان برای سازگاری با عقب نمایش داده می شوند.

Chrome روی دسک‌تاپ حداقل یک و حداکثر هشت اسکرین شات را نشان می‌دهد که این معیارها را برآورده می‌کند. بقیه نادیده گرفته می شوند.

Chrome در Android حداقل یک و حداکثر پنج اسکرین شات را نشان می دهد که این معیارها را داشته باشد. بقیه نادیده گرفته می شوند.

مانیفست برنامه وب را به صفحات خود اضافه کنید

پس از ایجاد مانیفست، یک تگ <link> به تمام صفحات برنامه وب پیشرو خود اضافه کنید. به عنوان مثال:

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

مانیفست خود را تست کنید

برای تأیید اینکه مانیفست شما به درستی تنظیم شده است، از پنجره Manifest در پانل برنامه Chrome DevTools استفاده کنید.

این صفحه یک نسخه قابل خواندن برای انسان از بسیاری از ویژگی‌های مانیفست شما ارائه می‌کند و به شما امکان می‌دهد تأیید کنید که همه تصاویر به درستی بارگیری می‌شوند.

پخش صفحه نمایش روی موبایل

هنگامی که برنامه شما برای اولین بار در تلفن همراه راه اندازی می شود، ممکن است چند لحظه طول بکشد تا مرورگر شروع به کار کند و محتوای اولیه شروع به رندر کند. به جای نمایش یک صفحه سفید که ممکن است باعث شود کاربر فکر کند برنامه کار نمی کند، مرورگر یک صفحه نمایش اسپلش را تا اولین رنگ نشان می دهد.

Chrome به‌طور خودکار از name ، background_color ، و icons مشخص‌شده در مانیفست شما، صفحه نمایش را ایجاد می‌کند. برای ایجاد یک انتقال صاف از صفحه نمایش چلپ چلوپ به برنامه، رنگ background_color را همرنگ صفحه بارگذاری کنید.

کروم نمادی را انتخاب می‌کند که بیشترین تطابق را با وضوح دستگاه برای صفحه‌های اسپلش دارد. ارائه آیکون های 192 پیکسل و 512 پیکسل برای اکثر موارد کافی است، اما می توانید نمادهای اضافی را برای تطبیق بهتر ارائه دهید.

در ادامه مطلب

برای آشنایی با ویژگی های دیگری که می توانید به مانیفست برنامه وب خود اضافه کنید، به مستندات مانیفست برنامه وب MDN مراجعه کنید.