توسعه کد تکراری

به عنوان یک توسعه‌دهنده موبایل، شما اغلب رابط کاربری برنامه خود را گام به گام توسعه می‌دهید تا اینکه همه چیز را به طور همزمان توسعه دهید. اندروید استودیو با Jetpack Compose این رویکرد را با ارائه ابزارهایی که نیازی به ساخت کامل برای بررسی، تغییر مقادیر و تأیید نتیجه نهایی ندارند، پذیرفته است.

ویرایش زنده

ویرایش زنده (Live Edit) قابلیتی است که به شما امکان می‌دهد کامپوننت‌ها (composables) را در شبیه‌سازها و دستگاه‌های فیزیکی به صورت بلادرنگ به‌روزرسانی کنید. این قابلیت، جابه‌جایی‌های زمینه‌ای بین نوشتن و ساخت برنامه را به حداقل می‌رساند و به شما امکان می‌دهد بدون وقفه، مدت بیشتری روی نوشتن کد تمرکز کنید.

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

• دستی: تغییرات کد زمانی اعمال می‌شوند که با استفاده از Control+' ( Command+' در macOS) به صورت دستی اعمال شوند.
• ذخیره دستی: تغییرات کد زمانی اعمال می‌شوند که به صورت دستی با استفاده از Control+S ( Command+S در macOS) ذخیره شوند.
• خودکار: وقتی یک تابع قابل ترکیب را به‌روزرسانی می‌کنید، تغییرات در دستگاه یا شبیه‌ساز شما اعمال می‌شوند.

ویرایش زنده (Live Edit) بر تغییرات کد مربوط به رابط کاربری (UI) و تجربه کاربری (UX) متمرکز است. ویرایش زنده از تغییراتی مانند به‌روزرسانی امضای متد، افزودن متدهای جدید یا تغییرات سلسله مراتب کلاس پشتیبانی نمی‌کند. برای اطلاعات بیشتر، به فهرست محدودیت‌های ویرایش زنده (Live Edit) مراجعه کنید.

این ویژگی جایگزینی برای ساخت و اجرای برنامه یا اعمال تغییرات نیست. در عوض، برای بهینه‌سازی گردش کار شما هنگام ساخت، استقرار و تکرار برای توسعه رابط کاربری Compose طراحی شده است.

بهترین روش گردش کار به شرح زیر است:

1. برنامه خود را طوری تنظیم کنید که بتواند اجرا شود.
2. تا جایی که می‌توانید از Live Edit استفاده کنید، مگر اینکه نیاز به ایجاد تغییری داشته باشید که Live Edit از آن پشتیبانی نمی‌کند، مانند اضافه کردن متدهای جدید در حین اجرای برنامه.
3. پس از ایجاد یک تغییر پشتیبانی نشده، روی اجرا کلیک کنید برای شروع مجدد برنامه و ادامه ویرایش زنده.

با ویرایش زنده شروع کنید

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

پروژه جدید خود را تنظیم کنید

1. قبل از شروع، مطمئن شوید که Android Studio Giraffe یا نسخه‌های بالاتر آن را نصب کرده‌اید و سطح API دستگاه فیزیکی یا شبیه‌ساز شما حداقل 30 است.

2. اندروید استودیو را باز کنید و در پنجره خوشامدگویی به اندروید استودیو ، گزینه «پروژه جدید» را انتخاب کنید. اگر از قبل پروژه‌ای باز دارید، می‌توانید با رفتن به مسیر File > New > New Project، یک پروژه جدید ایجاد کنید.

3. الگوی فعالیت نوشتن خالی را برای تلفن و تبلت انتخاب کنید و سپس روی بعدی کلیک کنید.

   

4. کادر محاوره‌ای پروژه جدید را با اطلاعات مورد نیاز تکمیل کنید: نام، نام بسته، محل ذخیره، حداقل SDK و زبان پیکربندی ساخت.

   

5. روی پایان کلیک کنید.

فعال کردن ویرایش زنده

1. برای فعال کردن ویرایش زنده، به تنظیمات بروید.

   • در ویندوز یا لینوکس، به مسیر File > Settings > Editor > Live Edit بروید.
   • در macOS، به Android Studio > Settings > Editor > Live Edit بروید.

2. گزینه Live Edit و حالتی که می‌خواهید اجرا شود را از تنظیمات انتخاب کنید.

   در حالت دستی، تغییرات کد شما هر بار که Control+' ( Command+' در macOS) را فشار دهید، اعمال می‌شوند. در حالت دستی هنگام ذخیره، تغییرات کد شما هر بار که به صورت دستی با استفاده از Control + S ( Command + S در macOS) ذخیره می‌کنید، اعمال می‌شوند. در حالت خودکار، تغییرات کد شما همزمان با ایجاد تغییرات، در دستگاه یا شبیه‌ساز شما اعمال می‌شوند.

   

3. در ویرایشگر، فایل MainActivity را که نقطه ورود برنامه شماست، باز کنید.

4. روی اجرا کلیک کنید برای استقرار برنامه شما.

5. بعد از اینکه Live Edit را فعال کردید، علامت تیک سبز رنگ Up-to-date در سمت راست بالای پنجره ابزار Running Devices ظاهر می‌شود:

   

ایجاد و بررسی تغییرات

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

برای مثال، متد Greeting موجود در MainActivity را به صورت زیر ویرایش کنید:

