یک ویجت ساده ایجاد کنید

ویجت‌های برنامه، نماهای مینیاتوری برنامه هستند که می‌توانید در برنامه‌های دیگر - مانند صفحه اصلی - جاسازی کنید و به‌روزرسانی‌های دوره‌ای را دریافت کنید. این نماها به عنوان ابزارک در رابط کاربری نامیده می‌شوند و می‌توانید یکی از آنها را با ارائه‌دهنده ابزارک برنامه (یا ارائه‌دهنده ویجت ) منتشر کنید. جزء برنامه ای که ویجت های دیگر را نگه می دارد، میزبان ویجت برنامه (یا میزبان ویجت ) نامیده می شود. شکل 1 نمونه ویجت موسیقی را نشان می دهد:

این سند نحوه انتشار یک ویجت با استفاده از ارائه دهنده ویجت را توضیح می دهد. برای جزئیات در مورد ایجاد AppWidgetHost خود برای میزبانی ابزارک های برنامه، به ساخت میزبان ویجت مراجعه کنید.

برای کسب اطلاعات در مورد نحوه طراحی ویجت خود، به نمای کلی ابزارک های برنامه مراجعه کنید.

اجزای ویجت

برای ایجاد یک ویجت، به اجزای اصلی زیر نیاز دارید:

شی AppWidgetProviderInfo

فراداده یک ویجت را توصیف می کند، مانند طرح بندی ویجت، فرکانس به روز رسانی، و کلاس AppWidgetProvider . AppWidgetProviderInfo در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.

کلاس AppWidgetProvider

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

نمایش طرح

طرح اولیه ویجت را تعریف می کند. طرح در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.

شکل 2 نشان می دهد که چگونه این مؤلفه ها در جریان کلی پردازش ویجت برنامه قرار می گیرند.

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

• با شروع Android 12 (سطح API 31)، می‌توانید یک پیکربندی پیش‌فرض ارائه دهید و به کاربران اجازه دهید بعداً ویجت را دوباره پیکربندی کنند. برای جزئیات بیشتر به استفاده از پیکربندی پیش فرض ویجت و فعال کردن کاربران برای پیکربندی مجدد ویجت های قرار داده شده مراجعه کنید.
• در اندروید 11 (سطح API 30) یا پایین تر، هر بار که کاربر ویجت را به صفحه اصلی خود اضافه می کند، این فعالیت راه اندازی می شود.

ما همچنین پیشرفت‌های زیر را توصیه می‌کنیم: طرح‌بندی ویجت‌های انعطاف‌پذیر ، پیشرفت‌های متفرقه ، ویجت‌های پیشرفته ، ویجت‌های مجموعه ، و ساخت میزبان ویجت .

AppWidgetProviderInfo XML را اعلام کنید

شی AppWidgetProviderInfo کیفیت های اساسی یک ویجت را تعریف می کند. شی AppWidgetProviderInfo را در یک فایل منبع XML با استفاده از یک عنصر <appwidget-provider> تعریف کنید و آن را در پوشه res/xml/ پروژه ذخیره کنید.

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

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

ویژگی های اندازه ویجت

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

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

جدول زیر ویژگی های <appwidget-provider> مربوط به اندازه ویجت را شرح می دهد:

مثال

برای نشان دادن اینکه چگونه ویژگی های جدول قبل بر اندازه ویجت تأثیر می گذارد، مشخصات زیر را در نظر بگیرید:

• یک سلول شبکه ای 30 dp عرض و 50 dp ارتفاع دارد.
• مشخصات ویژگی زیر ارائه شده است:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

شروع با اندروید 12:

از ویژگی های targetCellWidth و targetCellHeight به عنوان اندازه پیش فرض ویجت استفاده کنید.

اندازه ویجت به طور پیش فرض 2x2 است. اندازه ویجت را می توان به 2x1 یا تا 4x3 تغییر داد.

اندروید 11 و پایین تر:

از ویژگی های minWidth و minHeight برای محاسبه اندازه پیش فرض ویجت استفاده کنید.

عرض پیش فرض = Math.ceil(80 / 30) = 3

ارتفاع پیش فرض = Math.ceil(80 / 50) = 2

اندازه ویجت به طور پیش فرض 3x2 است. اندازه ویجت را می توان به 2x1 یا تا تمام صفحه تغییر داد.

ویژگی های ویجت اضافی

جدول زیر ویژگی های <appwidget-provider> مربوط به کیفیت هایی غیر از اندازه ویجت را توضیح می دهد.

از کلاس AppWidgetProvider برای مدیریت پخش ویجت استفاده کنید

کلاس AppWidgetProvider پخش ویجت را مدیریت می کند و ویجت را در پاسخ به رویدادهای چرخه حیات ویجت به روز می کند. بخش های زیر نحوه اعلان AppWidgetProvider در مانیفست و سپس پیاده سازی آن را توضیح می دهد.

یک ویجت را در مانیفست اعلام کنید

ابتدا طبق مثال زیر، کلاس AppWidgetProvider در فایل AndroidManifest.xml برنامه خود اعلام کنید:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

عنصر <receiver> به ویژگی android:name نیاز دارد که AppWidgetProvider مورد استفاده ویجت را مشخص می کند. مؤلفه نباید صادر شود مگر اینکه یک فرآیند جداگانه به AppWidgetProvider شما ارسال شود، که معمولاً اینطور نیست.

عنصر <intent-filter> باید دارای عنصر <action> با ویژگی android:name باشد. این ویژگی مشخص می کند که AppWidgetProvider پخش ACTION_APPWIDGET_UPDATE را می پذیرد. این تنها پخشی است که باید به صراحت اعلام کنید. AppWidgetManager به طور خودکار سایر پخش‌های ویجت را در صورت لزوم به AppWidgetProvider ارسال می‌کند.

عنصر <meta-data> منبع AppWidgetProviderInfo را مشخص می کند و به ویژگی های زیر نیاز دارد:

• android:name : نام ابرداده را مشخص می کند. از android.appwidget.provider برای شناسایی داده ها به عنوان توصیفگر AppWidgetProviderInfo استفاده کنید.
• android:resource : محل منبع AppWidgetProviderInfo را مشخص می کند.

کلاس AppWidgetProvider را پیاده سازی کنید

کلاس AppWidgetProvider BroadcastReceiver به عنوان یک کلاس راحت برای مدیریت پخش ویجت گسترش می دهد. فقط پخش رویدادهایی را دریافت می کند که مربوط به ویجت هستند، مانند زمانی که ویجت به روز می شود، حذف می شود، فعال و غیرفعال می شود. هنگامی که این رویدادهای پخش رخ می دهند، متدهای AppWidgetProvider زیر فراخوانی می شوند:

onUpdate()

این برای به روز رسانی ویجت در فواصل زمانی مشخص شده توسط ویژگی updatePeriodMillis در AppWidgetProviderInfo نامیده می شود. برای اطلاعات بیشتر به جدولی که ویژگی‌های ویجت اضافی را در این صفحه توضیح می‌دهد، مراجعه کنید.

این روش زمانی که کاربر ویجت را اضافه می‌کند نیز نامیده می‌شود، بنابراین تنظیمات ضروری مانند تعریف کنترل‌کننده‌های رویداد برای View اشیاء یا شروع کارها برای بارگیری داده‌ها برای نمایش در ویجت را انجام می‌دهد. با این حال، اگر یک فعالیت پیکربندی را بدون پرچم configuration_optional اعلام کنید، این روش زمانی که کاربر ویجت را اضافه می کند فراخوانی نمی شود، اما برای به روز رسانی های بعدی فراخوانی می شود . این مسئولیت فعالیت پیکربندی است که پس از تکمیل پیکربندی، اولین به روز رسانی را انجام دهد. برای اطلاعات بیشتر به فعال کردن کاربران برای پیکربندی ابزارک‌های برنامه رجوع کنید.

مهم ترین callback onUpdate() است. برای اطلاعات بیشتر به Handle events با کلاس onUpdate() در این صفحه مراجعه کنید.

onAppWidgetOptionsChanged()

هنگامی که ویجت برای اولین بار قرار می گیرد و هر زمانی که اندازه ویجت تغییر می کند، این نام خوانده می شود. از این تماس برای نمایش یا پنهان کردن محتوا بر اساس محدوده اندازه ویجت استفاده کنید. با فراخوانی getAppWidgetOptions() که Bundle شامل موارد زیر را برمی‌گرداند، محدوده‌های اندازه را دریافت کنید - و با شروع Android 12، فهرستی از اندازه‌های احتمالی که یک نمونه ویجت می‌تواند بگیرد.

• OPTION_APPWIDGET_MIN_WIDTH : شامل کران پایینی در عرض، به واحدهای dp، نمونه ویجت است.
• OPTION_APPWIDGET_MIN_HEIGHT : شامل کران پایینی در ارتفاع، به واحدهای dp، نمونه ویجت است.
• OPTION_APPWIDGET_MAX_WIDTH : شامل کران بالایی در عرض، به واحدهای dp، نمونه ویجت است.
• OPTION_APPWIDGET_MAX_HEIGHT : شامل کران بالای ارتفاع، به واحدهای dp، نمونه ویجت است.
• OPTION_APPWIDGET_SIZES : حاوی لیستی از اندازه های ممکن ( List<SizeF> ) در واحدهای dp است که یک نمونه ویجت می تواند بگیرد. در اندروید 12 معرفی شد.

onDeleted(Context, int[])

هر بار که یک ویجت از میزبان ویجت حذف می شود، این نام خوانده می شود.

onEnabled(Context)

هنگامی که یک نمونه از ویجت برای اولین بار ایجاد می شود، این نام خوانده می شود. به عنوان مثال، اگر کاربر دو نمونه از ویجت شما را اضافه کند، این تنها بار اول فراخوانی می شود. اگر نیاز به باز کردن یک پایگاه داده جدید یا انجام تنظیمات دیگری دارید که فقط باید یک بار برای همه نمونه های ویجت انجام شود، این مکان مناسبی برای انجام آن است.

onDisabled(Context)

این زمانی فراخوانی می شود که آخرین نمونه ویجت شما از میزبان ویجت حذف شود. اینجا جایی است که هر کاری را که در onEnabled(Context) انجام می شود، مانند حذف یک پایگاه داده موقت، پاک می کنید.

onReceive(Context, Intent)

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

شما باید پیاده سازی کلاس AppWidgetProvider خود را به عنوان یک گیرنده پخش با استفاده از عنصر <receiver> در AndroidManifest اعلام کنید. برای اطلاعات بیشتر به اعلام ویجت در مانیفست در این صفحه مراجعه کنید.

رویدادها را با کلاس onUpdate() مدیریت کنید

مهم ترین فراخوانی AppWidgetProvider ، onUpdate() است، زیرا زمانی که هر ویجت به یک میزبان اضافه می شود، فراخوانی می شود، مگر اینکه از یک فعالیت پیکربندی بدون پرچم configuration_optional استفاده کنید. اگر ویجت شما رویدادهای تعامل کاربر را می‌پذیرد، کنترل‌کننده‌های رویداد را در این پاسخ تماس ثبت کنید. اگر ویجت شما فایل‌ها یا پایگاه داده‌های موقتی ایجاد نمی‌کند، یا کارهای دیگری که نیاز به پاکسازی دارند انجام نمی‌دهد، ممکن است onUpdate() تنها روشی باشد که باید تعریف کنید.

به عنوان مثال، اگر ویجتی با دکمه ای می خواهید که با ضربه زدن یک فعالیت را راه اندازی کند، می توانید از پیاده سازی زیر AppWidgetProvider استفاده کنید:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

این AppWidgetProvider تنها متد onUpdate() را تعریف می‌کند و از آن برای ایجاد یک PendingIntent استفاده می‌کند که یک Activity را راه‌اندازی می‌کند و آن را با استفاده از setOnClickPendingIntent(int, PendingIntent) به دکمه ویجت متصل می‌کند. این شامل یک حلقه است که از طریق هر ورودی در appWidgetIds تکرار می‌شود، که آرایه‌ای از شناسه‌ها است که هر ویجت ایجاد شده توسط این ارائه‌دهنده را شناسایی می‌کند. اگر کاربر بیش از یک نمونه از ویجت را ایجاد کند، همه آنها به طور همزمان به روز می شوند. با این حال، تنها یک برنامه updatePeriodMillis برای همه نمونه‌های ویجت مدیریت می‌شود. به عنوان مثال، اگر زمان‌بندی به‌روزرسانی هر دو ساعت یک بار تعریف شده باشد، و یک نمونه دوم از ویجت یک ساعت پس از اولین مورد اضافه شود، هر دو در دوره تعریف‌شده توسط دوره اول و دوم به‌روزرسانی می‌شوند. نادیده گرفته می شود. هر دوی آنها هر دو ساعت یک بار به روز می شوند، نه هر ساعت.

برای جزئیات بیشتر به کلاس نمونه ExampleAppWidgetProvider.java مراجعه کنید.

اهداف پخش ویجت را دریافت کنید

AppWidgetProvider یک کلاس راحتی است. اگر می‌خواهید پخش‌های ویجت را مستقیماً دریافت کنید، می‌توانید BroadcastReceiver خود را پیاده‌سازی کنید یا پاسخ تماس onReceive(Context,Intent) را لغو کنید. اهدافی که باید به آنها اهمیت دهید موارد زیر است:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

طرح بندی ویجت را ایجاد کنید

شما باید یک طرح اولیه برای ویجت خود در XML تعریف کنید و آن را در دایرکتوری res/layout/ پروژه ذخیره کنید. برای جزئیات به دستورالعمل های طراحی مراجعه کنید.

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

RemoteViews همچنین از ViewStub پشتیبانی می کند، که یک View نامرئی و با اندازه صفر است که می توانید از آن برای افزایش تنبلی منابع طرح در زمان اجرا استفاده کنید.

حمایت از رفتار دولتی

Android 12 با استفاده از مؤلفه‌های موجود زیر، از رفتار حالت‌پذیر پشتیبانی می‌کند:

• CheckBox

• Switch

• RadioButton

ویجت هنوز بدون وضعیت است. برنامه شما باید وضعیت را ذخیره کند و برای رویدادهای تغییر وضعیت ثبت نام کند.

مثال کد زیر نحوه پیاده سازی این کامپوننت ها را نشان می دهد.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

دو طرح‌بندی ارائه دهید: یکی دستگاه‌های دارای Android 12 یا بالاتر در res/layout-v31 و دیگری هدف قرار دادن Android 11 یا پایین‌تر در پوشه res/layout پیش‌فرض.

گوشه های گرد را اجرا کنید

Android 12 پارامترهای سیستم زیر را برای تنظیم شعاع گوشه های گرد ویجت شما معرفی می کند:

• system_app_widget_background_radius : شعاع گوشه پس‌زمینه ویجت، که هرگز بزرگ‌تر از 28 dp نیست.

• system_app_widget_inner_radius : شعاع گوشه هر نمای داخل ویجت. این دقیقاً 8 dp کمتر از شعاع پس‌زمینه است تا در هنگام استفاده از یک لایه‌بندی 8 dp به خوبی تراز شود.

مثال زیر ویجتی را نشان می دهد که از system_app_widget_background_radius برای گوشه ویجت و system_app_widget_inner_radius برای نماهای داخل ویجت استفاده می کند.

1 گوشه ویجت.

2 گوشه نما در داخل ویجت.

ملاحظات مهم برای گوشه های گرد

• راه‌اندازهای شخص ثالث و سازندگان دستگاه می‌توانند پارامتر system_app_widget_background_radius را نادیده بگیرند تا کمتر از 28 dp باشد. پارامتر system_app_widget_inner_radius همیشه 8 dp کمتر از مقدار system_app_widget_background_radius است.
• اگر ویجت شما از @android:id/background استفاده نمی‌کند یا پس‌زمینه‌ای را تعریف نمی‌کند که محتوای آن را بر اساس طرح کلی برش می‌دهد - با تنظیم android:clipToOutline روی true - راه‌انداز به‌طور خودکار پس‌زمینه را شناسایی می‌کند و ویجت را با استفاده از یک مستطیل با گوشه‌های گرد برش می‌دهد. تا 16 dp اطمینان حاصل کنید که ویجت شما با Android 12 سازگار است .

برای سازگاری ویجت با نسخه‌های قبلی Android، توصیه می‌کنیم ویژگی‌های سفارشی را تعریف کنید و از یک تم سفارشی برای لغو آنها برای Android 12 استفاده کنید، همانطور که در فایل‌های XML نمونه زیر نشان داده شده است:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />

ویجت‌های برنامه، نماهای مینیاتوری برنامه هستند که می‌توانید در برنامه‌های دیگر - مانند صفحه اصلی - جاسازی کنید و به‌روزرسانی‌های دوره‌ای را دریافت کنید. این نماها به عنوان ابزارک در رابط کاربری نامیده می‌شوند و می‌توانید یکی از آنها را با ارائه‌دهنده ابزارک برنامه (یا ارائه‌دهنده ویجت ) منتشر کنید. جزء برنامه ای که ویجت های دیگر را نگه می دارد، میزبان ویجت برنامه (یا میزبان ویجت ) نامیده می شود. شکل 1 نمونه ویجت موسیقی را نشان می دهد:

این سند نحوه انتشار یک ویجت با استفاده از ارائه دهنده ویجت را توضیح می دهد. برای جزئیات در مورد ایجاد AppWidgetHost خود برای میزبانی ابزارک های برنامه، به ساخت میزبان ویجت مراجعه کنید.

برای کسب اطلاعات در مورد نحوه طراحی ویجت خود، به نمای کلی ابزارک های برنامه مراجعه کنید.

اجزای ویجت

برای ایجاد یک ویجت، به اجزای اصلی زیر نیاز دارید:

شی AppWidgetProviderInfo

فراداده یک ویجت را توصیف می کند، مانند طرح بندی ویجت، فرکانس به روز رسانی، و کلاس AppWidgetProvider . AppWidgetProviderInfo در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.

کلاس AppWidgetProvider

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

نمایش طرح

طرح اولیه ویجت را تعریف می کند. طرح در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.

شکل 2 نشان می دهد که چگونه این مؤلفه ها در جریان کلی پردازش ویجت برنامه قرار می گیرند.

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

• با شروع Android 12 (سطح API 31)، می‌توانید یک پیکربندی پیش‌فرض ارائه دهید و به کاربران اجازه دهید بعداً ویجت را دوباره پیکربندی کنند. برای جزئیات بیشتر به استفاده از پیکربندی پیش فرض ویجت و فعال کردن کاربران برای پیکربندی مجدد ویجت های قرار داده شده مراجعه کنید.
• در اندروید 11 (سطح API 30) یا پایین تر، هر بار که کاربر ویجت را به صفحه اصلی خود اضافه می کند، این فعالیت راه اندازی می شود.

ما همچنین پیشرفت‌های زیر را توصیه می‌کنیم: طرح‌بندی ویجت‌های انعطاف‌پذیر ، پیشرفت‌های متفرقه ، ویجت‌های پیشرفته ، ویجت‌های مجموعه ، و ساخت میزبان ویجت .

AppWidgetProviderInfo XML را اعلام کنید

شی AppWidgetProviderInfo کیفیت های اساسی یک ویجت را تعریف می کند. شی AppWidgetProviderInfo را در یک فایل منبع XML با استفاده از یک عنصر <appwidget-provider> تعریف کنید و آن را در پوشه res/xml/ پروژه ذخیره کنید.

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

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

ویژگی های اندازه ویجت

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

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

جدول زیر ویژگی های <appwidget-provider> مربوط به اندازه ویجت را شرح می دهد:

مثال

برای نشان دادن اینکه چگونه ویژگی های جدول قبل بر اندازه ویجت تأثیر می گذارد، مشخصات زیر را در نظر بگیرید:

• یک سلول شبکه ای 30 dp عرض و 50 dp ارتفاع دارد.
• مشخصات ویژگی زیر ارائه شده است:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

شروع با اندروید 12:

از ویژگی های targetCellWidth و targetCellHeight به عنوان اندازه پیش فرض ویجت استفاده کنید.

اندازه ویجت به طور پیش فرض 2x2 است. اندازه ویجت را می توان به 2x1 یا تا 4x3 تغییر داد.

اندروید 11 و پایین تر:

از ویژگی های minWidth و minHeight برای محاسبه اندازه پیش فرض ویجت استفاده کنید.

عرض پیش فرض = Math.ceil(80 / 30) = 3

ارتفاع پیش فرض = Math.ceil(80 / 50) = 2

اندازه ویجت به طور پیش فرض 3x2 است. اندازه ویجت را می توان به 2x1 یا تا تمام صفحه تغییر داد.

ویژگی های ویجت اضافی

جدول زیر ویژگی های <appwidget-provider> مربوط به کیفیت هایی غیر از اندازه ویجت را توضیح می دهد.

از کلاس AppWidgetProvider برای مدیریت پخش ویجت استفاده کنید

کلاس AppWidgetProvider پخش ویجت را مدیریت می کند و ویجت را در پاسخ به رویدادهای چرخه حیات ویجت به روز می کند. بخش های زیر نحوه اعلان AppWidgetProvider در مانیفست و سپس پیاده سازی آن را توضیح می دهد.

یک ویجت را در مانیفست اعلام کنید

ابتدا طبق مثال زیر، کلاس AppWidgetProvider در فایل AndroidManifest.xml برنامه خود اعلام کنید:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

عنصر <receiver> به ویژگی android:name نیاز دارد که AppWidgetProvider مورد استفاده ویجت را مشخص می کند. مؤلفه نباید صادر شود مگر اینکه نیاز باشد یک فرآیند جداگانه به AppWidgetProvider شما پخش شود، که معمولاً اینطور نیست.

عنصر <intent-filter> باید دارای عنصر <action> با ویژگی android:name باشد. این ویژگی مشخص می کند که AppWidgetProvider پخش ACTION_APPWIDGET_UPDATE را می پذیرد. این تنها پخشی است که باید به صراحت اعلام کنید. AppWidgetManager به طور خودکار سایر پخش‌های ویجت را در صورت لزوم به AppWidgetProvider ارسال می‌کند.

عنصر <meta-data> منبع AppWidgetProviderInfo را مشخص می کند و به ویژگی های زیر نیاز دارد:

• android:name : نام ابرداده را مشخص می کند. از android.appwidget.provider برای شناسایی داده ها به عنوان توصیفگر AppWidgetProviderInfo استفاده کنید.
• android:resource : محل منبع AppWidgetProviderInfo را مشخص می کند.

کلاس AppWidgetProvider را پیاده سازی کنید

کلاس AppWidgetProvider BroadcastReceiver به عنوان یک کلاس راحت برای مدیریت پخش ویجت گسترش می دهد. فقط پخش رویدادهایی را دریافت می کند که مربوط به ویجت هستند، مانند زمانی که ویجت به روز می شود، حذف می شود، فعال و غیرفعال می شود. هنگامی که این رویدادهای پخش رخ می دهند، متدهای AppWidgetProvider زیر فراخوانی می شوند:

onUpdate()

این برای به روز رسانی ویجت در فواصل زمانی مشخص شده توسط ویژگی updatePeriodMillis در AppWidgetProviderInfo نامیده می شود. برای اطلاعات بیشتر به جدولی که ویژگی‌های ویجت اضافی را در این صفحه توضیح می‌دهد، مراجعه کنید.

این روش زمانی که کاربر ویجت را اضافه می‌کند نیز نامیده می‌شود، بنابراین تنظیمات ضروری مانند تعریف کنترل‌کننده‌های رویداد برای View اشیاء یا شروع کارها برای بارگیری داده‌ها برای نمایش در ویجت را انجام می‌دهد. با این حال، اگر یک فعالیت پیکربندی را بدون پرچم configuration_optional اعلام کنید، این روش زمانی که کاربر ویجت را اضافه می کند فراخوانی نمی شود، اما برای به روز رسانی های بعدی فراخوانی می شود . این وظیفه فعالیت پیکربندی است که اولین بروزرسانی را هنگام تکمیل پیکربندی انجام دهید. برای اطلاعات بیشتر به کاربران برای پیکربندی ابزارک های برنامه مراجعه کنید.

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

onAppWidgetOptionsChanged()

این زمانی خوانده می شود که ویجت برای اولین بار قرار می گیرد و هر زمان که ویجت تغییر شکل می یابد. از این پاسخ به تماس برای نشان دادن یا پنهان کردن محتوا بر اساس محدوده اندازه ویجت استفاده کنید. محدوده های اندازه را بدست آورید - و با شروع از Android 12 ، لیست اندازه های ممکن است که یک ویجت می تواند با نام getAppWidgetOptions() ، که یک Bundle که شامل موارد زیر است ، برگرداند:

• OPTION_APPWIDGET_MIN_WIDTH : حاوی محدوده پایین در عرض ، در واحدهای DP ، نمونه ویجت است.
• OPTION_APPWIDGET_MIN_HEIGHT : حاوی محدوده پایین در ارتفاع ، در واحدهای DP ، نمونه ویجت است.
• OPTION_APPWIDGET_MAX_WIDTH : حاوی قسمت بالایی بر روی عرض ، در واحدهای DP ، نمونه ویجت است.
• OPTION_APPWIDGET_MAX_HEIGHT : حاوی مرز بالایی در ارتفاع ، در واحدهای DP ، نمونه ویجت است.
• OPTION_APPWIDGET_SIZES : شامل لیست اندازه های ممکن ( List<SizeF> ) ، در واحدهای DP است که یک نمونه ویجت می تواند از آن استفاده کند. معرفی شده در Android 12.

onDeleted(Context, int[])

این هر بار که ویجت از میزبان ویجت حذف می شود ، خوانده می شود.

onEnabled(Context)

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

onDisabled(Context)

این زمانی خوانده می شود که آخرین نمونه ویجت شما از میزبان ویجت حذف شود. این جایی است که شما هر کار انجام شده در onEnabled(Context) ، مانند حذف یک پایگاه داده موقت را تمیز می کنید.

onReceive(Context, Intent)

این برای هر پخش و قبل از هر یک از روشهای قبلی پاسخ به تماس خواسته شده است. شما به طور معمول نیازی به اجرای این روش ندارید ، زیرا اجرای پیش فرض AppWidgetProvider تمام پخش های ویجت را فیلتر می کند و روش های قبلی را در صورت لزوم فراخوانی می کند.

شما باید اجرای کلاس AppWidgetProvider خود را به عنوان یک گیرنده پخش با استفاده از عنصر <receiver> در AndroidManifest اعلام کنید. برای اطلاعات بیشتر به اعلام ویجت در مانیفست در این صفحه مراجعه کنید.

با کلاس onUpdate () رویدادها را انجام دهید

مهمترین پاسخ به تماس AppWidgetProvider onUpdate() است ، زیرا وقتی هر ویجت به یک میزبان اضافه می شود ، نامیده می شود ، مگر اینکه از یک فعالیت پیکربندی بدون پرچم configuration_optional استفاده کنید. اگر ویجت شما هرگونه وقایع تعامل کاربر را می پذیرد ، پسران رویداد را در این پاسخ تماس ثبت کنید. اگر ویجت شما پرونده های موقت یا پایگاه داده ایجاد نمی کند ، یا کارهای دیگری را که نیاز به پاکسازی دارد انجام نمی دهد ، ممکن است onUpdate() تنها روش پاسخ به تماس شما برای تعریف باشد.

به عنوان مثال ، اگر می خواهید ویجت با دکمه ای که هنگام ضربه زدن فعالیت را راه اندازی می کند ، می توانید از اجرای زیر AppWidgetProvider استفاده کنید:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

این AppWidgetProvider فقط روش onUpdate() را تعریف می کند ، با استفاده از آن برای ایجاد یک PendingIntent که یک Activity راه اندازی می کند و آن را با استفاده از setOnClickPendingIntent(int, PendingIntent) به دکمه ویجت وصل می کند. این شامل یک حلقه است که از طریق هر ورودی در appWidgetIds تکرار می شود ، که مجموعه ای از شناسه ها است که هر ویجت ایجاد شده توسط این ارائه دهنده را شناسایی می کند. اگر کاربر بیش از یک نمونه از ویجت ایجاد کند ، همه آنها همزمان به روز می شوند. با این حال ، فقط یک برنامه updatePeriodMillis برای کلیه موارد ویجت مدیریت می شود. به عنوان مثال ، اگر برنامه به روزرسانی هر دو ساعت تعریف شود و نمونه دوم ویجت یک ساعت پس از اولین اضافه شود ، پس هر دو در دوره تعریف شده توسط اول و دوره بروزرسانی دوم به روز می شوند. نادیده گرفته می شود هر دو آنها هر دو ساعت به روز می شوند ، نه هر ساعت.

برای اطلاعات بیشتر به کلاس نمونه ExampleAppWidgetProvider.java مراجعه کنید.

اهداف پخش ویجت را دریافت کنید

AppWidgetProvider یک کلاس راحتی است. اگر می خواهید پخش ویجت را مستقیماً دریافت کنید ، می توانید BroadcastReceiver خود را پیاده سازی کرده یا از پاسخگویی onReceive(Context,Intent) پیروز شوید. اهداف مورد نیاز شما برای مراقبت از موارد زیر است:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

طرح ویجت را ایجاد کنید

شما باید یک طرح اولیه برای ویجت خود در XML تعریف کنید و آن را در res/layout/ Directory پروژه ذخیره کنید. برای جزئیات بیشتر به دستورالعمل های طراحی مراجعه کنید.

اگر با طرح بندی آشنا باشید ، ایجاد طرح ویجت ساده است. با این حال ، توجه داشته باشید که طرح های ویجت مبتنی بر RemoteViews است که از هر نوع طرح یا ویجت مشاهده پشتیبانی نمی کند. شما نمی توانید از نماهای سفارشی یا زیر کلاسهای دیدگاه هایی که توسط RemoteViews پشتیبانی می شوند استفاده کنید.

RemoteViews همچنین از ViewStub پشتیبانی می کند ، که یک View نامرئی و با اندازه صفر است که می توانید در زمان اجرا از منابع چیدمان تنبل استفاده کنید.

حمایت از رفتار حالت

Android 12 با استفاده از مؤلفه های موجود زیر پشتیبانی از رفتار حالت را می افزاید:

• CheckBox

• Switch

• RadioButton

ویجت هنوز بدون تابعیت است. برنامه شما باید دولت را ذخیره کرده و برای رویدادهای تغییر دولت ثبت نام کند.

مثال کد زیر نحوه اجرای این مؤلفه ها را نشان می دهد.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

دو طرح را ارائه دهید: یکی دستگاه های هدفمند که Android 12 یا بالاتر را در res/layout-v31 اجرا می کنند و دیگری هدف قرار دادن Android 11 یا پایین تر در پوشه res/layout پیش فرض.

گوشه های گرد را اجرا کنید

Android 12 پارامترهای سیستم زیر را برای تنظیم شعاع گوشه های گرد ویج خود معرفی می کند:

• system_app_widget_background_radius : شعاع گوشه ای از پس زمینه ویجت ، که هرگز از 28 dp بزرگتر نیست.

• system_app_widget_inner_radius : شعاع گوشه ای از هر نمای داخل ویجت. این دقیقاً 8 DP کمتر از شعاع پس زمینه است ، تا هنگام استفاده از یک بالشتک 8 DP ، به خوبی تراز شود.

مثال زیر ویجت را نشان می دهد که از system_app_widget_background_radius برای گوشه ویجت و system_app_widget_inner_radius برای بازدید در داخل ویجت استفاده می کند.

1 گوشه ویجت.

2 گوشه نمای داخل ویجت.

ملاحظات مهم برای گوشه های گرد

• پرتابگرهای شخص ثالث و تولید کنندگان دستگاه می توانند پارامتر system_app_widget_background_radius را نادیده بگیرند تا از 28 dp کوچکتر باشند. پارامتر system_app_widget_inner_radius همیشه 8 dp کمتر از مقدار system_app_widget_background_radius است.
• اگر ویجت شما از @android:id/background استفاده نمی کند یا پس زمینه ای را تعریف می کند که محتوای آن را بر اساس طرح کلی - با android:clipToOutline true می کند - تنظیم کننده به طور خودکار پس زمینه را شناسایی می کند و ویجت را با استفاده از مستطیل با گوشه های گرد کلی می کند. از حداکثر 16 دپری. اطمینان حاصل کنید که ویجت شما با Android 12 سازگار است .

برای سازگاری ویجت با نسخه های قبلی Android ، توصیه می کنیم ویژگی های سفارشی را تعریف کنید و از یک موضوع سفارشی برای غلبه بر آنها برای Android 12 استفاده کنید ، همانطور که در نمونه های XML نمونه زیر نشان داده شده است:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />