فعالیت در حال انجام

در Wear OS، جفت کردن یک فعالیت در حال انجام با یک اعلان در حال انجام، این اعلان را به سطوح اضافی در رابط کاربری Wear OS اضافه می کند. این به کاربران امکان می‌دهد بیشتر درگیر فعالیت‌های طولانی مدت باشند.

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

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

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

با API فعالیت مداوم، اعلان مداوم یک برنامه می تواند اطلاعات را در چندین سطح جدید و راحت در Wear OS قرار دهد تا کاربر را درگیر نگه دارد.

به عنوان مثال، در این برنامه تمرینی، اطلاعات می توانند روی صفحه ساعت کاربر به عنوان یک نماد در حال ضربه زدن ظاهر شوند:

شکل 1. نشانگر فعالیت.

بخش Recents راه‌انداز جهانی برنامه همچنین هرگونه فعالیت در حال انجام را فهرست می‌کند:

شکل 2. پرتاب کننده جهانی.

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

شکل 3. تایمر: به طور فعال زمان را شمارش معکوس می کند و با توقف یا توقف تایمر به پایان می رسد.

شکل 4. پیمایش چرخش با نوبت: مسیرها را به مقصد اعلام می کند. زمانی که کاربر به مقصد برسد یا ناوبری را متوقف کند پایان می یابد.

شکل 5. رسانه: موسیقی را در طول یک جلسه پخش می کند. بلافاصله پس از توقف کاربر جلسه پایان می یابد.

Wear فعالیت‌های مداوم را به‌طور خودکار برای برنامه‌های رسانه ایجاد می‌کند.

برای مثالی عمیق از ایجاد فعالیت‌های در حال انجام برای انواع دیگر برنامه‌ها، به آزمایشگاه کد فعالیت در حال انجام مراجعه کنید.

راه اندازی

برای شروع استفاده از API فعالیت مداوم در برنامه خود، وابستگی های زیر را به فایل build.gradle برنامه خود اضافه کنید:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.0.0"
  // Includes LocusIdCompat and new Notification categories for Ongoing Activity.
  implementation "androidx.core:core:1.6.0"
}

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

با ایجاد یک اعلان در حال انجام و سپس یک فعالیت در حال انجام شروع کنید.

یک اعلان مداوم ایجاد کنید

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

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

• اعلان‌ها بازگشتی در دستگاه‌هایی هستند که از فعالیت‌های جاری پشتیبانی نمی‌کنند. اعلان تنها سطحی است که برنامه شما در حال اجرا در پس‌زمینه نشان می‌دهد.
• در Android 11 و بالاتر، Wear OS اعلان را در سینی اعلان پنهان می کند که برنامه به عنوان یک فعالیت مداوم در سطوح اضافی قابل مشاهده باشد.
• پیاده سازی فعلی از خود Notification به عنوان مکانیزم ارتباطی استفاده می کند.

با استفاده از Notification.Builder.setOngoing یک اعلان در حال انجام ایجاد کنید.

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

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

var notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
      …
      .setSmallIcon(..)
      .setOngoing(true)

val ongoingActivityStatus = Status.Builder()
    // Sets the text used across various surfaces.
    .addTemplate(mainText)
    .build()

val ongoingActivity =
    OngoingActivity.Builder(
        applicationContext, NOTIFICATION_ID, notificationBuilder
    )
        // Sets the animated icon that will appear on the watch face in
        // active mode.
        // If it isn't set, the watch face will use the static icon in
        // active mode.
        .setAnimatedIcon(R.drawable.ic_walk)
        // Sets the icon that will appear on the watch face in ambient mode.
        // Falls back to Notification's smallIcon if not set.
        // If neither is set, an Exception is thrown.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap/touch event so users can re-enter your app from the
        // other surfaces.
        // Falls back to Notification's contentIntent if not set.
        // If neither is set, an Exception is thrown.
        .setTouchIntent(activityPendingIntent)
        // Here, sets the text used for the Ongoing Activity (more
        // options are available for timers and stopwatches).
        .setStatus(ongoingActivityStatus)
        .build()

ongoingActivity.apply(applicationContext)

notificationManager.notify(NOTIFICATION_ID, builder.build())

NotificationCompat.Builder notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
      …
      .setSmallIcon(..)
      .setOngoing(true);

OngoingActivityStatus ongoingActivityStatus = OngoingActivityStatus.Builder()
    // Sets the text used across various surfaces.
    .addTemplate(mainText)
    .build();

OngoingActivity ongoingActivity =
    OngoingActivity.Builder(
        applicationContext, NOTIFICATION_ID, notificationBuilder
    )
        // Sets the animated icon that will appear on the watch face in
        // active mode.
        // If it isn't set, the watch face will use the static icon in
        // active mode.
        .setAnimatedIcon(R.drawable.ic_walk)
        // Sets the icon that will appear on the watch face in ambient mode.
        // Falls back to Notification's smallIcon if not set.
        // If neither is set, an Exception is thrown.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap/touch event so users can re-enter your app from the
        // other surfaces.
        // Falls back to Notification's contentIntent if not set.
        // If neither is set, an Exception is thrown.
        .setTouchIntent(activityPendingIntent)
        // Here, sets the text used for the Ongoing Activity (more
        // options are available for timers and stopwatches).
        .setStatus(ongoingActivityStatus)
        .build();

ongoingActivity.apply(applicationContext);

notificationManager.notify(NOTIFICATION_ID, builder.build());

مراحل زیر مهمترین بخش مثال قبلی را نشان می دهد:

1. در NotificationCompat.Builder .setOngoing(true) را فراخوانی کنید و هر فیلد اختیاری را تنظیم کنید.

2. یک OngoingActivityStatus - یا گزینه وضعیت دیگری، همانطور که در بخش زیر توضیح داده شده است - برای نمایش متن ایجاد کنید.

3. یک OngoingActivity ایجاد کنید و یک شناسه اعلان تنظیم کنید.

4. در OngoingActivity با متن apply() را فراخوانی کنید.

5. notificationManager.notify() را فراخوانی کنید و همان شناسه اعلان را که در فعالیت در حال انجام تنظیم شده است، ارسال کنید تا آنها را به هم متصل کنید.

وضعیت

شما از Status استفاده می‌کنید تا وضعیت فعلی و زنده OngoingActivity را در سطوح جدید، مانند بخش Recents در راه‌انداز، در معرض دید کاربر قرار دهید. برای استفاده از این ویژگی، از زیر کلاس Status.Builder استفاده کنید.

در بیشتر موارد، فقط باید الگویی اضافه کنید که نمایانگر متنی باشد که می‌خواهید در بخش Recents در راه‌انداز برنامه ظاهر شود.

سپس می‌توانید نحوه نمایش متن با span را با استفاده از متد addTemplate() و تعیین هر بخش پویا از متن به عنوان Status.Part سفارشی کنید.

مثال زیر نشان می دهد که چگونه کلمه "زمان" را به رنگ قرمز نشان دهیم. این مثال از Status.StopwatchPart برای نشان دادن کرونومتر در بخش Recents در راه‌انداز برنامه استفاده می‌کند.

val htmlStatus =
        "<p>The <font color=\"red\">time</font> on your current #type# is #time#.</p>"

val statusTemplate =
        Html.fromHtml(
                htmlStatus,
                Html.FROM_HTML_MODE_COMPACT
        )

// Creates a 5 minute timer.
// Note the use of SystemClock.elapsedRealtime(), not System.currentTimeMillis().
val runStartTime = SystemClock.elapsedRealtime() + TimeUnit.MINUTES.toMillis(5)

val status = new Status.Builder()
   .addTemplate(statusTemplate)
   .addPart("type", Status.TextPart("run"))
   .addPart("time", Status.StopwatchPart(runStartTime)
   .build()

String htmlStatus =
        "<p>The <font color=\"red\">time</font> on your current #type# is #time#.</p>";

Spanned statusTemplate =
        Html.fromHtml(
                htmlStatus,
                Html.FROM_HTML_MODE_COMPACT
        );

// Creates a 5 minute timer.
// Note the use of SystemClock.elapsedRealtime(), not System.currentTimeMillis().
Long runStartTime = SystemClock.elapsedRealtime() + TimeUnit.MINUTES.toMillis(5);

Status status = new Status.Builder()
   .addTemplate(statusTemplate)
   .addPart("type", new Status.TextPart("run"))
   .addPart("time", new Status.StopwatchPart(runStartTime)
   .build();

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

مثال قبلی از HTMLCompat برای تولید CharSequence برای ارسال به الگو استفاده می‌کند، که آسان‌تر از تعریف دستی یک شی Spannable است.

سفارشی سازی های اضافی

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

اطلاع رسانی در حال انجام

• مجموعه دسته بندی اولویت فعالیت در حال انجام را تعیین می کند.
  • CATEGORY_CALL : تماس صوتی یا تصویری ورودی یا درخواست ارتباط همزمان مشابه
  • CATEGORY_NAVIGATION : یک نقشه یا ناوبری گام به گام
  • CATEGORY_TRANSPORT : کنترل انتقال رسانه برای پخش
  • CATEGORY_ALARM : زنگ هشدار یا تایمر
  • CATEGORY_WORKOUT : یک تمرین (دسته جدید)
  • CATEGORY_LOCATION_SHARING : اشتراک‌گذاری موقت موقعیت مکانی (دسته جدید)
  • CATEGORY_STOPWATCH : کرونومتر (دسته جدید)

فعالیت در حال انجام

• نماد متحرک: یک وکتور سیاه و سفید، ترجیحا با پس‌زمینه شفاف. روی صفحه ساعت در حالت فعال نمایش داده می شود. اگر نماد متحرک ارائه نشده باشد، از نماد اعلان پیش فرض استفاده می شود. (آیکون اعلان پیش فرض برای هر برنامه متفاوت است.)

• نماد استاتیک: یک نماد برداری با پس زمینه شفاف. روی صفحه ساعت در حالت محیطی نمایش داده می شود. اگر نماد متحرک تنظیم نشده باشد، نماد ثابت روی صفحه ساعت در حالت فعال استفاده می شود. اگر این مورد ارائه نشده باشد، از نماد اعلان استفاده می شود. اگر هیچ کدام تنظیم نشده باشد، یک استثنا پرتاب می شود. (راه‌انداز برنامه همچنان از نماد برنامه استفاده می‌کند.)

• وضعیت در حال فعالیت: متن ساده یا Chronometer . در بخش Recents راه‌انداز برنامه نمایش داده می‌شود. اگر ارائه نشده باشد، از اعلان "متن زمینه" استفاده می شود.

• Intent را لمس کنید: یک PendingIntent برای بازگشت به برنامه اگر کاربر روی نماد فعالیت در حال انجام ضربه بزند استفاده می‌شود. روی صفحه ساعت یا روی آیتم راه‌انداز نمایش داده می‌شود. می تواند با هدف اصلی استفاده شده برای راه اندازی برنامه متفاوت باشد. اگر ارائه نشده باشد، از هدف محتوای اعلان استفاده می شود. اگر هیچکدام تنظیم نشده باشد، یک استثنا پرتاب می شود.

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

• شناسه فعالیت در حال انجام: شناسه برای رفع ابهام تماس‌ها از fromExistingOngoingActivity() استفاده می‌شود، زمانی که یک برنامه بیش از یک فعالیت در حال انجام دارد.

یک فعالیت در حال انجام را به روز کنید

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

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

برای به روز رسانی فعالیت در حال انجام و اعلان ارسال شده، از شی ای که قبلا ایجاد کرده اید استفاده کنید و update() را فراخوانی کنید، همانطور که در مثال زیر نشان داده شده است:

ongoingActivity.update(context, newStatus)

ongoingActivity.update(context, newStatus);

به عنوان یک راحتی، یک روش ثابت برای ایجاد یک فعالیت مداوم وجود دارد.

OngoingActivity.recoverOngoingActivity(context)
               .update(context, newStatus)

OngoingActivity.recoverOngoingActivity(context)
               .update(context, newStatus);

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

وقتی برنامه به عنوان یک فعالیت در حال اجرا به پایان رسید، فقط باید اعلان در حال انجام را لغو کند.

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

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

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

بهترین شیوه ها

هنگام کار با API فعالیت مداوم موارد زیر را به خاطر بسپارید:

• قبل از تماس با notificationManager.notify(...) با ongoingActivity.apply(context) تماس بگیرید.

• یک نماد ثابت برای فعالیت در حال انجام خود، به طور صریح یا به عنوان یک بازگشت از طریق اعلان تنظیم کنید. اگر این کار را نکنید، یک IllegalArgumentException دریافت می کنید.

• از آیکون های وکتور سیاه و سفید با پس زمینه شفاف استفاده کنید.

• با استفاده از اعلان ، یک هدف لمسی را برای فعالیت در حال انجام خود، به طور صریح یا به عنوان بازگشتی تنظیم کنید. اگر این کار را نکنید، یک IllegalArgumentException دریافت می کنید.

• برای NotificationCompat ، core:1.5.0-alpha05+ استفاده کنید که شامل LocusIdCompat و دسته‌های جدید برای تمرین، کرونومتر و اشتراک‌گذاری مکان است.

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

هنگام پخش رسانه در دستگاه‌های Wear OS، اعلان‌های رسانه را منتشر کنید

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

اگر از Media3 استفاده می کنید، اعلان به صورت خودکار منتشر می شود. اگر اعلان خود را به صورت دستی ایجاد کنید، باید از MediaStyleNotificationHelper.MediaStyle استفاده کند و MediaSession مربوطه باید دارای فعالیت جلسه باشد.