@Composable
fun Greeting(name: String) {
    Text(
        text = "Hello $name!",
        Modifier
            .padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}
IterativeDevelopmentSnippets.kt

تغییرات شما فوراً روی دستگاه آزمایشی ظاهر می‌شوند، همانطور که در شکل ۴ نشان داده شده است.

عیب‌یابی ویرایش زنده

اگر ویرایش‌های خود را در دستگاه آزمایشی مشاهده نمی‌کنید، ممکن است اندروید استودیو در به‌روزرسانی ویرایش‌های شما ناموفق بوده باشد. بررسی کنید که آیا نشانگر Live Edit، همانطور که در شکل 5 نشان داده شده است، عبارت «Out Of Date» را نشان می‌دهد یا خیر، که نشان‌دهنده‌ی خطای کامپایل است. برای کسب اطلاعات در مورد خطا و پیشنهادهایی برای رفع آن، روی نشانگر کلیک کنید.

محدودیت‌های ویرایش زنده

در ادامه فهرستی از محدودیت‌های فعلی آمده است.

• [فقط برای اندروید استودیو Giraffe و نسخه‌های بالاتر اعمال می‌شود] Live Edit نیاز به Compose Runtime نسخه ۱.۳.۰ یا بالاتر دارد. اگر پروژه شما از نسخه پایین‌تر Compose استفاده می‌کند، Live Edit غیرفعال است.

• [فقط برای اندروید استودیو Giraffe و نسخه‌های بالاتر اعمال می‌شود] Live Edit به AGP 8.1.0-alpha05 یا بالاتر نیاز دارد. اگر پروژه شما از نسخه پایین‌تر AGP استفاده می‌کند، Live Edit غیرفعال است.

• ویرایش زنده به یک دستگاه فیزیکی یا شبیه‌ساز نیاز دارد که API سطح 30 یا بالاتر را اجرا کند.

• ویرایش زنده فقط از ویرایش بدنه تابع پشتیبانی می‌کند، به این معنی که نمی‌توانید نام تابع یا امضای آن را تغییر دهید، تابعی را اضافه یا حذف کنید یا فیلدهای غیرتابعی را تغییر دهید.

• ویرایش زنده، وضعیت برنامه را در اولین باری که یک تابع Compose را در یک فایل تغییر می‌دهید، بازنشانی می‌کند. این اتفاق فقط پس از اولین تغییر کد رخ می‌دهد - وضعیت برنامه با تغییرات کد بعدی که در توابع Compose در آن فایل ایجاد می‌کنید، بازنشانی نمی‌شود.

• کلاس‌های اصلاح‌شده در ویرایش زنده ممکن است دچار مقداری افت عملکرد شوند. برنامه خود را اجرا کنید و اگر عملکرد آن را ارزیابی می‌کنید، از یک نسخه آزمایشی (clean release build) استفاده کنید.

• برای اینکه اشکال‌زدا بتواند روی کلاس‌هایی که با Live Edit تغییر داده‌اید، عمل کند، باید یک اجرای کامل انجام دهید.

• ممکن است یک برنامه در حال اجرا هنگام ویرایش با Live Edit از کار بیفتد. در این صورت، می‌توانید برنامه را با Run مجدداً راه‌اندازی کنید. دکمه

• ویرایش زنده هیچ دستکاری بایت‌کدی را که در فایل ساخت پروژه شما تعریف شده است، انجام نمی‌دهد - برای مثال، دستکاری بایت‌کدی که هنگام ساخت پروژه با استفاده از گزینه‌های موجود در منوی ساخت یا با کلیک بر روی دکمه‌های ساخت یا اجرا اعمال می‌شود.

• توابع غیر قابل ترکیب (Non-Composable) به صورت زنده روی دستگاه یا شبیه‌ساز به‌روزرسانی می‌شوند و یک ترکیب‌بندی کامل آغاز می‌شود. ترکیب‌بندی کامل ممکن است تابع به‌روزرسانی‌شده را فراخوانی نکند. برای توابع غیر قابل ترکیب، باید توابع تازه به‌روزرسانی‌شده را آغاز کنید یا برنامه را دوباره اجرا کنید.

• ویرایش زنده با راه‌اندازی مجدد برنامه از سر گرفته نمی‌شود. باید برنامه را دوباره اجرا کنید.

• ویرایش زنده فقط از فرآیندهای قابل اشکال‌زدایی پشتیبانی می‌کند.

• ویرایش زنده از پروژه‌هایی که از مقادیر سفارشی برای moduleName در kotlinOptions در پیکربندی ساخت استفاده می‌کنند، پشتیبانی نمی‌کند.

• Live Edit با استقرارهای چندگانه کار نمی‌کند. این بدان معناست که شما نمی‌توانید ابتدا برنامه را روی یک دستگاه و سپس روی دستگاه دیگر مستقر کنید. Live Edit فقط روی آخرین مجموعه دستگاه‌هایی که برنامه روی آنها مستقر شده است، فعال است.

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

• اعمال تغییرات/اعمال تغییرات کد با Live Edit سازگار نیستند و نیاز به راه‌اندازی مجدد برنامه در حال اجرا دارند.

• ویرایش زنده در حال حاضر از پروژه‌های خودروسازی اندروید پشتیبانی نمی‌کند.

سوالات متداول در مورد ویرایش زنده

• وضعیت فعلی Live Edit چگونه است؟

  قابلیت ویرایش زنده (Live Edit) در اندروید استودیو زرافه (Giraffe) موجود است. برای فعال کردن آن، به مسیر File > Settings > Editor > Live Edit (در مک او اس به مسیر Android Studio > Settings > Editor > Live Edit ) بروید.

• چه زمانی باید از ویرایش زنده استفاده کنم؟

  وقتی می‌خواهید تأثیر به‌روزرسانی‌های عناصر تجربه کاربری (مانند به‌روزرسانی‌های اصلاح‌کننده‌ها و انیمیشن‌ها) را بر تجربه کلی برنامه به سرعت مشاهده کنید، از ویرایش زنده (Live Edit) استفاده کنید.

• چه زمانی باید از استفاده از ویرایش زنده خودداری کنم؟

  ویرایش زنده (Live Edit) بر تغییرات کد مربوط به رابط کاربری (UI) و تجربه کاربری (UX) متمرکز است. این ابزار از تغییراتی مانند به‌روزرسانی امضای متد، افزودن متدهای جدید یا تغییرات سلسله مراتب کلاس پشتیبانی نمی‌کند. برای اطلاعات بیشتر، به محدودیت‌های ویرایش زنده (Live Edit) مراجعه کنید.

• چه زمانی باید از پیش‌نمایش نوشتن استفاده کنم؟

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

توسعه کد تکراری با Compose

ویرایش زنده و بارگذاری مجدد سریع برای Compose Multiplatform ویژگی‌هایی هستند که می‌توانند در زمان شما صرفه‌جویی کرده و بهره‌وری شما را هنگام توسعه با Compose افزایش دهند. با این حال، آنها نیازهای انواع مختلف توسعه را برآورده می‌کنند:

• ویرایش زنده از توسعه تکراری با Jetpack Compose برای برنامه‌های اندروید پشتیبانی می‌کند. این به شما امکان می‌دهد composables را در شبیه‌سازها و دستگاه‌های فیزیکی به صورت بلادرنگ به‌روزرسانی کنید. این قابلیت، جابجایی‌های زمینه‌ای بین نوشتن و ساخت برنامه شما را به حداقل می‌رساند و به شما امکان می‌دهد بدون وقفه، مدت بیشتری روی نوشتن کد تمرکز کنید.

• قابلیت Compose Hot Reload نیز همین نیاز را برطرف می‌کند، اما از برنامه‌های دسکتاپ ساخته شده با Compose Multiplatform پشتیبانی می‌کند. این قابلیت به شما امکان می‌دهد تا در یک برنامه Compose Multiplatform، تغییراتی در کد رابط کاربری خود ایجاد کنید و با بارگذاری مجدد هوشمند کد خود در هر زمان که تغییر می‌کند، نتایج را به صورت بلادرنگ مشاهده کنید.

اگرچه این دو ویژگی، فناوری‌های مشترک زیادی در موتور Compose دارند و از موارد استفاده مشابه زیادی پشتیبانی می‌کنند، اما قابلیت‌های یکسانی ندارند زیرا در انواع مختلف توسعه Compose اعمال می‌شوند.

اگر در حال توسعه یک اپلیکیشن اندروید هستید، باید از Live Edit برای سرعت بخشیدن به فرآیند توسعه خود استفاده کنید. اگر در حال توسعه یک اپلیکیشن دسکتاپ با استفاده از Compose Multiplatform هستید، باید از Compose Hot Reload استفاده کنید.

ویرایش زنده‌ی حروف (منسوخ شده)

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

• Int
• String
• Color
• Dp
• Boolean

شما می‌توانید با فعال کردن تزئینات لیترال از طریق نشانگر رابط کاربری Live Edit of literals، لیترال‌های ثابتی را مشاهده کنید که به‌روزرسانی‌های بلادرنگ را بدون مرحله کامپایل فعال می‌کنند:

اعمال تغییرات

اعمال تغییرات به شما امکان می‌دهد کد و منابع را بدون نیاز به استقرار مجدد برنامه خود در یک شبیه‌ساز یا دستگاه فیزیکی (با برخی محدودیت‌ها ) به‌روزرسانی کنید.

هر زمان که composableها را اضافه، اصلاح یا حذف می‌کنید، می‌توانید برنامه خود را بدون نیاز به استقرار مجدد، با کلیک بر روی دکمه «اعمال تغییرات کد» به‌روزرسانی کنید:

به عنوان یک توسعه‌دهنده موبایل، شما اغلب رابط کاربری برنامه خود را گام به گام توسعه می‌دهید تا اینکه همه چیز را به طور همزمان توسعه دهید. اندروید استودیو با Jetpack Compose این رویکرد را با ارائه ابزارهایی که نیازی به ساخت کامل برای بررسی، تغییر مقادیر و تأیید نتیجه نهایی ندارند، پذیرفته است.

ویرایش زنده

ویرایش زنده (Live Edit) قابلیتی است که به شما امکان می‌دهد کامپوننت‌ها (composables) را در شبیه‌سازها و دستگاه‌های فیزیکی به صورت بلادرنگ به‌روزرسانی کنید. این قابلیت، جابه‌جایی‌های زمینه‌ای بین نوشتن و ساخت برنامه را به حداقل می‌رساند و به شما امکان می‌دهد بدون وقفه، مدت بیشتری روی نوشتن کد تمرکز کنید.

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

• دستی: تغییرات کد زمانی اعمال می‌شوند که با استفاده از Control+' ( Command+' در macOS) به صورت دستی اعمال شوند.
• ذخیره دستی: تغییرات کد زمانی اعمال می‌شوند که به صورت دستی با استفاده از Control+S ( Command+S در macOS) ذخیره شوند.
• خودکار: وقتی یک تابع قابل ترکیب را به‌روزرسانی می‌کنید، تغییرات در دستگاه یا شبیه‌ساز شما اعمال می‌شوند.

