مانیفست برنامه وب یک فایل 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، فقط اسکرین شات هایی با
- از 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 مراجعه کنید.