برنامه های وب پیشرو: توانمندسازی PWA شما

1. خوش آمدید

در این آزمایشگاه، یک برنامه وب موجود را می گیرید و قابلیت های پیشرفته ای را به آن اضافه می کنید. این ششمین مورد از مجموعه کدهای همراه برای کارگاه برنامه کاربردی وب پیشرو است. آزمایشگاه کد قبلی Prompting & Measuring Install بود. دو کد دیگر در این سری وجود دارد.

چیزی که یاد خواهید گرفت

  • با استفاده از File System Access API فایل ها را از سیستم فایل کاربر باز و ذخیره کنید
  • PWA نصب شده خود را به عنوان یک کنترل کننده فایل با File Handling API ثبت کنید
  • با استفاده از Multi-Screen Window Placement API صفحه مناسب را برای باز کردن پنجره انتخاب کنید
  • با استفاده از Screen Wake Lock API از به خواب رفتن صفحه جلوگیری کنید

آنچه شما باید بدانید

  • جاوا اسکریپت

آنچه شما نیاز خواهید داشت

  • مرورگری که از API های فوق پشتیبانی می کند. برای برخی از APIها، ممکن است لازم باشد از مرورگری با برنامه آزمایشی فعال یا Origin Trial استفاده کنید.

2. راه اندازی کنید

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

اگر مخزن را شبیه سازی می کنید، مطمئن شوید که در شاخه pwa05--empowering-your-pwa هستید. فایل فشرده حاوی کد آن شاخه نیز می باشد.

این پایگاه کد به Node.js 14 یا بالاتر نیاز دارد. هنگامی که کد را در دسترس دارید، npm ci از خط فرمان موجود در پوشه کد اجرا کنید تا تمام وابستگی های مورد نیاز خود را نصب کنید. سپس، npm start اجرا کنید تا سرور توسعه برای Codelab راه اندازی شود.

فایل README.md کد منبع توضیحی برای همه فایل های توزیع شده ارائه می دهد. علاوه بر این، فایل‌های موجود کلیدی که در سرتاسر این Codelab با آنها کار خواهید کرد، به شرح زیر است:

فایل های کلیدی

  • js/lib/actions.js - یک کلاس پایه برای منو فراهم می کند

نکته مهم معماری

در سراسر این کد، شما js/lib/action.js را ویرایش می‌کنید که عملکردهای دکمه‌های مختلف را در منوی برنامه مدیریت می‌کند. شما می توانید به هر ویژگی در سازنده منوی اولیه دسترسی داشته باشید، که شامل this.editor برای نمونه ای از ویرایشگر متن اصلی است. دو روش ویرایشگر مهمی که در سراسر این کد لبه استفاده خواهید کرد عبارتند از:

  • this.editor.setContent(content) - محتوای ویرایشگر را روی آرگومان محتوای ارائه شده تنظیم می کند
  • this.editor.content() - محتوای فعلی ویرایشگر را دریافت می کند

3. مدیریت فایل ها

اکنون به لطف File System Access API امکان باز کردن، ذخیره و ایجاد فایل های جدید در رایانه کاربر وجود دارد. همراه با File Handling API ، که به کاربران اجازه می‌دهد فایل‌ها را مستقیماً در PWA خود باز کنند، PWA شما می‌تواند به طور یکپارچه در زندگی روزمره کاربر شما یکپارچه شود.

از داخل برنامه باز کنید

اولین اقدام برای اتصال، باز کردن یک فایل از سیستم فایل کاربر از داخل برنامه است. در js/lib/actions.js ، در متد open کلاس Actions ، کدی بنویسید که کارهای زیر را انجام دهد:

  • انتخابگر فایلی را باز کنید که فایل text/markdown با پسوندهای .md یا .markdown را می گیرد
  • عنوان صفحه را روی نام فایل های باز به اضافه PWA Edit تنظیم کنید
  • کنترل کننده فایل را در زیر this.handler ذخیره کنید
  • محتوای ویرایشگر را روی محتوای متنی فایل تنظیم کنید
  • کنترل کننده را در ذخیره شی settings در پایگاه داده settings-store IndexedDB ذخیره کنید.

مثبت: به یاد داشته باشید: سازنده کلاس ها نمی توانند توابع async باشند، اما می توانید Promises را در داخل آنها فراخوانی کنید.

اکنون که می‌توانید فایلی را باز کنید و فایلی را که بین بارگذاری‌ها باز است ذخیره کنید، دو کار دیگر وجود دارد که باید انجام دهید: هنگام بارگیری برنامه، کنترل‌کننده را پشتیبان‌گیری کنید و زمانی که کاربر برنامه را بازنشانی می‌کند، آن را از حالت تنظیم خارج کنید.

برای انجام اولین مورد، در سازنده کلاس Actions در js/lib/actions.js ، موارد زیر را انجام دهید:

  • پایگاه داده settings-store را باز کنید
  • کنترل کننده ذخیره شده را از فروشگاه شی settings دریافت کنید
  • this.handler handler را روی مقدار بازیابی شده و عنوان صفحه را روی نام فایل کنترل کننده (به علاوه PWA Edit ) تنظیم کنید اگر یک کنترل کننده ذخیره شده وجود دارد.

برای بازنشانی وضعیت برنامه (که با CTRL / CMD + Shift + R قابل انجام است)، روش reset کلاس Actions را در js/lib/actions.js به‌روزرسانی کنید تا موارد زیر را انجام دهید:

  • عنوان سند را روی PWA Edit قرار دهید
  • محتوای ویرایشگر را روی یک رشته خالی تنظیم کنید
  • this.handler را روی null قرار دهید
  • کنترل کننده ذخیره شده را از ذخیره شی settings حذف کنید

از فایل سیستم کاربر باز شود

اکنون که می توانید یک فایل از برنامه خود باز کنید، باید به کاربران اجازه دهید برنامه شما را با فایل خود باز کنند! ثبت‌نام به‌عنوان کنترل‌کننده فایل برای یک دستگاه به کاربر اجازه می‌دهد فایل‌های برنامه شما را از هر نقطه‌ای از سیستم فایل خود باز کند.

منفی: ممکن است لازم باشد یک برنامه‌نویس یا نسخه آزمایشی را برای این کار فعال کنید. اگر نیاز به فعال کردن نسخه آزمایشی برنامه نویس دارید، توصیه می شود به جای مرورگر معمولی خود، این کار را در یک نسخه از Chrome Canary انجام دهید. اگر نیاز به فعال کردن Origin Trial دارید، باید به طور معمول برای آن ثبت نام کنید و آن را اضافه کنید به index.html برچسب بزنید

برای شروع، در manifest.json ، یک ورودی file_handlers اضافه کنید که کارهای زیر را انجام می دهد:

  • باز می شود /
  • text/markdown با پسوندهای فایل .md یا .markdown می پذیرد.

این به کاربران امکان می‌دهد فایل‌ها را با برنامه شما باز کنند، اما در واقع فایل‌ها را در برنامه شما باز نمی‌کند. برای انجام این کار، در کلاس Actions در js/lib/actions.js ، موارد زیر را انجام دهید:

  • یک مصرف کننده window.launchQueue در سازنده اضافه کنید، در صورت وجود، this.open با handler فراخوانی کنید.
  • برای پذیرش یک کنترل کننده راه اندازی اختیاری، this.open را به روز کنید
    • اگر وجود دارد و نمونه ای از FileSystemFileHandle است، از آن به عنوان کنترل کننده فایل برای تابع استفاده کنید.
    • اگر نشد، انتخابگر فایل را باز کنید

پس از انجام هر دو مورد بالا، PWA خود را نصب کنید و سعی کنید یک فایل را با آن از سیستم فایل باز کنید!

ذخیره یک فایل

دو مسیر ذخیره متفاوت وجود دارد که کاربر ممکن است بخواهد طی کند: ذخیره تغییرات در فایلی که قبلاً باز شده است یا ذخیره در یک فایل جدید. با File System Access API، ذخیره در یک فایل جدید در واقع ایجاد یک فایل جدید و بازگرداندن یک کنترل کننده فایل است، بنابراین برای شروع، اجازه دهید از یک کنترل کننده موجود ذخیره کنید.

در متد save در کلاس Actions در js/lib/actions.js ، موارد زیر را انجام دهید:

  • کنترل کننده را یا از this.handler دریافت کنید یا اگر وجود ندارد، کنترلر ذخیره شده را از پایگاه داده دریافت کنید.
  • FileSystemWritableFileStream کنترل کننده فایل را ایجاد کنید
  • محتوای ویرایشگر را در جریان بنویسید
  • جریان را ببندید

هنگامی که می توانید یک فایل را ذخیره کنید، زمان اجرای save as فرا می رسد. برای انجام این کار، در متد saveAs در کلاس Actions در js/lib/actions.js ، موارد زیر را انجام دهید:

  • انتخابگر فایل ذخیره را نشان دهید، آن را به عنوان یک Markdown File توصیف کنید و از آن بخواهید فایل های text/markdown را با پسوند .md
  • this.handler را روی کنترل کننده برگشتی تنظیم کنید
  • کنترل کننده را در فروشگاه شی settings ذخیره کنید
  • منتظر بمانید تا this.save تمام شود تا محتوا در فایل ایجاد شده ذخیره شود

هنگامی که این کار را انجام دادید، به روش save برگردید، قبل از اینکه بخواهید روی آن بنویسید، بررسی کنید که آیا handler وجود دارد یا خیر، و اگر این کار را نکرد، در عوض منتظر بمانید تا this.saveAs تمام شود.

4. نمایش پیش نمایش

با ویرایشگر Markdown، کاربران می خواهند پیش نمایشی از خروجی رندر شده را ببینند. با استفاده از Window Management API ، پیش نمایشی از محتوای رندر شده را در صفحه اصلی کاربر باز می کنید.

قبل از شروع، یک فایل js/preview.js بسازید و کد زیر را به آن اضافه کنید تا در هنگام بارگذاری، پیش‌نمایش نمایش داده شود:

import { openDB } from 'idb';
import { marked } from 'marked';

window.addEventListener('DOMContentLoaded', async () => {
  const preview = document.querySelector('.preview');
  const db = await openDB('settings-store');
  const content = (await db.get('settings', 'content')) || '';

  preview.innerHTML = marked(content);
});

پیش نمایش باید به روش های زیر عمل کند:

  • وقتی کاربر روی دکمه پیش‌نمایش کلیک می‌کند و پیش‌نمایش باز نمی‌شود، باید پیش‌نمایش را باز کند
  • وقتی کاربر روی دکمه پیش‌نمایش کلیک می‌کند و پیش‌نمایش باز می‌شود، باید پیش‌نمایش را ببندد
  • وقتی کاربر PWA را می بندد یا تازه می کند، پیش نمایش باید بسته شود

به ترتیب این موارد را با ویرایش متد preview در کلاس Actions در js/lib/actions.js شروع کنید تا کارهای زیر را انجام دهید:

  • صفحه های موجود را با استفاده از Window Management API دریافت کنید
  • برای پیدا کردن صفحه اصلی، صفحه‌ها را فیلتر کنید
  • پنجره‌ای را برای /preview با عنوان Markdown preview باز کنید که نیمی از عرض موجود و کل ارتفاع موجود صفحه اصلی را به‌گونه‌ای قرار می‌دهد که نیمه سمت راست کامل آن صفحه را اشغال کند. ابعاد موجود، بخش‌های رزرو شده صفحه، مانند نوار منوی سیستم، نوار ابزار، وضعیت یا مکان را حذف نمی‌کند.
  • این پنجره باز را در this.previewWindow ذخیره کنید
  • در بالای روش، بررسی کنید که آیا this.previewWindow وجود دارد یا خیر، و اگر وجود دارد، پنجره را ببندید و به جای باز کردن پیش نمایش پنجره، this.previewWindow تنظیم نکنید.

در نهایت، در انتهای سازنده کلاس Actions در js/lib/actions.js موارد زیر را انجام دهید:

  • در طول رویداد beforeunload this.previewWindow ببندید

5. تمرکز کنید

در نهایت، ما می خواهیم یک حالت نوشتن بدون حواس پرتی را به کاربران ارائه دهیم. بدون حواس پرتی نه تنها به معنای عدم درهم ریختگی برنامه های دیگر است، بلکه از به خواب رفتن صفحه نمایش کاربر نیز جلوگیری می کند. برای انجام این کار، از Screen Wake Lock API استفاده خواهید کرد.

دکمه wake lock درست مانند دکمه پیش نمایش کار می کند و بین حالت روشن و خاموش جابجا می شود. برای انجام این کار، در متد focus کلاس Actions در js/lib/actions.js ، موارد زیر را انجام دهید:

  • بررسی کنید که آیا سند دارای یک عنصر تمام صفحه است یا خیر
  • اگر انجام دهد:
    • خروج از تمام صفحه
    • اگر this.wakeLock وجود دارد، wake lock را رها کرده و this.wakeLock را بازنشانی کنید
  • اگر اینطور نیست:
    • یک نگهبان wake lock را درخواست کنید و آن را روی this.wakeLock تنظیم کنید
    • درخواست کنید که بدنه سند تمام صفحه شود.

6. تبریک!

شما یاد گرفته اید که چگونه فایل های سیستم را مدیریت کنید و PWA خود را با سیستم با استفاده از File System Access API و File Handling API یکپارچه کنید، پنجره ها را در صفحه های مختلف با Window Management API باز کنید و با Screen Wake Lock API از به خواب رفتن صفحه جلوگیری کنید.

Codelab بعدی این سری Service Worker Includes است