ویرایش زنده (Live Edit) بر تغییرات کد مربوط به رابط کاربری (UI) و تجربه کاربری (UX) متمرکز است. ویرایش زنده از تغییراتی مانند به‌روزرسانی امضای متد، افزودن متدهای جدید یا تغییرات سلسله مراتب کلاس پشتیبانی نمی‌کند. برای اطلاعات بیشتر، به فهرست محدودیت‌های ویرایش زنده (Live Edit) مراجعه کنید.

این ویژگی جایگزینی برای ساخت و اجرای برنامه یا اعمال تغییرات نیست. در عوض، برای بهینه‌سازی گردش کار شما هنگام ساخت، استقرار و تکرار برای توسعه رابط کاربری Compose طراحی شده است.

بهترین روش گردش کار به شرح زیر است:

1. برنامه خود را طوری تنظیم کنید که بتواند اجرا شود.
2. تا جایی که می‌توانید از Live Edit استفاده کنید، مگر اینکه نیاز به ایجاد تغییری داشته باشید که Live Edit از آن پشتیبانی نمی‌کند، مانند اضافه کردن متدهای جدید در حین اجرای برنامه.
3. پس از ایجاد یک تغییر پشتیبانی نشده، روی اجرا کلیک کنید برای شروع مجدد برنامه و ادامه ویرایش زنده.

