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

این عملکرد کد JavaScript وارد شده را اجرا می‌کند و امکان دسترسی به متغیرها، نمایش پیام و اجرای سایر عملکردها از داخل کد را فراهم می‌کند.

کاربردها

• اجرای کد جاوااسکریپت سفارشی.
• پیاده‌سازی منطق‌های خاص خارج از عملکردهای آماده.
• اتصال به قابلیت‌های پیشرفته یا محاسبات اختصاصی.
• فراخوانی API و دریافت داده از سرور با تابع fetch.

هشدار

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

فرم تنظیمات عملکرد «اجرای کد جاوااسکریپت» در پنل اپ‌ادیتور.

تنظیمات

• کد JavaScript: متن کدی که باید اجرا شود. از سینتکس استاندارد JavaScript استفاده کنید.
• لیست عملکردها (اختیاری): می‌توانید چند عملکرد دیگر را به این عملکرد اضافه کنید و به هر کدام یک شناسه بدهید. از داخل کد با AppEditor.runAction('شناسه') همان عملکرد را اجرا کنید.

شیء AppEditor

با استفاده از کدنویسی JavaScript می‌توانید برخی قابلیت‌های اپلیکیشن را داخل کد مدیریت کنید. در این محیط، آبجکت AppEditor برای ارتباط با اپ در دسترس است و متدهای مختلفی دارد.

بیشترین کاربرد این بخش، کنترل متغیرها و پویا کردن رفتار اپلیکیشن است؛ برای مثال می‌توانید مقدار یک متغیر را بخوانید، آن را تغییر دهید، وجود متغیر را بررسی کنید، پیام نمایش دهید یا عملکردهای دیگری را اجرا کنید.

مهم

خروجی تمام توابع AppEditor از نوع Promise است. برای دریافت مقدار برگشتی، قبل از فراخوانی تابع از کلمه کلیدی await استفاده کنید.

متد	توضیح
AppEditor.showMessage(متن)	نمایش یک پیام کوتاه (Toast) به کاربر.
AppEditor.getVar(نام_متغیر)	خواندن مقدار یک متغیر. نام متغیر را به صورت رشته ارسال کنید.
AppEditor.setVar(نام, مقدار)	مقداردهی یا تغییر مقدار یک متغیر.
AppEditor.varIsExist(نام_متغیر)	بررسی وجود داشتن متغیر؛ مقدار بولی برمی‌گرداند.
AppEditor.addVar(...)	ایجاد متغیر جدید با تنظیمات ذخیره‌سازی و نوع.
AppEditor.runAction(شناسه)	اجرای یکی از عملکردهای تعریف‌شده در لیست این عملکرد با شناسهٔ مشخص.

یادداشت

در پایین فرم این عملکرد می‌توانید لیستی از عملکرد‌های مورد نیاز را ایجاد کنید و برای هرکدام یک شناسه قرار دهید. سپس با همان شناسه، عملکرد را داخل کد JavaScript اجرا کنید.

---

راهنمای متدهای AppEditor

نمایش پیام

با کد زیر یک پیغام کوتاه نمایش داده می‌شود.

AppEditor.showMessage("متن پیام مورد نظر");

افزودن متغیر

برای افزودن یک متغیر از متد addVar استفاده کنید. ورودی این متد یک آبجکت است که خصوصیات زیر را می‌پذیرد:

• name: نام متغیر است که بهتر است به صورت لاتین باشد.
• storeType: نوع ذخیره‌سازی است و می‌تواند یکی از مقدارهای temp، device یا online باشد.
  • temp: حافظه موقت
  • device: حافظه دستگاه
  • online: حافظه آنلاین
• varType: نوع مقدار متغیر است و می‌تواند یکی از مقدارهای string، int، double یا bool باشد.
  • string: رشته متنی
  • int: عدد صحیح
  • double: عدد اعشاری
  • bool: مقدار بولی
• value: مقدار اولیه متغیر.
• updateValueIfExists: اگر مقدار آن true باشد، در صورت وجود داشتن متغیر، مقدار آن می‌تواند تغییر کند.

