مفاهیم و معماری Remote Compose

‫Remote Compose یک کتابخانه Jetpack است که به شما امکان می‌دهد بااستفاده از میاناهای برنامه‌سازی کاربردی سبک Compose در برنامه‌تان، واسط کاربر بسازید و آن را در فرایندهای سیستم، مانند «ابزاره‌های برنامه» یا «ابزاره‌های Wear OS»، نمایش دهید. برنامه شما میانای کاربر را به‌عنوان یک سند فشرده ضبط می‌کند و یک پخش‌کننده در فرایند میزبان آن را ارائه می‌دهد و تعاملات، تغییرات حالت، و پویانمایی‌ها را به‌صورت محلی و بدون فراخوانی مجدد در برنامه شما مدیریت می‌کند.

این راهنما معماری Remote Compose و تفاوت آن با Jetpack Compose استاندارد را توضیح می‌دهد. این راهنما بر ساختن میانای کاربر با مؤلفه‌ها تمرکز دارد.

موارد استفاده Compose ازراه‌دور

از «ترکیب‌بندی از راه دور» می‌توان در هر سطحی با پخش‌کننده پشتیبانی‌کننده استفاده کرد. در Android، ابزاره‌های «برنامه» و ابزاره‌های Wear OS را تقویت می‌کند.

نحوه عملکرد: معماری سه‌بلوکی

تفاوت معماری بنیادی بین Remote Compose و Jetpack Compose استاندارد در جداسازی تعریف میانای کاربر از اجرا در سه بلوک سطح بالا نهفته است:

• ایجاد سند: برنامه شما توابع @RemoteComposable شما را برای ثبت سند اجرا می‌کند: شرحی فشرده و سریالی از واسط کاربر، ازجمله چیدمان، وضعیت از راه دور، و کنش‌های آن. وقتی داده‌هایتان تغییر می‌کند، برنامه‌تان می‌تواند سند جدیدی را ضبط و ارسال کند.
• انتقال سند به میزبان راه دور: برنامه شما سند را به میزبان (فرایندی که آن را نمایش می‌دهد، مثل راه‌انداز یا Wear OS) منتقل می‌کند.
• پخش سند: یک پخش‌کننده Remote Compose در میزبان سند را ارائه می‌کند و چیدمان، ورودی، تغییرات وضعیت UX، و پویانمایی‌ها را به‌صورت محلی مدیریت می‌کند، بدون اینکه به برنامه شما بازگردد.

این معماری مزایای اصلی‌ای ارائه می‌دهد که مستقیماً تأخیر را کاهش می‌دهد:

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

قیاس صفحه وب / HTML: عملکرد Remote Compose مشابه ارائه صفحه وب است. سرور برنامه یک‌بار ساختار HTML/سند را تولید و ارسال می‌کند و میزبان مرورگر آن را ارائه می‌کند و تعاملات را به‌صورت محلی بدون پرس‌وجوی مداوم از باطن مدیریت می‌کند.

اجزا

‫Remote Compose مؤلفه‌های میانای کاربری سطح بالایی برای ساختاردهی به چیدمان‌ها ارائه می‌دهد. به‌جای معادل‌های استاندارد Compose، از مؤلفه‌های Remote Compose و RemoteModifier استفاده کنید. این موارد شامل محفظه‌های چیدمان پایه و همچنین مؤلفه‌های تطبیقی است که به‌طور خاص برای مدیریت اندازه‌های پویای صفحه‌نمایش طراحی شده‌اند:

• مؤلفه‌های چیدمان پایه: عناصر چیدمان رایج شبیه Compose مانند RemoteBox، RemoteRow، و RemoteColumn.
• مؤلفه‌های چیدمان تطبیقی: مؤلفه‌های تخصصی مانند RemoteFitBox، RemoteCollapsibleRow، و RemoteCollapsibleColumn که برای تطبیق تمیز در سطوح ازراه‌دور طراحی شده‌اند.
• موضوع‌دهی طراحی Material: موضوع‌دهی برای ابزاره‌های Wear OS به همان روش کار می‌کند، با سلسله‌مراتبی از رنگ و طرح حروف که توسط RemoteMaterialTheme ارائه شده است. این کار باعث می‌شود نمانام‌سازی و طراحی سیستم به‌طور یکپارچه در سراسر برنامه و ابزارک‌هایتان پیاده‌سازی شود.

طراحی سفارشی با RemoteCanvas

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

تفاوت‌های اساسی

مفاهیم اصلی زیر را مرور کنید تا متوجه شوید Remote Compose چگونه حالت، منطق، و کنش‌ها را مدیریت می‌کند.

ارجاع‌های وضعیت نمادین

در Compose استاندارد، محفظه‌های حالت مقادیر فعال و قابل‌خواندن را در حافظه برنامه محلی نگه می‌دارند که توسط کد برنامه (لامبدا) هنگام وقوع رویدادها تغییر می‌کنند. در Remote Compose، اعلامیه‌های وضعیت به‌عنوان ارجاع‌های نمادین عمل می‌کنند. به‌جای نگهداری مقادیر فعال در حافظه برنامه محلی، آن‌ها پیوندهایی را اعلام می‌کنند که پخش‌کننده از راه دور آن‌ها را مدیریت می‌کند و به‌طور محلی در زمان اجرا به‌روز می‌کند. هنگام اعلام وضعیت در Remote Compose، ملاحظات زیر را درنظر داشته باشید:

• از توابع کارخانه‌ای Remote Compose برای اعلام وضعیت‌هایی مثل rememberMutableRemoteInt، rememberMutableRemoteFloat، یا rememberMutableRemoteString استفاده کنید.
• کد برنامه شما نمی‌تواند مقدار متغیر حالت ازراه‌دور را مستقیماً درطول ترکیب‌بندی بازرسی یا خوانش کند.
• پخش‌کننده این مقادیر را به‌صورت محلی ذخیره و به‌روزرسانی می‌کند، زیرا کاربر با سند تعامل دارد.

وضعیت ازراه‌دور درمقابل جریان کنترل Kotlin

کد Kotlin شما فقط زمانی اجرا می‌شود که برنامه‌تان سند را ایجاد کند. عبارت‌های Kotlin مانند if،‏ when، و for می‌توانند سند را براساس مقادیر شناخته‌شده در آن زمان شکل دهند، مثلاً تکرار کردن یک ردیف برای هر مورد در فهرست، اما نمی‌توانند به وضعیت ازراه‌دوری که بعداً تغییر می‌کند واکنش نشان دهند. هنگام کار در «ترکیب‌بندی ازراه‌دور»، موارد زیر را به‌خاطر داشته باشید:

• منطق انشعاب: تعویض پویای میانای کاربر بااستفاده از RemoteStateLayout با نگاشت وضعیت به RemoteComposable جایگاه‌های مختلف انجام می‌شود.
• ارزیابی نوشتار: از درون‌یابی رشته Kotlin استاندارد («$remoteValue») که فقط هنگام ایجاد سند ارزیابی می‌شود اجتناب کنید. درعوض، RemoteString را به RemoteText ارسال کنید.

سبک‌بندی پویا بااستفاده از RemoteModifier

Dynamic styling on the host does not rerun composition; instead, remote state variables are passed directly into modifiers, such as RemoteModifier.background(remoteColor).

بافت سیستم ازراه‌دور

CompositionLocal ارائه‌دهندگانی مانند LocalConfiguration یا LocalDensity فقط محیط برنامه محلی را در لحظه ثبت سند منعکس می‌کنند. این تصاویر به‌صورت پویا در میزبان راه‌دور به‌روز نمی‌شوند، حتی اگر اندازه سطح تغییر کند، وضعیت نمایش تغییر کند، یا زمان پیش برود. درعوض، از مقادیری استفاده کنید که پخش‌کننده در زمان اجرا در میزبان حل می‌کند، مانند اندازه فعلی مؤلفه، RemoteConfiguration یا RemoteDensity.

کنش‌های اظهاری

در Compose استاندارد، گرداننده‌های کلیک عبارت‌های لامبدایی هستند که در برنامه شما اجرا می‌شوند. میزبان نمی‌تواند کد برنامه شما را اجرا کند، بنابراین در Remote Compose به‌جای آن کنش‌ها را پیوست می‌کنید، برای مثال با RemoteModifier.clickable(action). کنش می‌تواند وضعیت راه دور را مستقیماً در میزبان با valueChange به‌روز کند، یا با pendingIntentAction یا hostAction به برنامه یا میزبان شما واگذار کند. برای اجرای چند کنش با یک کلیک، از combinedAction استفاده کنید.

مقایسه الگوهای سطح بالا

دامنه ویژگی	Jetpack Compose استاندارد	Remote Compose
رویدادهای کلیک و لمس	لامبداهای همگام درحال پردازش	اشیاء «کنش» سریالی‌شده اعلانی
منطق شرطی	جریان کنترل if و when در Kotlin	Kotlin if/when استاندارد برای حالت ثابتی که هنگام تولید سند شناخته می‌شود به‌طور عادی کار می‌کند. انشعاب پویا از RemoteStateLayout (برای درخت‌های واسط کاربر) استفاده می‌کند.
حلقه‌های جریان کنترل	حلقه‌های استاندارد for و while در Kotlin	حلقه‌های استاندارد Kotlin (تکرار، برای، برای هرکدام) فقط زمانی اجرا می‌شوند که سند ایجاد شده باشد. آن‌ها نمی‌توانند وضعیت ازراه‌دور را در میزبان تکرار کنند
میزبان اجرا	فرایند برنامه	راه‌انداز (AppWidget)، ابزاره‌های Wear OS، یا هر ضریب شکل دیگری با پخش‌کننده پشتیبانی‌کننده
چرخه حیات پردازش	برای بازترکیب و رندر کردن، فرایند باید فعال بماند	سند عکس آنی واسط کاربر سوابق پردازش؛ موتور «پخش‌کننده ازراه‌دور» درخت مؤلفه را تجزیه می‌کند، تغییرات وضعیت را ردیابی می‌کند، و بدون فراخوانی مجدد در برنامه، به‌صورت محلی بازترسیم می‌کند.
عوارض جانبی	چرخه‌های حیات Coroutine‏ (LaunchedEffect)	در میزبان دردسترس نیست. «ترکیب‌بندی» در برنامه شما اجرا می‌شود تا سند را ایجاد کند، بنابراین جلوه‌های هم‌روال نمی‌توانند واسط کاربر ازراه‌دور را هدایت کنند، مگراینکه ادغام ترکیب‌بندی را باز نگه دارد.
الگوی وضعیت	مقادیر وضعیت حافظه محلی	توابع کارخانه‌ای (rememberMutableRemoteInt()، rememberNamedRemoteColor()) که به‌جای مقادیر خام، ارجاع‌های حالت نمادین را برمی‌گردانند.