با ویرایش زنده شروع کنید

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

پروژه جدید خود را تنظیم کنید

1. قبل از شروع، مطمئن شوید که Android Studio Giraffe یا نسخه‌های بالاتر آن را نصب کرده‌اید و سطح API دستگاه فیزیکی یا شبیه‌ساز شما حداقل 30 است.

2. اندروید استودیو را باز کنید و در پنجره خوشامدگویی به اندروید استودیو ، گزینه «پروژه جدید» را انتخاب کنید. اگر از قبل پروژه‌ای باز دارید، می‌توانید با رفتن به مسیر File > New > New Project، یک پروژه جدید ایجاد کنید.

3. الگوی فعالیت نوشتن خالی را برای تلفن و تبلت انتخاب کنید و سپس روی بعدی کلیک کنید.

   

4. کادر محاوره‌ای پروژه جدید را با اطلاعات مورد نیاز تکمیل کنید: نام، نام بسته، محل ذخیره، حداقل SDK و زبان پیکربندی ساخت.

   

5. روی پایان کلیک کنید.

فعال کردن ویرایش زنده

1. برای فعال کردن ویرایش زنده، به تنظیمات بروید.

   • در ویندوز یا لینوکس، به مسیر File > Settings > Editor > Live Edit بروید.
   • در macOS، به Android Studio > Settings > Editor > Live Edit بروید.

2. گزینه Live Edit و حالتی که می‌خواهید اجرا شود را از تنظیمات انتخاب کنید.

   در حالت دستی، تغییرات کد شما هر بار که Control+' ( Command+' در macOS) را فشار دهید، اعمال می‌شوند. در حالت دستی هنگام ذخیره، تغییرات کد شما هر بار که به صورت دستی با استفاده از Control + S ( Command + S در macOS) ذخیره می‌کنید، اعمال می‌شوند. در حالت خودکار، تغییرات کد شما همزمان با ایجاد تغییرات، در دستگاه یا شبیه‌ساز شما اعمال می‌شوند.

   

3. در ویرایشگر، فایل MainActivity را که نقطه ورود برنامه شماست، باز کنید.

4. روی اجرا کلیک کنید برای استقرار برنامه شما.

5. بعد از اینکه Live Edit را فعال کردید، علامت تیک سبز رنگ Up-to-date در سمت راست بالای پنجره ابزار Running Devices ظاهر می‌شود:

   

ایجاد و بررسی تغییرات

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

برای مثال، متد Greeting موجود در MainActivity را به صورت زیر ویرایش کنید:

@Composable
fun Greeting(name: String) {
    Text(
        text = "Hello $name!",
        Modifier
            .padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}
IterativeDevelopmentSnippets.kt

تغییرات شما فوراً روی دستگاه آزمایشی ظاهر می‌شوند، همانطور که در شکل ۴ نشان داده شده است.

عیب‌یابی ویرایش زنده

اگر ویرایش‌های خود را در دستگاه آزمایشی مشاهده نمی‌کنید، ممکن است اندروید استودیو در به‌روزرسانی ویرایش‌های شما ناموفق بوده باشد. بررسی کنید که آیا نشانگر Live Edit، همانطور که در شکل 5 نشان داده شده است، عبارت «Out Of Date» را نشان می‌دهد یا خیر، که نشان‌دهنده‌ی خطای کامپایل است. برای کسب اطلاعات در مورد خطا و پیشنهادهایی برای رفع آن، روی نشانگر کلیک کنید.

محدودیت‌های ویرایش زنده

در ادامه فهرستی از محدودیت‌های فعلی آمده است.

• [فقط برای اندروید استودیو Giraffe و نسخه‌های بالاتر اعمال می‌شود] Live Edit نیاز به Compose Runtime نسخه ۱.۳.۰ یا بالاتر دارد. اگر پروژه شما از نسخه پایین‌تر Compose استفاده می‌کند، Live Edit غیرفعال است.

• [فقط برای اندروید استودیو Giraffe و نسخه‌های بالاتر اعمال می‌شود] Live Edit به AGP 8.1.0-alpha05 یا بالاتر نیاز دارد. اگر پروژه شما از نسخه پایین‌تر AGP استفاده می‌کند، Live Edit غیرفعال است.

• ویرایش زنده به یک دستگاه فیزیکی یا شبیه‌ساز نیاز دارد که API سطح 30 یا بالاتر را اجرا کند.

• ویرایش زنده فقط از ویرایش بدنه تابع پشتیبانی می‌کند، به این معنی که نمی‌توانید نام تابع یا امضای آن را تغییر دهید، تابعی را اضافه یا حذف کنید یا فیلدهای غیرتابعی را تغییر دهید.

• ویرایش زنده، وضعیت برنامه را در اولین باری که یک تابع Compose را در یک فایل تغییر می‌دهید، بازنشانی می‌کند. این اتفاق فقط پس از اولین تغییر کد رخ می‌دهد - وضعیت برنامه با تغییرات کد بعدی که در توابع Compose در آن فایل ایجاد می‌کنید، بازنشانی نمی‌شود.

• کلاس‌های اصلاح‌شده در ویرایش زنده ممکن است دچار مقداری افت عملکرد شوند. برنامه خود را اجرا کنید و اگر عملکرد آن را ارزیابی می‌کنید، از یک نسخه آزمایشی (clean release build) استفاده کنید.

• برای اینکه اشکال‌زدا بتواند روی کلاس‌هایی که با Live Edit تغییر داده‌اید، عمل کند، باید یک اجرای کامل انجام دهید.

• ممکن است یک برنامه در حال اجرا هنگام ویرایش با Live Edit از کار بیفتد. در این صورت، می‌توانید برنامه را با Run مجدداً راه‌اندازی کنید. دکمه

• ویرایش زنده هیچ دستکاری بایت‌کدی را که در فایل ساخت پروژه شما تعریف شده است، انجام نمی‌دهد - برای مثال، دستکاری بایت‌کدی که هنگام ساخت پروژه با استفاده از گزینه‌های موجود در منوی ساخت یا با کلیک بر روی دکمه‌های ساخت یا اجرا اعمال می‌شود.

• توابع غیر قابل ترکیب (Non-Composable) به صورت زنده روی دستگاه یا شبیه‌ساز به‌روزرسانی می‌شوند و یک ترکیب‌بندی کامل آغاز می‌شود. ترکیب‌بندی کامل ممکن است تابع به‌روزرسانی‌شده را فراخوانی نکند. برای توابع غیر قابل ترکیب، باید توابع تازه به‌روزرسانی‌شده را آغاز کنید یا برنامه را دوباره اجرا کنید.

• ویرایش زنده با راه‌اندازی مجدد برنامه از سر گرفته نمی‌شود. باید برنامه را دوباره اجرا کنید.

• ویرایش زنده فقط از فرآیندهای قابل اشکال‌زدایی پشتیبانی می‌کند.

• ویرایش زنده از پروژه‌هایی که از مقادیر سفارشی برای moduleName در kotlinOptions در پیکربندی ساخت استفاده می‌کنند، پشتیبانی نمی‌کند.

• Live Edit با استقرارهای چندگانه کار نمی‌کند. این بدان معناست که شما نمی‌توانید ابتدا برنامه را روی یک دستگاه و سپس روی دستگاه دیگر مستقر کنید. Live Edit فقط روی آخرین مجموعه دستگاه‌هایی که برنامه روی آنها مستقر شده است، فعال است.

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

• اعمال تغییرات/اعمال تغییرات کد با Live Edit سازگار نیستند و نیاز به راه‌اندازی مجدد برنامه در حال اجرا دارند.

• ویرایش زنده در حال حاضر از پروژه‌های خودروسازی اندروید پشتیبانی نمی‌کند.

سوالات متداول در مورد ویرایش زنده

• وضعیت فعلی Live Edit چگونه است؟

  قابلیت ویرایش زنده (Live Edit) در اندروید استودیو زرافه (Giraffe) موجود است. برای فعال کردن آن، به مسیر File > Settings > Editor > Live Edit (در مک او اس به مسیر Android Studio > Settings > Editor > Live Edit ) بروید.

• چه زمانی باید از ویرایش زنده استفاده کنم؟

  وقتی می‌خواهید تأثیر به‌روزرسانی‌های عناصر تجربه کاربری (مانند به‌روزرسانی‌های اصلاح‌کننده‌ها و انیمیشن‌ها) را بر تجربه کلی برنامه به سرعت مشاهده کنید، از ویرایش زنده (Live Edit) استفاده کنید.

• چه زمانی باید از استفاده از ویرایش زنده خودداری کنم؟

  ویرایش زنده (Live Edit) بر تغییرات کد مربوط به رابط کاربری (UI) و تجربه کاربری (UX) متمرکز است. این ابزار از تغییراتی مانند به‌روزرسانی امضای متد، افزودن متدهای جدید یا تغییرات سلسله مراتب کلاس پشتیبانی نمی‌کند. برای اطلاعات بیشتر، به محدودیت‌های ویرایش زنده (Live Edit) مراجعه کنید.

• چه زمانی باید از پیش‌نمایش نوشتن استفاده کنم؟

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

توسعه کد تکراری با Compose

ویرایش زنده و بارگذاری مجدد سریع برای Compose Multiplatform ویژگی‌هایی هستند که می‌توانند در زمان شما صرفه‌جویی کرده و بهره‌وری شما را هنگام توسعه با Compose افزایش دهند. با این حال، آنها نیازهای انواع مختلف توسعه را برآورده می‌کنند:

• ویرایش زنده از توسعه تکراری با Jetpack Compose برای برنامه‌های اندروید پشتیبانی می‌کند. این به شما امکان می‌دهد composables را در شبیه‌سازها و دستگاه‌های فیزیکی به صورت بلادرنگ به‌روزرسانی کنید. این قابلیت، جابجایی‌های زمینه‌ای بین نوشتن و ساخت برنامه شما را به حداقل می‌رساند و به شما امکان می‌دهد بدون وقفه، مدت بیشتری روی نوشتن کد تمرکز کنید.

• قابلیت Compose Hot Reload نیز همین نیاز را برطرف می‌کند، اما از برنامه‌های دسکتاپ ساخته شده با Compose Multiplatform پشتیبانی می‌کند. این قابلیت به شما امکان می‌دهد تا در یک برنامه Compose Multiplatform، تغییراتی در کد رابط کاربری خود ایجاد کنید و با بارگذاری مجدد هوشمند کد خود در هر زمان که تغییر می‌کند، نتایج را به صورت بلادرنگ مشاهده کنید.

اگرچه این دو ویژگی، فناوری‌های مشترک زیادی در موتور Compose دارند و از موارد استفاده مشابه زیادی پشتیبانی می‌کنند، اما قابلیت‌های یکسانی ندارند زیرا در انواع مختلف توسعه Compose اعمال می‌شوند.

اگر در حال توسعه یک اپلیکیشن اندروید هستید، باید از Live Edit برای سرعت بخشیدن به فرآیند توسعه خود استفاده کنید. اگر در حال توسعه یک اپلیکیشن دسکتاپ با استفاده از Compose Multiplatform هستید، باید از Compose Hot Reload استفاده کنید.

ویرایش زنده‌ی حروف (منسوخ شده)

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

• Int
• String
• Color
• Dp
• Boolean

شما می‌توانید با فعال کردن تزئینات لیترال از طریق نشانگر رابط کاربری Live Edit of literals، لیترال‌های ثابتی را مشاهده کنید که به‌روزرسانی‌های بلادرنگ را بدون مرحله کامپایل فعال می‌کنند:

اعمال تغییرات

اعمال تغییرات به شما امکان می‌دهد کد و منابع را بدون نیاز به استقرار مجدد برنامه خود در یک شبیه‌ساز یا دستگاه فیزیکی (با برخی محدودیت‌ها ) به‌روزرسانی کنید.

هر زمان که composableها را اضافه، اصلاح یا حذف می‌کنید، می‌توانید برنامه خود را بدون نیاز به استقرار مجدد، با کلیک بر روی دکمه «اعمال تغییرات کد» به‌روزرسانی کنید:

به عنوان یک توسعه‌دهنده موبایل، شما اغلب رابط کاربری برنامه خود را گام به گام توسعه می‌دهید تا اینکه همه چیز را به طور همزمان توسعه دهید. اندروید استودیو با Jetpack Compose این رویکرد را با ارائه ابزارهایی که نیازی به ساخت کامل برای بررسی، تغییر مقادیر و تأیید نتیجه نهایی ندارند، پذیرفته است.

ویرایش زنده

ویرایش زنده (Live Edit) قابلیتی است که به شما امکان می‌دهد کامپوننت‌ها (composables) را در شبیه‌سازها و دستگاه‌های فیزیکی به صورت بلادرنگ به‌روزرسانی کنید. این قابلیت، جابه‌جایی‌های زمینه‌ای بین نوشتن و ساخت برنامه را به حداقل می‌رساند و به شما امکان می‌دهد بدون وقفه، مدت بیشتری روی نوشتن کد تمرکز کنید.

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

• دستی: تغییرات کد زمانی اعمال می‌شوند که با استفاده از Control+' ( Command+' در macOS) به صورت دستی اعمال شوند.
• ذخیره دستی: تغییرات کد زمانی اعمال می‌شوند که به صورت دستی با استفاده از Control+S ( Command+S در macOS) ذخیره شوند.
• خودکار: وقتی یک تابع قابل ترکیب را به‌روزرسانی می‌کنید، تغییرات در دستگاه یا شبیه‌ساز شما اعمال می‌شوند.

ویرایش زنده (Live Edit) بر تغییرات کد مربوط به رابط کاربری (UI) و تجربه کاربری (UX) متمرکز است. ویرایش زنده از تغییراتی مانند به‌روزرسانی امضای متد، افزودن متدهای جدید یا تغییرات سلسله مراتب کلاس پشتیبانی نمی‌کند. برای اطلاعات بیشتر، به فهرست محدودیت‌های ویرایش زنده (Live Edit) مراجعه کنید.

این ویژگی جایگزینی برای ساخت و اجرای برنامه یا اعمال تغییرات نیست. در عوض، برای بهینه‌سازی گردش کار شما هنگام ساخت، استقرار و تکرار برای توسعه رابط کاربری Compose طراحی شده است.

بهترین روش گردش کار به شرح زیر است:

1. برنامه خود را طوری تنظیم کنید که بتواند اجرا شود.
2. تا جایی که می‌توانید از Live Edit استفاده کنید، مگر اینکه نیاز به ایجاد تغییری داشته باشید که Live Edit از آن پشتیبانی نمی‌کند، مانند اضافه کردن متدهای جدید در حین اجرای برنامه.
3. پس از ایجاد یک تغییر پشتیبانی نشده، روی اجرا کلیک کنید برای شروع مجدد برنامه و ادامه ویرایش زنده.