هشدار

در حال حاضر حافظه آنلاین (online) پشتیبانی نمی‌شود؛ برای ذخیره ماندگار روی دستگاه از device و برای داده‌های موقت از temp استفاده کنید.

await AppEditor.addVar({
  name: "var1",
  storeType: "temp",
  varType: "string",
  value: "sample text",
  updateValueIfExists: false
});

چک کردن موجود بودن متغیر

برای چک کردن موجود بودن متغیر قبل از استفاده، می‌توانید از متد AppEditor.varIsExist استفاده کنید.

await AppEditor.varIsExist("var1");

// مثال
if (await AppEditor.varIsExist("var1")) {
  AppEditor.showMessage("متغیر var1 موجود است");
} else {
  AppEditor.showMessage("متغیر var1 یافت نشد!");
}

دریافت مقدار متغیر

با استفاده از متد AppEditor.getVar می‌توانید مقدار متغیر را دریافت کنید.

await AppEditor.getVar("var1");

// مثال
var var1 = await AppEditor.getVar("var1");
AppEditor.showMessage("متغیر var1 برابر است با: " + var1);

تغییر مقدار متغیر

با استفاده از متد AppEditor.setVar می‌توانید مقدار متغیر را تغییر دهید.

await AppEditor.setVar("var1", "new value");

// مثال
await AppEditor.setVar("var1", "مقدار جدید");
var var1 = await AppEditor.getVar("var1");
AppEditor.showMessage("متغیر var1 برابر است با: " + var1);

اجرای عملکرد

با استفاده از متد AppEditor.runAction می‌توانید یک عملکرد را که در لیست عملکردها قرار داده‌اید اجرا کنید. هر عملکرد یک شناسه دارد که شما تعیین می‌کنید و توسط آن می‌توانید عملکرد مورد نظر را اجرا کنید.

AppEditor.runAction("شناسه عملکرد");

نکته

اگر قصد دارید دستورهای بعدی تا پایان اجرای عملکرد متوقف شوند، قبل از AppEditor.runAction از await استفاده کنید.

برای مثال، اگر عملکرد مورد نظر «باز کردن صفحه» باشد، پایان عملکرد زمانی است که صفحه بسته شود. اگر از await استفاده کرده باشید، دستورهای بعدی بعد از بسته شدن صفحه اجرا می‌شوند؛ در غیر این صورت، ادامه کد بدون توقف اجرا خواهد شد.

await AppEditor.runAction("openProfile");
AppEditor.showMessage("صفحه بسته شد و ادامه کد اجرا شد");

---

چه کارهایی می‌توان با اجرای JavaScript انجام داد؟

عملکرد «اجرای کد جاوااسکریپت» زمانی کاربردی است که منطق مورد نظر شما با یک عملکرد آماده به‌تنهایی قابل انجام نیست. با این عملکرد می‌توانید چند عملیات را با هم ترکیب کنید، بر اساس مقدار متغیرها تصمیم بگیرید، داده‌ها را محاسبه کنید و سپس یک یا چند عملکرد دیگر را اجرا کنید.

کاربردهای رایج این عملکرد:

• ساخت منطق‌های شرطی سفارشی بر اساس مقدار چند متغیر.
• محاسبه مقدارهای عددی مثل قیمت نهایی، امتیاز، درصد تخفیف یا تعداد.
• کنترل جریان‌های چندمرحله‌ای مثل ورود، تکمیل فرم، نمایش پیام و باز کردن صفحه.
• جلوگیری از اجرای عملیات تکراری، مثل نمایش فقط یک‌بار یک پیام یا آموزش اولیه.
• اجرای عملکردهای مختلف بر اساس وضعیت کاربر، زبان، انتخاب‌ها یا نتیجه محاسبات.
• پاکسازی، تبدیل یا آماده‌سازی مقدارها قبل از ذخیره در متغیر.
• دریافت داده از API با fetch و ذخیره نتیجه در متغیرها برای نمایش در اپ.

پیشنهاد

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

---

مثال‌های کاربردی

۱. نمایش پیام خوشامد فقط برای اولین اجرا

در این مثال، اگر متغیر welcomeShown قبلاً ساخته نشده باشد، پیام خوشامد نمایش داده می‌شود و سپس متغیر ساخته می‌شود تا دفعات بعد پیام تکرار نشود.

if (!(await AppEditor.varIsExist("welcomeShown"))) {
  AppEditor.showMessage("به اپلیکیشن خوش آمدید");

  await AppEditor.addVar({
    name: "welcomeShown",
    storeType: "device",
    varType: "bool",
    value: true,
    updateValueIfExists: true
  });
}

یادداشت

برای وضعیت‌هایی که باید بعد از بستن و باز کردن اپ حفظ شوند، از storeType: "device" استفاده کنید.

۲. شمارش کلیک کاربر و اجرای پاداش

در این سناریو، با هر بار اجرای کد، مقدار متغیر clickCount یک واحد زیاد می‌شود. وقتی تعداد کلیک‌ها به ۵ برسد، عملکردی با شناسه showReward اجرا می‌شود.

var clickCount = 0;

if (await AppEditor.varIsExist("clickCount")) {
  clickCount = Number(await AppEditor.getVar("clickCount")) || 0;
} else {
  await AppEditor.addVar({
    name: "clickCount",
    storeType: "device",
    varType: "int",
    value: 0,
    updateValueIfExists: true
  });
}

clickCount = clickCount + 1;
await AppEditor.setVar("clickCount", clickCount);

if (clickCount >= 5) {
  AppEditor.showMessage("تبریک! پاداش شما فعال شد");
  await AppEditor.runAction("showReward");
}

مهم

قبل از استفاده از runAction، باید عملکرد مورد نظر را در لیست عملکرد‌های همین فرم اضافه کرده و شناسه آن را دقیقاً showReward قرار دهید.

۳. محاسبه قیمت نهایی با تخفیف

در این مثال، قیمت و درصد تخفیف از متغیرها خوانده می‌شود، قیمت نهایی محاسبه و در متغیر finalPrice ذخیره می‌شود.

var price = Number(await AppEditor.getVar("price")) || 0;
var discountPercent = Number(await AppEditor.getVar("discountPercent")) || 0;

if (discountPercent < 0) discountPercent = 0;
if (discountPercent > 100) discountPercent = 100;

var finalPrice = price - (price * discountPercent / 100);

if (!(await AppEditor.varIsExist("finalPrice"))) {
  await AppEditor.addVar({
    name: "finalPrice",
    storeType: "temp",
    varType: "double",
    value: finalPrice,
    updateValueIfExists: true
  });
} else {
  await AppEditor.setVar("finalPrice", finalPrice);
}

AppEditor.showMessage("قیمت نهایی: " + finalPrice);

هشدار

مقدارهایی که از متغیرها می‌خوانید ممکن است رشته متنی باشند؛ برای محاسبات عددی، آن‌ها را با Number(...) به عدد تبدیل کنید.

۴. هدایت کاربر بر اساس وضعیت ورود

اگر متغیر isLoggedIn مقدار true داشته باشد، عملکرد openProfile اجرا می‌شود؛ در غیر این صورت، عملکرد openLogin اجرا خواهد شد.

var isLoggedIn = false;

if (await AppEditor.varIsExist("isLoggedIn")) {
  isLoggedIn = await AppEditor.getVar("isLoggedIn");
}

if (isLoggedIn === true || isLoggedIn === "true") {
  await AppEditor.runAction("openProfile");
} else {
  AppEditor.showMessage("لطفاً ابتدا وارد حساب کاربری شوید");
  await AppEditor.runAction("openLogin");
}

۵. بررسی تکمیل بودن چند فیلد قبل از ارسال فرم

در این مثال، مقدار چند متغیر بررسی می‌شود. اگر یکی از آن‌ها خالی باشد، پیام خطا نمایش داده می‌شود؛ در غیر این صورت، عملکرد sendForm اجرا می‌شود.

var name = await AppEditor.getVar("name");
var mobile = await AppEditor.getVar("mobile");
var message = await AppEditor.getVar("message");

if (!name || !mobile || !message) {
  AppEditor.showMessage("لطفاً همه فیلدهای ضروری را تکمیل کنید");
} else {
  await AppEditor.runAction("sendForm");
}

نکته

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

۶. تغییر مرحله در یک فرایند چندمرحله‌ای

این مثال برای فرم‌های چندمرحله‌ای، آموزش مرحله‌ای یا آزمون کاربرد دارد. مقدار step خوانده می‌شود و بر اساس آن عملکرد مناسب اجرا می‌شود.

var step = 1;

if (await AppEditor.varIsExist("step")) {
  step = Number(await AppEditor.getVar("step")) || 1;
}

if (step === 1) {
  await AppEditor.setVar("step", 2);
  await AppEditor.runAction("goStep2");
} else if (step === 2) {
  await AppEditor.setVar("step", 3);
  await AppEditor.runAction("goStep3");
} else {
  AppEditor.showMessage("مراحل تکمیل شد");
  await AppEditor.runAction("finishSteps");
}

۷. تغییر وضعیت نمایش یک بخش

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

var showDetails = false;

if (await AppEditor.varIsExist("showDetails")) {
  showDetails = await AppEditor.getVar("showDetails");
  showDetails = showDetails === true || showDetails === "true";
} else {
  await AppEditor.addVar({
    name: "showDetails",
    storeType: "temp",
    varType: "bool",
    value: false,
    updateValueIfExists: true
  });
}

showDetails = !showDetails;
await AppEditor.setVar("showDetails", showDetails);

یادداشت

بعد از تغییر مقدار متغیر، ویجت‌هایی که شرط نمایش آن‌ها به آن متغیر وابسته است می‌توانند رفتار متفاوتی داشته باشند.

۸. انتخاب تصادفی یک پیام

در این مثال یک پیام تصادفی از بین چند متن انتخاب و نمایش داده می‌شود.

var messages = [
  "امروز یک قدم جلوتر برو!",
  "ادامه بده، نتیجه نزدیک است.",
  "هر روز بهتر از دیروز."
];

var index = Math.floor(Math.random() * messages.length);
AppEditor.showMessage(messages[index]);

۹. اجرای چند عملکرد با فاصله زمانی

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

AppEditor.showMessage("عملیات با موفقیت انجام شد");

await new Promise(function(resolve) {
  setTimeout(resolve, 1000);
});

await AppEditor.runAction("openNextPage");

هشدار

از تأخیرهای طولانی و زیاد استفاده نکنید؛ چون ممکن است کاربر تصور کند اپ متوقف شده است.

۱۰. آماده‌سازی مقدار متنی قبل از ذخیره

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

var fullName = await AppEditor.getVar("fullName");

if (fullName) {
  fullName = String(fullName).trim();
  await AppEditor.setVar("fullName", fullName);
  AppEditor.showMessage("نام ذخیره شد: " + fullName);
} else {
  AppEditor.showMessage("نام را وارد کنید");
}

۱۱. دریافت داده با درخواست GET

تابع fetch برای ارسال درخواست HTTP به یک آدرس (API) استفاده می‌شود. خروجی fetch از نوع Promise است؛ بنابراین مثل متدهای AppEditor باید با await منتظر پاسخ بمانید.

مراحل معمول کار با API:

1. ارسال درخواست با fetch(آدرس)
2. بررسی موفق بودن پاسخ با response.ok
3. تبدیل بدنه پاسخ به JSON با response.json()
4. استخراج فیلدهای موردنیاز و ذخیره در متغیر با AppEditor.setVar

در این مثال، با یک درخواست GET ساده، عنوان یک پست نمونه از JSONPlaceholder خوانده و در متغیر apiTitle ذخیره می‌شود. می‌توانید مقدار این متغیر را با ویجت نمایشگر متغیر روی صفحه نشان دهید.

var response = await fetch("https://jsonplaceholder.typicode.com/posts/1");

if (!response.ok) {
  AppEditor.showMessage("خطا در دریافت داده — کد: " + response.status);
} else {
  var data = await response.json();
  await AppEditor.setVar("apiTitle", data.title);
  AppEditor.showMessage("داده دریافت شد");
}

یادداشت

قبل از اجرای این کد، متغیر apiTitle را با عملکرد ایجاد متغیر بسازید یا در رویداد ورود به صفحه مقداردهی اولیه کنید.

۱۲. فراخوانی API با پارامتر ورودی کاربر

گاهی آدرس API باید بر اساس مقداری که کاربر وارد کرده ساخته شود؛ مثلاً متن جستجو یا شناسه یک آیتم. در این حالت ابتدا مقدار را از متغیر متصل به فیلد فرم می‌خوانید، سپس آن را در آدرس قرار می‌دهید.

var postId = Number(await AppEditor.getVar("postId")) || 0;

if (postId <= 0) {
  AppEditor.showMessage("شناسه پست را وارد کنید");
} else {
  var response = await fetch(
    "https://jsonplaceholder.typicode.com/posts/" + postId
  );

  if (!response.ok) {
    AppEditor.showMessage("پستی با این شناسه یافت نشد");
  } else {
    var data = await response.json();
    await AppEditor.setVar("postTitle", data.title);
    await AppEditor.setVar("postBody", data.body);
    AppEditor.showMessage("پست بارگذاری شد");
  }
}

نکته

برای پارامترهای متنی در آدرس URL، اگر مقدار ممکن است شامل فاصله یا کاراکترهای خاص باشد، از encodeURIComponent(مقدار) استفاده کنید.

۱۳. مدیریت خطا و حالت بارگذاری هنگام فراخوانی API

هنگام کار با API، ممکن است اینترنت قطع باشد، سرور پاسخ ندهد یا داده نامعتبر برگردد. بهتر است از try/catch استفاده کنید و با یک متغیر بولی مثل isLoading به کاربر نشان دهید درخواست در حال انجام است.

try {
  await AppEditor.setVar("isLoading", true);

  var response = await fetch("https://jsonplaceholder.typicode.com/posts/1");

  if (!response.ok) {
    throw new Error("خطای سرور — کد " + response.status);
  }

  var data = await response.json();

  if (!data || !data.title) {
    throw new Error("پاسخ API معتبر نیست");
  }

  await AppEditor.setVar("apiTitle", data.title);
  AppEditor.showMessage("با موفقیت دریافت شد");
} catch (error) {
  AppEditor.showMessage("خطا: " + error.message);
} finally {
  await AppEditor.setVar("isLoading", false);
}

می‌توانید ویجتی را با شرط نمایش به isLoading وصل کنید تا هنگام بارگذاری، متن «در حال دریافت…» نشان داده شود.

۱۴. ارسال داده با درخواست POST

برای ارسال اطلاعات به سرور (مثل ثبت فرم یا ایجاد رکورد جدید)، علاوه بر آدرس API باید متد و بدنه درخواست را هم مشخص کنید.

var name = await AppEditor.getVar("userName");
var email = await AppEditor.getVar("email");

if (!name || !email) {
  AppEditor.showMessage("نام و ایمیل را وارد کنید");
} else {
  var response = await fetch("https://jsonplaceholder.typicode.com/posts", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      title: name,
      body: email,
      userId: 1
    })
  });

  if (!response.ok) {
    AppEditor.showMessage("ارسال ناموفق بود");
  } else {
    var data = await response.json();
    await AppEditor.setVar("createdId", data.id);
    AppEditor.showMessage("ثبت شد — شناسه: " + data.id);
  }
}

هشدار

APIهای واقعی ممکن است به کلید دسترسی (API Key) یا هدر احراز هویت نیاز داشته باشند. کلیدهای حساس را فقط در صورتی در کد قرار دهید که از محدودیت‌های امنیتی آن API آگاه هستید؛ در بسیاری از سناریوها بهتر است درخواست از طریق سرور واسط شما ارسال شود.

نکته درباره CORS و خروجی وب

در خروجی اندروید معمولاً fetch مستقیماً کار می‌کند. در خروجی وب، اگر API اجازه درخواست از مرورگر را ندهد (محدودیت CORS)، ممکن است fetch با خطا مواجه شود. در این حالت از پراکسی در تنظیمات خروجی وب استفاده کنید یا درخواست را از سرور خودتان ارسال کنید.

---

الگوی پیشنهادی برای نوشتن کد

برای اینکه کد شما قابل نگهداری‌تر باشد، معمولاً این ترتیب مناسب است:

1. متغیرهای موردنیاز را بخوانید.
2. مقدارها را بررسی و تبدیل کنید.
3. تصمیم‌گیری اصلی را انجام دهید.
4. متغیرهای جدید را ذخیره کنید.
5. پیام یا عملکرد نهایی را اجرا کنید.

نمونه الگوی ساده:

// 1. خواندن داده
var value = await AppEditor.getVar("value");

// 2. آماده‌سازی
value = Number(value) || 0;

// 3. تصمیم‌گیری
if (value > 10) {
  // 4. ذخیره نتیجه
  await AppEditor.setVar("status", "ok");

  // 5. اجرای عملکرد
  await AppEditor.runAction("successAction");
} else {
  AppEditor.showMessage("مقدار کافی نیست");
}

نمونه الگوی فراخوانی API:

try {
  // 1. آماده‌سازی (اختیاری: نمایش حالت بارگذاری)
  await AppEditor.setVar("isLoading", true);

  // 2. ارسال درخواست
  var response = await fetch("https://api.example.com/data");

  // 3. بررسی پاسخ
  if (!response.ok) {
    throw new Error("خطا در دریافت داده");
  }

  // 4. تبدیل و استخراج
  var data = await response.json();
  var result = data.value;

  // 5. ذخیره در متغیر
  await AppEditor.setVar("result", result);
  AppEditor.showMessage("انجام شد");
} catch (error) {
  AppEditor.showMessage("خطا: " + error.message);
} finally {
  await AppEditor.setVar("isLoading", false);
}

مهم

کدهای طولانی را به چند سناریوی کوچک‌تر تقسیم کنید. اگر یک کد چند کار نامرتبط انجام می‌دهد، بهتر است آن را به چند عملکرد جدا تبدیل کنید.

---

نکات مهم

• خطاها: اگر در حین اجرای کد خطایی رخ دهد، معمولاً در خروجی اپ یا به صورت پیام Toast نمایش داده می‌شود.
• شناسه عملکرد: فقط عملکردهایی که در لیست همین عملکرد «اجرای کد جاوااسکریپت» اضافه و شناسه‌دار شده‌اند با AppEditor.runAction('شناسه') قابل فراخوانی هستند.
• امنیت: کد مستقیم در اپ اجرا می‌شود؛ از اجرای کدهای نامطمئن یا ورودی کاربر بدون بررسی خودداری کنید.
• نام متغیر: بهتر است نام متغیرها را لاتین، کوتاه و قابل فهم انتخاب کنید.
• ناهمگام بودن: برای متدهایی که مقدار برمی‌گردانند یا باید منتظر نتیجه آن‌ها بمانید، از await استفاده کنید.
• تست مرحله‌ای: ابتدا کد را با پیام‌های ساده مثل AppEditor.showMessage بررسی کنید و سپس عملکردهای مهم‌تر را اضافه کنید.
• مقادیر خالی: همیشه احتمال خالی بودن یا وجود نداشتن متغیر را در نظر بگیرید.
• fetch و await: خروجی fetch و response.json() هر دو Promise هستند؛ بدون await داده آماده نمی‌شود.
• اینترنت: برای فراخوانی API، دستگاه کاربر باید به اینترنت متصل باشد؛ خطای شبکه را با try/catch مدیریت کنید.
• CORS: در خروجی وب، همه APIها از مرورگر قابل فراخوانی نیستند؛ جزئیات در خروجی وب.
• API Key: کلیدهای دسترسی داخل کد اپ قابل مشاهده هستند؛ برای داده‌های حساس از سرور واسط استفاده کنید.

---