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

ویجت‌های برنامه، نماهای مینیاتوری برنامه هستند که می‌توانید در برنامه‌های دیگر - مانند صفحه اصلی - جاسازی کنید و به‌روزرسانی‌های دوره‌ای را دریافت کنید. این نماها به عنوان ابزارک در رابط کاربری نامیده می‌شوند و می‌توانید یکی از آنها را با ارائه‌دهنده ابزارک برنامه (یا ارائه‌دهنده ویجت ) منتشر کنید. جزء برنامه ای که ویجت های دیگر را نگه می دارد، میزبان ویجت برنامه (یا میزبان ویجت ) نامیده می شود. شکل 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" />