تنظیم امکان بازگشت و رفتار دگمه بازگشت در اپسان

مقدمه

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

استفاده از رفتار پیش‌فرض

رفتار پیش‌فرض اپسان بر اساس تعداد صفحات موجود در تاریخچه عمل می‌کند:

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

پاک کردن تاریخچه

برای پاک کردن تاریخچه و تنظیم تعداد صفحات موجود، می‌توانید از تابع پیش‌فرض clearBackStack استفاده کنید:

این تابع تمام صفحات را حذف کرده و تاریخچه را به حالت اولیه تنظیم می‌کند.
برای استفاده از این تابع، می‌توانید آن را در هر تابعی که نیاز دارید فراخوانی کنید.

AppsanWeb.getAvailableHistoryCountProvider()?.clearBackStack();

قابلیت customBackHandler در AppsanWeb

AppsanWeb شامل یک متغیر و متد برای مدیریت بازگشت سفارشی است:

تعریف customBackHandler: این متغیر می‌تواند یک تابع تعریف شده توسط شما را ذخیره کند که هنگام فشار دادن دکمه بازگشت، اجرا خواهد شد.
متد setCustomBackHandler: برای تنظیم یک تابع سفارشی استفاده می‌شود:
```
AppsanWeb.setCustomBackHandler(() => {
  // handle back here your way
});
```

در صورت استفاده از تابع شخصی سازی شده عملکرد بازگشت پیش فرض اجرا نمی شود و بازگشت میتوند با استفاده از اکشن app/forceback انجام شود. دقت کنید تابع customBackHandler تنها در صورتی که مینی اپ امکان بازگشت داشته باشد صدا می شود. در صورتی که مقدار getAvailableBackHistoryCount() یک یا کم تر باشد مینی وب بدون اجرای تابع customBackHandler بسته می شود. توضیحات تکمیلی تابع getAvailableBackHistoryCount در بخش بعدی آمدهاست.

سفارشی‌سازی امکان بازگشت

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

getAvailableHistoryCount(): برای دریافت تعداد صفحات موجود در تاریخچه.
clearBackStack(): برای پاک کردن تاریخچه و بازنشانی به مقدار اولیه.

نمونه کد برای غیر فعال کردن بازگشت در مینی وب و بسته شدن مینی اپ در صورت بازگشت.

برای غیرفعال کردن دکمه بازگشت و بستن مینی وب، می‌توانید از یک Custom BackCountProvider استفاده کنید که به‌طور مستقیم تعداد تاریخچه را به 1 تنظیم کرده و سپس اپلیکیشن را می‌بندد.

مراحل پیاده‌سازی

یک کلاس سفارشی ایجاد کنید که از رابط AvailableBackCountProvider ارث‌بری کند.
متد getAvailableHistoryCount() را به گونه‌ای پیاده‌سازی کنید که همیشه مقدار 1 برگرداند.

کد نمونه

import { AppsanWeb, AvailableBackCountProvider } from "./AppsanWeb";

export class DisableBackAndCloseProvider implements AvailableBackCountProvider {
    private parent: any;

    constructor() {
        this.parent = window.parent;
        const glob = globalThis as any;
        if (glob['Appsan']) {
            this.parent = glob['Appsan'] as any;
        }
    }

    getAvailableHistoryCount(): number {
        return 1; // همیشه مقدار 1 برگردانده می‌شود تا بازگشت غیرفعال باشد
    }

    clearBackStack(): void {
      
    }
}

توضیحات

غیرفعال کردن بازگشت: با بازگرداندن مقدار 1 در متد getAvailableHistoryCount()، اپسان وب تصور می‌کند که تاریخچه‌ای برای بازگشت وجود ندارد و با کلیک شدن دگمه بک مینی وب را می بندد..

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

در این مثال، از customBackHandler برای نمایش یک دیالوگ تأیید قبل از بازگشت استفاده می‌کنیم. پیاده‌سازی این کلاس به گونه‌ای است که امکان بازگشت را کاملاً سفارشی کرده و تعامل با تاریخچه صفحات را کنترل می‌کند.

import { AppsanWeb, AvailableBackCountProvider } from "./AppsanWeb";

export class ConfirmableBackCountProvider implements AvailableBackCountProvider {
    private availableHistoryCount = 1;
    private parent: any;

    constructor() {
        this.parent = window.parent;
        const glob = globalThis as any;
        if (glob['Appsan']) {
            this.parent = glob['Appsan'] as any;
        }

        const self = this;

        // شنود برای تغییرات تاریخچه
        (function (history: any) {
            const pushState = history.pushState;
            history.pushState = function (state: any) {
                console.log('Push state:', state);
                self.onPushState(state);
                return pushState.apply(history, arguments);
            };
        })(window.history);

        window.addEventListener("popstate", (event) => {
            self.onPopState(event.state);
        });

        // تنظیم customBackHandler
        AppsanWeb.setCustomBackHandler(() => {
            self.showConfirmationDialog();
        });
    }

    onPopState(state: any): void {
        this.availableHistoryCount--;
        (AppsanWeb as any).instance.post((AppsanWeb as any).MESSAGE_TYPE_AVAILABLE_HISTORY_COUNT, this.availableHistoryCount);
    }

    onPushState(state: any): void {
        this.availableHistoryCount++;
        (AppsanWeb as any).instance.post((AppsanWeb as any).MESSAGE_TYPE_AVAILABLE_HISTORY_COUNT, this.availableHistoryCount);
    }

    getAvailableHistoryCount(): number {
        return this.availableHistoryCount;
    }

    clearBackStack(): void {
        this.availableHistoryCount = 1;
        (AppsanWeb as any).instance.post((AppsanWeb as any).MESSAGE_TYPE_AVAILABLE_HISTORY_COUNT, this.availableHistoryCount);
    }

    private showConfirmationDialog(): void {
        const confirmed = confirm("آیا مطمئن هستید که می‌خواهید به صفحه قبلی بازگردید؟");
        if (confirmed) {
            history.back();
        } else {
            console.log("کاربر بازگشت را لغو کرد.");
        }
    }
}

نحوه استفاده از کلاس سفارشی

برای استفاده از این کلاس در اپلیکیشن خود، مراحل زیر را دنبال کنید:

ایجاد نمونه از کلاس:

const backHandler = new ConfirmableBackCountProvider();

ثبت رفتار بازگشت سفارشی: کلاس ConfirmableBackCountProvider به صورت خودکار از طریق AppsanWeb.setCustomBackHandler رفتار بازگشت را تنظیم می‌کند.
مدیریت تاریخچه: این کلاس با متدهای onPushState و onPopState تعداد صفحات موجود در تاریخچه را مدیریت می‌کند.

تنظیم امکان بازگشت و رفتار دگمه بازگشت در اپسان