با ویرایش زنده شروع کنید

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

پروژه جدید خود را تنظیم کنید

1. قبل از شروع، مطمئن شوید که Android Studio Giraffe یا نسخه‌های بالاتر آن را نصب کرده‌اید و سطح API دستگاه فیزیکی یا شبیه‌ساز شما حداقل 30 است.

2. اندروید استودیو را باز کنید و در پنجره خوشامدگویی به اندروید استودیو ، گزینه «پروژه جدید» را انتخاب کنید. اگر از قبل پروژه‌ای باز دارید، می‌توانید با رفتن به مسیر File > New > New Project، یک پروژه جدید ایجاد کنید.

3. الگوی فعالیت نوشتن خالی را برای تلفن و تبلت انتخاب کنید و سپس روی بعدی کلیک کنید.

   

4. کادر محاوره‌ای پروژه جدید را با اطلاعات مورد نیاز تکمیل کنید: نام، نام بسته، محل ذخیره، حداقل SDK و زبان پیکربندی ساخت.

   

5. روی پایان کلیک کنید.

فعال کردن ویرایش زنده

1. برای فعال کردن ویرایش زنده، به تنظیمات بروید.

   • در ویندوز یا لینوکس، به مسیر File > Settings > Editor > Live Edit بروید.
   • در macOS، به Android Studio > Settings > Editor > Live Edit بروید.

2. گزینه Live Edit و حالتی که می‌خواهید اجرا شود را از تنظیمات انتخاب کنید.

   در حالت دستی، تغییرات کد شما هر بار که Control+' ( Command+' در macOS) را فشار دهید، اعمال می‌شوند. در حالت دستی هنگام ذخیره، تغییرات کد شما هر بار که به صورت دستی با استفاده از Control + S ( Command + S در macOS) ذخیره می‌کنید، اعمال می‌شوند. در حالت خودکار، تغییرات کد شما همزمان با ایجاد تغییرات، در دستگاه یا شبیه‌ساز شما اعمال می‌شوند.

   

3. در ویرایشگر، فایل MainActivity را که نقطه ورود برنامه شماست، باز کنید.

4. روی اجرا کلیک کنید برای استقرار برنامه شما.

5. بعد از اینکه Live Edit را فعال کردید، علامت تیک سبز رنگ Up-to-date در سمت راست بالای پنجره ابزار Running Devices ظاهر می‌شود:

   

ایجاد و بررسی تغییرات

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

برای مثال، متد Greeting موجود در MainActivity را به صورت زیر ویرایش کنید:

@Composable
fun Greeting(name: String) {
    Text(
        text = "Hello $name!",
        Modifier
            .padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}
IterativeDevelopmentSnippets.kt

تغییرات شما فوراً روی دستگاه آزمایشی ظاهر می‌شوند، همانطور که در شکل ۴ نشان داده شده است.

عیب‌یابی ویرایش زنده

اگر ویرایش‌های خود را در دستگاه آزمایشی مشاهده نمی‌کنید، ممکن است اندروید استودیو در به‌روزرسانی ویرایش‌های شما ناموفق بوده باشد. بررسی کنید که آیا نشانگر Live Edit، همانطور که در شکل 5 نشان داده شده است، عبارت «Out Of Date» را نشان می‌دهد یا خیر، که نشان‌دهنده‌ی خطای کامپایل است. برای کسب اطلاعات در مورد خطا و پیشنهادهایی برای رفع آن، روی نشانگر کلیک کنید.

محدودیت‌های ویرایش زنده

در ادامه فهرستی از محدودیت‌های فعلی آمده است.

• [فقط برای اندروید استودیو Giraffe و نسخه‌های بالاتر اعمال می‌شود] Live Edit نیاز به Compose Runtime نسخه ۱.۳.۰ یا بالاتر دارد. اگر پروژه شما از نسخه پایین‌تر Compose استفاده می‌کند، Live Edit غیرفعال است.

• [فقط برای اندروید استودیو Giraffe و نسخه‌های بالاتر اعمال می‌شود] Live Edit به AGP 8.1.0-alpha05 یا بالاتر نیاز دارد. اگر پروژه شما از نسخه پایین‌تر AGP استفاده می‌کند، Live Edit غیرفعال است.

• ویرایش زنده به یک دستگاه فیزیکی یا شبیه‌ساز نیاز دارد که API سطح 30 یا بالاتر را اجرا کند.

• ویرایش زنده فقط از ویرایش بدنه تابع پشتیبانی می‌کند، به این معنی که نمی‌توانید نام تابع یا امضای آن را تغییر دهید، تابعی را اضافه یا حذف کنید یا فیلدهای غیرتابعی را تغییر دهید.

• ویرایش زنده، وضعیت برنامه را در اولین باری که یک تابع Compose را در یک فایل تغییر می‌دهید، بازنشانی می‌کند. این اتفاق فقط پس از اولین تغییر کد رخ می‌دهد - وضعیت برنامه با تغییرات کد بعدی که در توابع Compose در آن فایل ایجاد می‌کنید، بازنشانی نمی‌شود.

• کلاس‌های اصلاح‌شده در ویرایش زنده ممکن است دچار مقداری افت عملکرد شوند. برنامه خود را اجرا کنید و اگر عملکرد آن را ارزیابی می‌کنید، از یک نسخه آزمایشی (clean release build) استفاده کنید.

• برای اینکه اشکال‌زدا بتواند روی کلاس‌هایی که با Live Edit تغییر داده‌اید، عمل کند، باید یک اجرای کامل انجام دهید.

• ممکن است یک برنامه در حال اجرا هنگام ویرایش با Live Edit از کار بیفتد. در این صورت، می‌توانید برنامه را با Run مجدداً راه‌اندازی کنید. دکمه

• ویرایش زنده هیچ دستکاری بایت‌کدی را که در فایل ساخت پروژه شما تعریف شده است، انجام نمی‌دهد - برای مثال، دستکاری بایت‌کدی که هنگام ساخت پروژه با استفاده از گزینه‌های موجود در منوی ساخت یا با کلیک بر روی دکمه‌های ساخت یا اجرا اعمال می‌شود.

• توابع غیر قابل ترکیب (Non-Composable) به صورت زنده روی دستگاه یا شبیه‌ساز به‌روزرسانی می‌شوند و یک ترکیب‌بندی کامل آغاز می‌شود. ترکیب‌بندی کامل ممکن است تابع به‌روزرسانی‌شده را فراخوانی نکند. برای توابع غیر قابل ترکیب، باید توابع تازه به‌روزرسانی‌شده را آغاز کنید یا برنامه را دوباره اجرا کنید.

• ویرایش زنده با راه‌اندازی مجدد برنامه از سر گرفته نمی‌شود. باید برنامه را دوباره اجرا کنید.

• ویرایش زنده فقط از فرآیندهای قابل اشکال‌زدایی پشتیبانی می‌کند.

• ویرایش زنده از پروژه‌هایی که از مقادیر سفارشی برای moduleName در kotlinOptions در پیکربندی ساخت استفاده می‌کنند، پشتیبانی نمی‌کند.

• Live Edit با استقرارهای چندگانه کار نمی‌کند. این بدان معناست که شما نمی‌توانید ابتدا برنامه را روی یک دستگاه و سپس روی دستگاه دیگر مستقر کنید. Live Edit فقط روی آخرین مجموعه دستگاه‌هایی که برنامه روی آنها مستقر شده است، فعال است.

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

• اعمال تغییرات/اعمال تغییرات کد با Live Edit سازگار نیستند و نیاز به راه‌اندازی مجدد برنامه در حال اجرا دارند.

• ویرایش زنده در حال حاضر از پروژه‌های خودروسازی اندروید پشتیبانی نمی‌کند.

سوالات متداول در مورد ویرایش زنده

• وضعیت فعلی Live Edit چگونه است؟

  قابلیت ویرایش زنده (Live Edit) در اندروید استودیو زرافه (Giraffe) موجود است. برای فعال کردن آن، به مسیر File > Settings > Editor > Live Edit (در مک او اس به مسیر Android Studio > Settings > Editor > Live Edit ) بروید.

• چه زمانی باید از ویرایش زنده استفاده کنم؟

  وقتی می‌خواهید تأثیر به‌روزرسانی‌های عناصر تجربه کاربری (مانند به‌روزرسانی‌های اصلاح‌کننده‌ها و انیمیشن‌ها) را بر تجربه کلی برنامه به سرعت مشاهده کنید، از ویرایش زنده (Live Edit) استفاده کنید.

• چه زمانی باید از استفاده از ویرایش زنده خودداری کنم؟

  Live Edit is focused on UI- and UX-related code changes. It doesn't support changes such as method signature updates, adding new methods, or class hierarchy changes. For more information, see Limitations of Live Edit .

• When should I use Compose Preview?

  Use Compose Preview when you're developing individual composables. Preview visualizes Compose elements and automatically refreshes to display the effect of code changes. Preview also supports viewing UI elements under different configurations and states, such as dark theme, locales, and font scale.

Iterative code development with Compose

Live Edit and Hot Reload for Compose Multiplatform are features that can save you time and increase your productivity as you develop with Compose. However, they serve the needs of different types of development:

• Live Edit supports iterative development with Jetpack Compose for Android applications . It lets you update composables in emulators and physical devices in real time. This functionality minimizes context switches between writing and building your app, letting you focus on writing code for longer without interruption.

• Compose Hot Reload serves the same need, but supports desktop applications built with Compose Multiplatform . It enables you to make changes to your UI code in a Compose Multiplatform application and see the results in real time by intelligently reloading your code whenever it is changed.

While these two features share many technologies within the Compose engine and support many similar use cases, they do not have the same capabilities because they apply to different types of Compose development.

If you are developing an Android app, you should use Live Edit to accelerate your development process. If you are developing a desktop application using Compose Multiplatform, you should use Compose Hot Reload.

Live Edit of literals (deprecated)

Android Studio can update in real time some constant literals used in composables within previews, emulator, and physical device. Here are some supported types:

• Int
• String
• Color
• Dp
• Boolean

You can view constant literals that trigger real time updates without the compilation step by enabling literal decorations through the Live Edit of literals UI indicator:

اعمال تغییرات

Apply Changes lets you update code and resources without having to redeploy your app to an emulator or physical device (with some limitations ).

Whenever you add, modify, or delete composables, you can update your app without having to redeploy it by clicking on the Apply Code Changes button: