بسته ها و بسته ها
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
اشیاء Parcelable و Bundle برای استفاده در سراسر مرزهای فرآیند مانند تراکنش‌های IPC/Binder، بین فعالیت‌های دارای هدف، و ذخیره حالت گذرا در میان تغییرات پیکربندی در نظر گرفته شده‌اند. این صفحه توصیه ها و بهترین روش ها را برای استفاده از اشیاء Parcelable و Bundle ارائه می دهد.
توجه: Parcel یک مکانیسم سریال سازی همه منظوره نیست و شما هرگز نباید هیچ گونه داده Parcel را روی دیسک ذخیره کنید یا آن را از طریق شبکه ارسال کنید.
ارسال داده بین فعالیت ها
هنگامی که یک برنامه یک شی Intent ایجاد می کند تا در startActivity(android.content.Intent) برای شروع یک فعالیت جدید استفاده کند، برنامه می تواند با استفاده از روش putExtra(java.lang.String, java.lang.String) پارامترها را ارسال کند.
قطعه کد زیر نمونه ای از نحوه انجام این عملیات را نشان می دهد.
کاتلین
val intent = Intent(this, MyActivity::class.java).apply {
putExtra("media_id", "a1b2c3")
// ...
}
startActivity(intent) جاوا
Intent intent = new Intent(this, MyActivity.class);
intent.putExtra("media_id", "a1b2c3");
// ...
startActivity(intent); سیستم‌عامل بسته‌بندی Bundle هدف را بسته‌بندی می‌کند. سپس، سیستم‌عامل فعالیت جدید را ایجاد می‌کند، داده‌ها را بسته‌بندی می‌کند و هدف را به فعالیت جدید منتقل می‌کند.
توصیه می کنیم از کلاس Bundle برای تنظیم اولیه های شناخته شده برای سیستم عامل روی اشیاء Intent استفاده کنید. کلاس Bundle برای marshalling و unmarshalling با استفاده از بسته ها بسیار بهینه شده است.
در برخی موارد، ممکن است به مکانیزمی برای ارسال اشیاء مرکب یا پیچیده در میان فعالیت ها نیاز داشته باشید. در چنین مواردی، کلاس سفارشی باید Parcelable را پیاده سازی کند و متد مناسب writeToParcel(android.os.Parcel, int) را ارائه دهد. همچنین باید یک فیلد غیر تهی به نام CREATOR ارائه کند که رابط Parcelable.Creator پیاده سازی کند، که متد createFromParcel() آن برای تبدیل Parcel به شی فعلی استفاده می شود. برای اطلاعات بیشتر، به مستندات مرجع شیء Parcelable مراجعه کنید.
هنگام ارسال داده از طریق intent، باید مراقب باشید که اندازه داده را به چند کیلوبایت محدود کنید. ارسال بیش از حد داده می تواند باعث شود سیستم یک استثنا TransactionTooLargeException ایجاد کند.
ارسال داده بین فرآیندها
ارسال داده بین فرآیندها مشابه انجام این کار بین فعالیت ها است. با این حال، هنگام ارسال بین فرآیندها، توصیه می کنیم از بسته بندی های سفارشی استفاده نکنید. اگر یک شیء سفارشی Parcelable را از یک برنامه به برنامه دیگر ارسال می کنید، باید مطمئن شوید که دقیقاً همان نسخه کلاس سفارشی در هر دو برنامه ارسال و دریافت وجود دارد. معمولاً این می تواند یک کتابخانه مشترک باشد که در هر دو برنامه استفاده می شود. اگر برنامه شما بخواهد یک بسته بندی سفارشی را به سیستم ارسال کند، ممکن است خطایی رخ دهد، زیرا سیستم نمی تواند کلاسی را که هیچ اطلاعی از آن ندارد، باز کند.
به عنوان مثال، یک برنامه ممکن است با استفاده از کلاس AlarmManager زنگ هشدار تنظیم کند و از یک Parcelable سفارشی در هدف آلارم استفاده کند. وقتی زنگ هشدار به صدا در می‌آید، سیستم Bundle of Extra intent را تغییر می‌دهد تا تعداد تکرار اضافه شود. این اصلاح می‌تواند منجر به حذف سیستم سفارشی Parcelable از موارد اضافی شود. این حذف، به نوبه خود، می تواند منجر به از کار افتادن برنامه در هنگام دریافت هدف هشدار اصلاح شده شود، زیرا برنامه انتظار دارد داده های اضافی را دریافت کند که دیگر وجود ندارد.
بافر تراکنش Binder دارای یک اندازه ثابت محدود است، در حال حاضر 1 مگابایت، که توسط تمام تراکنش‌های در حال انجام فرآیند به اشتراک گذاشته می‌شود. از آنجایی که این محدودیت در سطح فرآیند است نه در سطح هر فعالیت، این تراکنش ها شامل تمام تراکنش های بایندر در برنامه مانند onSaveInstanceState، startActivity و هر گونه تعامل با سیستم می شود. وقتی از محدودیت اندازه فراتر رفت، یک TransactionTooLargeException پرتاب می شود.
برای مورد خاص savedInstanceState، مقدار داده باید کم نگه داشته شود زیرا فرآیند سیستم باید تا زمانی که کاربر بتواند به آن فعالیت بازگردد (حتی اگر فرآیند فعالیت از بین برود) روی داده های ارائه شده باقی بماند. توصیه می کنیم وضعیت ذخیره شده را در کمتر از 50 هزار داده نگه دارید.
توجه: در اندروید 7.0 (سطح API 24) و بالاتر، سیستم یک TransactionTooLargeException را به عنوان یک استثنا در زمان اجرا می‌اندازد. در نسخه‌های پایین‌تر اندروید، سیستم فقط یک هشدار را در logcat نشان می‌دهد.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Parcelables and bundles\n\n[Parcelable](/reference/android/os/Parcelable) and [Bundle](/reference/android/os/Bundle) objects are intended to be\nused across process boundaries such as with IPC/Binder\ntransactions, between activities with intents, and to store transient state across configuration\nchanges. This page provides recommendations and best practices for using\n[Parcelable](/reference/android/os/Parcelable) and [Bundle](/reference/android/os/Bundle) objects.\n\n**Note:** [Parcel](/reference/android/os/Parcel) is not a general-purpose\nserialization mechanism, and you should never\nstore any [Parcel](/reference/android/os/Parcel) data on disk or send it over the network.\n\nSending data between activities\n-------------------------------\n\n\nWhen an app creates an [Intent](/reference/android/content/Intent) object to use in\n[startActivity(android.content.Intent)](/reference/android/app/Activity#startActivity(android.content.Intent)) in starting a new Activity,\nthe app can pass in\nparameters using the [putExtra(java.lang.String, java.lang.String)](/reference/android/content/Intent#putExtra(java.lang.String, java.lang.String))\nmethod.\n\nThe following code snippet shows an example of how to perform this operation. \n\n### Kotlin\n\n```kotlin\nval intent = Intent(this, MyActivity::class.java).apply {\n putExtra(\"media_id\", \"a1b2c3\")\n // ...\n}\nstartActivity(intent)\n```\n\n### Java\n\n```java\nIntent intent = new Intent(this, MyActivity.class);\nintent.putExtra(\"media_id\", \"a1b2c3\");\n// ...\nstartActivity(intent);\n```\n\n\nThe OS parcels the underlying [Bundle](/reference/android/os/Bundle) of the intent. Then, the OS creates\nthe new activity,\nun-parcels the data, and passes the intent to the new activity.\n\n\nWe recommend that you use the [Bundle](/reference/android/os/Bundle) class to set primitives known to the OS on\n[Intent](/reference/android/content/Intent) objects. The [Bundle](/reference/android/os/Bundle) class is highly\noptimized for marshalling and unmarshalling using parcels.\n\n\nIn some cases, you may need a mechanism to send composite or complex objects across activities.\nIn such cases, the custom class should implement Parcelable, and provide the appropriate\n[writeToParcel(android.os.Parcel, int)](/reference/android/os/Parcelable#writeToParcel(android.os.Parcel, int)) method.\nIt must also provide a non-null field called `CREATOR` that\nimplements the [Parcelable.Creator](/reference/android/os/Parcelable.Creator) interface, whose\n[createFromParcel()](/reference/android/os/Parcelable.Creator#createFromParcel(android.os.Parcel))\nmethod is used for converting the [Parcel](/reference/android/os/Parcel) back to the current object.\nFor more information,\nsee the reference documentation for the [Parcelable](/reference/android/os/Parcelable) object.\n\n\nWhen sending data via an intent, you should be careful to limit the data size to a few KB.\nSending too much data can cause the system to throw a\n[TransactionTooLargeException](/reference/android/os/TransactionTooLargeException) exception.\n\nSending data between processes\n------------------------------\n\n\nSending data between processes is similar to doing so between activities. However, when sending\nbetween processes, we recommend that you do not use custom parcelables. If you send a custom\n[Parcelable](/reference/android/os/Parcelable) object from one app to another, you need to be certain that the\nexact same version of the custom class is\npresent on both the sending and receiving apps. Typically this could be a common library\nused across both apps. An error can occur if your app tries to send a custom parcelable to\nthe system, because the system cannot unmarshal a class that it has no knowledge of.\n\n\nFor example, an app might set an alarm using\nthe [AlarmManager](/reference/android/app/AlarmManager) class, and use a custom [Parcelable](/reference/android/os/Parcelable)\non the alarm intent. When the alarm goes off, the system modifies the intent's\n[Bundle](/reference/android/os/Bundle) of extras to add\na repeat count. This modification can result in the system's stripping the custom\n[Parcelable](/reference/android/os/Parcelable) from the extras. This stripping, in turn, can result in the app's\ncrashing when it receives the modified alarm intent, because the app expects to\nreceive extra data that is no longer there.\n\n\nThe Binder transaction buffer has a limited fixed size, currently 1MB, which is shared by all\ntransactions in progress for the process. Since this limit is at the process\nlevel rather than at the per activity level, these transactions include all binder transactions in\nthe app such as onSaveInstanceState, startActivity and any interaction with the system. When the size\nlimit is exceeded, a TransactionTooLargeException is thrown.\n\n\nFor the specific case of savedInstanceState, the amount of data should be kept small\nbecause the system process needs to hold on to the provided data for as long as the user\ncan ever navigate back to that activity (even if the activity's process is killed).\nWe recommend that you keep saved state to less than 50k of data.\n\n\n**Note:** In Android 7.0 (API level 24) and higher, the system throws a\nTransactionTooLargeException as a runtime exception.\nIn lower versions of Android, the system only shows a warning in logcat."]]
