مفاهیم ساختاری

نمایش صفحه

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

چرا Page؟ Page المانی است که به صورت پیش‌فرض به عنوان "نمای اصلی" یک برنامه یا بخشی از آن استفاده می‌شود. هر چیزی که کاربر در یک صفحه مشاهده می‌کند، فرزندان همین Page خواهند بود.

مثال: ساخت یک صفحه ساده در این مثال، یک صفحه به نام "صفحه اصلی" طراحی شده است که حاوی متنی برای خوش‌آمدگویی به کاربر است:

<page id="main-page" title="صفحه اصلی" layout="linear_vertical" scrollable="true">
    <text text="به اپسان خوش آمدید" textsize="20" textcolor="#424750" />
</page>

ویژگی‌های کلیدی Page:

• id: شناسه یکتا برای صفحه.
• title: عنوانی که در نوار ابزار نمایش داده می‌شود.
• layout: نوع چیدمان محتوا (افقی یا عمودی).
• scrollable: مشخص می‌کند که صفحه قابلیت اسکرول دارد یا خیر.

اولین المان در کد اپسان با اجرای مینی اپ اجرا می شود. این المان میتواند از نوع page، dialog، action یا دیگر المان های قابل اجرا باشد.

صفحه (Page) به شما اجازه می‌دهد یک نمای اصلی ایجاد کنید. در داخل یک صفحه می‌توان انواع مختلفی از المان‌ها مانند متن (Text)، دکمه‌ها (Button)، تصاویر (Image) و سایر المان‌ها را قرار داد. یک مینی اپ میتواند صفحات مختلف داشته باشد.

اپسان در زمان اجرا اولین صفحه (یا المان قابل اجرا دیگر) در کد را نمایش میدهد پس از آن منطق جابجایی بین صفحات باید توسط دولپر مشخص شود. این کار با استفاده از اکشن ها انجام میشود.

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

 

اکشن ها

جابجایی بین صفحات با اکشن

جابجایی بین صفحات در اپسان با اکشن‌های page/pageId انجام می‌شود. این اکشن صفحه‌ای با شناسه (ID) مشخص را باز می‌کند. استفاده از این روش باعث می‌شود تجربه کاربری روان و سریع باشد.

برای جابجایی بین صفحات چند صفحه داخل کد تعریف میکنیم و به هر یک id میدهیم هر page با id خود شناخته می شود و برای باز کردن page از این id استفاده می شود.

برای مثال، سه صفحه ایجاد می‌کنیم که کاربر می‌تواند بین آن‌ها جابجا شود. صفحه‌ها شامل یک متن و دکمه‌هایی برای رفتن به صفحه دیگر هستند.

<!-- صفحه اول -->
<page id="page1" title="صفحه اول" layout="linear_vertical" scrollable="true">
    <text text="این صفحه اول است." textsize="20" textcolor="#424750" />
    <button text="برو به صفحه دوم" onclick="page/page2" />
    <button text="برو به صفحه سوم" onclick="page/page3" />
</page>

<!-- صفحه دوم -->
<page id="page2" title="صفحه دوم" layout="linear_vertical" scrollable="true">
    <text text="این صفحه دوم است." textsize="20" textcolor="#424750" />
    <button text="بازگشت به صفحه اول" onclick="page/page1" />
    <button text="برو به صفحه سوم" onclick="page/page3" />
</page>

<!-- صفحه سوم -->
<page id="page3" title="صفحه سوم" layout="linear_vertical" scrollable="true">
    <text text="این صفحه سوم است." textsize="20" textcolor="#424750" />
    <button text="برو به صفحه اول" onclick="page/page1" />
    <button text="برو به صفحه دوم" onclick="page/page2" />
</page>

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

اکشن‌ها تنها محدود به ویژگی onclick نیستند. بسیاری از ویژگی‌های دیگر نیز می‌توانند اکشن دریافت کنند. این ویژگی‌ها معمولاً با پیشوند on شروع می‌شوند. در ادامه، چند مثال از اکشن‌ها در بخش‌های مختلف ارائه شده است:

قابلیت ترکیب اکشن ها

چند اکشن می‌توانند در یک ویژگی به صورت زنجیره‌ای اجرا شوند. این اکشن ها با ; یا -> جدا می شوند. اکشن هایی که با ; جدا شوند پشت سر هم به صورت موازی اجرا می شوند و اکشن هایی که با -> جدا می شوند به ترتیب اجرا شده و پس از پایان اکشن اول اکشن بعدی با نتیجه اکشن اول صدا می شود.

<button text="ذخیره و بازگشت" onclick="script/form-script:saveForm();page/summary-page" />
<button text="امضا و ارسال" onclick="ekyc/generateToken('0300000','1X12345678')->script/sign:submit($data)" />

همه ی اکشن ها امکان استفاده با -> را ندارند. در صورت عدم پشتیبانی اکشن از -> ممکن است اکشن بعدی اجرا نشود یا به طور همزمان با اکشن قبلی اجرا شود.

 

اکشن‌های پرکاربرد

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

• page/pageId: جابجایی به صفحه‌ای با شناسه مشخص.
• dialog/dialogId: باز کردن یک دیالوگ.
• app/closedialog: بستن دیالوگ باز.
• script/scriptId:functionName(): اجرای یک تابع جاوااسکریپت.
• app/exit: خروج از برنامه.

برای آشنایی با باقی اکشن ها میتوانید بخش اکشن ها را مطالعه نمایید.

 

انتقال داده بین صفحات: معرفی متغیرها (Variables)

 

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

Variable: ابزار مدیریت و انتقال داده

متغیرها (Variable) در اپسان برای ذخیره و انتقال داده‌ها بین صفحات یا سایر بخش‌های برنامه استفاده می‌شوند. این متغیرها می‌توانند مقادیر مختلفی مانند متن، عدد یا اشیاء را نگه‌داری کرده و در هر نقطه از برنامه قابل دسترسی باشند.

نحوه تعریف و استفاده از متغیرها

در اپسان، متغیرها با استفاده از متد Appsan.setVariable() تعریف و مقداردهی می‌شوند. برای دسترسی به مقدار متغیر نیز از متد Appsan.getVariable() استفاده می‌شود علاوه بر این میتوانید متغیر را داخل xml با تگ var با مقدار اولیه مشخص اعریف کنید.

<var id="phone" value="0211231225"/>

Appsan.setVariable('phone', '02112345678')

مثال: ذخیره و استفاده از متغیرها

• ذخیره مقدار در متغیر در صفحه اول، نام کاربر در یک متغیر ذخیره می‌شود:

<page id="page1" title="صفحه اول" layout="linear_vertical">
    <textinput id="username" hint="نام کاربری" />
    <button text="ذخیره و برو به صفحه بعد" onclick="script/main-script:saveUsername()" />
</page>

<script id="main-script">
    function saveUsername() {
        const username = Appsan.findElementById('username').value;
        Appsan.setVariable('user_name', username);
        Appsan.runAction('page/page2');
    }
</script>

• دسترسی به مقدار متغیر در صفحه دوم در صفحه دوم، مقدار ذخیره شده نمایش داده می‌شود:

<page id="page2" title="صفحه دوم" layout="linear_vertical">
    <text id="welcomeMessage" text="در حال بارگذاری..." />
    <script id="page2-script">
        function initPage() {
            const username = Appsan.getVariable('user_name').value;
            Appsan.setProperty('welcomeMessage', 'text', `سلام، ${username}!`);
        }
    </script>
    <onshown action="script/page2-script:initPage()" />
</page>

نکات کلیدی در استفاده از متغیرها

1. دسترسی در تمام برنامه: متغیرها به صورت سراسری تعریف می‌شوند و در هر صفحه یا بخش از برنامه قابل دسترسی هستند.
2. مدیریت ساده داده‌ها: با استفاده از متغیرها، نیازی به ارسال مستقیم داده‌ها از یک صفحه به صفحه دیگر نیست.
3. حذف متغیرها: می‌توانید متغیرها را با مقداردهی مجدد بازنویسی کنید یا در صورت نیاز حذف کنید.