شروع به کار

این صفحه به شما نشان می‌دهد که چگونه محیط خود را راه‌اندازی کنید و Slices را در برنامه خود بسازید.

توجه: Android Studio نسخه ۳.۲ یا جدیدتر حاوی ابزارها و عملکردهای بیشتری است که می‌تواند در توسعه «برش» به شما کمک کند:

• ابزار بازسازی کد AndroidX: اگر در پروژه‌ای کار می‌کنید که از کتابخانه‌های AndroidX استفاده می‌کند، این ابزار لازم است.
• بررسی‌های Slices lint: ضدعملکردهای رایج را هنگام ساختن Slices می‌گیرد
• الگوی SliceProvider: هنگام ساختن SliceProvider، کد تکراری را مدیریت می‌کند

بارگیری و نصب Slice Viewer

جدیدترین نمونه انتشار APK «نمایشگر برش» را بارگیری کنید که می‌توانید از آن برای آزمایش «برش‌ها» بدون پیاده‌سازی SliceView API استفاده کنید.

توجه: «نمایشگر برش» به Android 4.4 (سطح API‏ ۱۹) یا بالاتر نیاز دارد.

اگر ADB به‌درستی در محیط شما راه‌اندازی نشده است، برای اطلاعات بیشتر به راهنمای ADB مراجعه کنید.

با اجرای فرمان زیر در همان دایرکتوری slice-viewer.apk بارگیری‌شده، Slice Viewer را در دستگاهتان نصب کنید:

adb install -r -t slice-viewer.apk

اجرای «نمایشگر برش»

می‌توانید «نمایشگر برش» را از پروژه Android Studio یا از خط فرمان راه‌اندازی کنید:

«نمایشگر برش» را از پروژه «استودیو Android» خود راه‌اندازی کنید

1. در پروژه، اجرا > ویرایش پیکربندی‌ها... را انتخاب کنید
2. در گوشه بالا سمت راست، روی علامت به‌علاوه سبز کلیک کنید

3. برنامه Android را انتخاب کنید

   

4. slice را در فیلد نام وارد کنید

5. در منو کرکره‌ای ماژول، ماژول برنامه‌تان را انتخاب کنید

6. در بخش گزینه‌های راه‌اندازی، نشانی وب را از منو کرکره‌ای راه‌اندازی انتخاب کنید

7. slice-<your slice URI> را در فیلد نشانی وب وارد کنید

   مثال: slice-content://com.example.your.sliceuri

   

8. روی تأیید کلیک کنید

توجه: دفعه بعد که می‌خواهید «نمایشگر برش» را برای مشاهده «برش» خود راه‌اندازی کنید، می‌توانید از پیکربندی‌ای که به‌تازگی ایجاد کرده‌اید استفاده کنید

ابزار Slice Viewer را ازطریق ADB (خط فرمان) راه‌اندازی کنید

برنامه‌تان را از «استودیو Android» اجرا کنید:

adb install -t -r <yourapp>.apk

با اجرای فرمان زیر، Slice خود را مشاهده کنید:

adb shell am start -a android.intent.action.VIEW -d slice-<your slice URI>

«نمایشگر برش» که یک «برش Wi-Fi» را نشان می‌دهد

همه «برش‌ها» را در یک جا ببینید

علاوه‌بر راه‌اندازی یک «برش»، می‌توانید فهرست ثابتی از «برش‌های» خود را مشاهده کنید.

• از نوار جستجو برای جستجوی دستی «برش‌ها» ازطریق URI استفاده کنید (برای مثال، content://com.example.android.app/hello). هربار که جستجو می‌کنید، «برش» به فهرست اضافه می‌شود.
• هر زمان که ابزار Slice Viewer را با Slice URI راه‌اندازی کنید، Slice به فهرست اضافه می‌شود.
• می‌توانید با تند کشیدن روی «برش»، آن را از فهرست بردارید.
• روی URI «برش» ضربه بزنید تا صفحه‌ای را که فقط حاوی آن «برش» است ببینید. این کار همان تأثیر راه‌اندازی «نمایانگر برش» با «شناسه منبع یکسان» (URI) برش را دارد.

توجه: پیمایش «برش» هنگام نمایش در فهرست غیرفعال است. «برش» خود را در «نمایشگر برش» تکی راه‌اندازی کنید تا پیمایش‌پذیری آن را آزمایش کنید.

«نمایشگر برش» که فهرستی از «برش‌ها» را نشان می‌دهد

مشاهده «برش» در حالت‌های مختلف

برنامه‌ای که «برش» را ارائه می‌دهد می‌تواند SliceView#mode را در زمان اجرا تغییر دهد، بنابراین باید مطمئن شوید «برش» شما در هر حالت همان‌طور که انتظار می‌رود نشان داده می‌شود. برای تغییر حالت، نماد منو را در گوشه بالا سمت راست صفحه انتخاب کنید.

نمایشگر «تک‌برش» با حالت تنظیم‌شده روی «کوچک»

اولین «برش» خود را بسازید

برای ساختن «برش»، پروژه «استودیو Android» خود را باز کنید، روی بسته src کلیک راست کنید، و جدید... را انتخاب کنید > Other (سایر) > Slice Provider (ارائه‌دهنده برش). این کار کلاسی ایجاد می‌کند که SliceProvider را گسترش می‌دهد، ورودی ارائه‌دهنده لازم را به AndroidManifest.xml شما اضافه می‌کند، و build.gradle شما را اصلاح می‌کند تا وابستگی‌های لازم «برش» را اضافه کند.

اصلاح AndroidManifest.xml در زیر نشان داده شده است:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.android.app">
    ...
    <application>
        ...
        <provider android:name="MySliceProvider"
            android:authorities="com.example.android.app"
            android:exported="true" >
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.app.slice.category.SLICE" />
            </intent-filter>
        </provider>
        ...
    </application>

</manifest>

توجه: می‌توانید SliceProviders را به‌طور ایمن صادر کنید، زیرا همه بررسی‌های اجازه به‌طور داخلی انجام می‌شود.

وابستگی‌های زیر به build.gradle شما اضافه می‌شود:

کاتلین

dependencies {
// ...
    implementation "androidx.slice:slice-builders-ktx:(latest version)"
// ...
}

جاوا

dependencies {
// ...
    implementation "androidx.slice:slice-builders:(latest version)"
// ...
}

توجه: الگوی SliceProvider به‌طور پیش‌فرض به کتابخانه‌های AndroidX اشاره می‌کند. اگر پروژه‌تان از کتابخانه‌های پشتیبانی قدیمی استفاده می‌کند، حتماً فایل build.gradle را اصلاح کنید تا به‌جای معادل AndroidX، به com.android.support:slices-builders:(latest version) اشاره کند.

توجه: اگر از Kotlin استفاده می‌کنید، توجه داشته باشید که slice-builders-ktx فقط در AndroidX دردسترس است. اگر از کتابخانه پشتیبانی قدیمی استفاده می‌کنید، به‌جای آن از کتابخانه استاندارد com.android.support:slices-builders:(latest version) استفاده کنید.

هر «برش» یک URI منسوب دارد. وقتی سطحی می‌خواهد «برش» را نمایش دهد، درخواست اتصالی با این شناسه منبع یکسان به برنامه شما ارسال می‌کند. سپس برنامه شما این درخواست را مدیریت می‌کند و به‌طور پویا «بخش» را ازطریق روش onBindSlice می‌سازد. سپس سطح می‌تواند «برش» را در زمان مناسب نمایش دهد.

در زیر نمونه‌ای از روش onBindSlice آورده شده است که مسیر URI /hello را بررسی می‌کند و «برش» سلام دنیا را برمی‌گرداند:

کاتلین

override fun onBindSlice(sliceUri: Uri): Slice? {
    val activityAction = createActivityAction()
    return if (sliceUri.path == "/hello") {
        list(context, sliceUri, ListBuilder.INFINITY) {
            row {
                primaryAction = activityAction
                title = "Hello World."
            }
        }
    } else {
        list(context, sliceUri, ListBuilder.INFINITY) {
            row {
                primaryAction = activityAction
                title = "URI not recognized."
            }
        }
    }
}

جاوا

@Override
public Slice onBindSlice(Uri sliceUri) {
    if (getContext() == null) {
        return null;
    }
    SliceAction activityAction = createActivityAction();
    ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY);
    // Create parent ListBuilder.
    if ("/hello".equals(sliceUri.getPath())) {
        listBuilder.addRow(new ListBuilder.RowBuilder()
                .setTitle("Hello World")
                .setPrimaryAction(activityAction)
        );
    } else {
        listBuilder.addRow(new ListBuilder.RowBuilder()
                .setTitle("URI not recognized")
                .setPrimaryAction(activityAction)
        );
    }
    return listBuilder.build();
}

از پیکربندی اجرای برش که در بخش «نمایشگر برش» در بالا ایجاد کردید استفاده کنید و شناسه منبع یکسان «برش» (برای مثال، slice-content://com.android.example.slicesample/hello) مربوط به «برش» سلام دنیا را ارسال کنید تا آن را در «نمایشگر برش» مشاهده کنید.

برش‌های تعاملی

مشابه اعلان‌ها، می‌توانید کلیک‌ها را در «برش» خود با پیوست کردن اشیاء PendingIntent که در تعامل کاربر راه‌اندازی می‌شوند، مدیریت کنید. مثال زیر یک Activity را شروع می‌کند که می‌تواند آن هدف‌ها را دریافت و مدیریت کند:

کاتلین

fun createSlice(sliceUri: Uri): Slice {
    val activityAction = createActivityAction()
    return list(context, sliceUri, INFINITY) {
        row {
            title = "Perform action in app"
            primaryAction = activityAction
        }
    }
}

fun createActivityAction(): SliceAction {
    val intent = Intent(context, MainActivity::class.java)
    return SliceAction.create(
        PendingIntent.getActivity(context, 0, Intent(context, MainActivity::class.java), 0),
        IconCompat.createWithResource(context, R.drawable.ic_home),
        ListBuilder.ICON_IMAGE,
        "Enter app"
    )
}

جاوا

public Slice createSlice(Uri sliceUri) {
    if (getContext() == null) {
        return null;
    }
    SliceAction activityAction = createActivityAction();
    return new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY)
            .addRow(new ListBuilder.RowBuilder()
                    .setTitle("Perform action in app.")
                    .setPrimaryAction(activityAction)
            ).build();
}

public SliceAction createActivityAction() {
    if (getContext() == null) {
        return null;
    }
    return SliceAction.create(
            PendingIntent.getActivity(
                    getContext(),
                    0,
                    new Intent(getContext(), MainActivity.class),
                    0
            ),
            IconCompat.createWithResource(getContext(), R.drawable.ic_home),
            ListBuilder.ICON_IMAGE,
            "Enter app"
    );
}

«برش‌ها» از انواع ورودی‌های دیگر نیز پشتیبانی می‌کنند، مثل کلیدهای روشن/خاموش، که شامل وضعیت در قصدی است که به برنامه ارسال می‌شود.

کاتلین

fun createBrightnessSlice(sliceUri: Uri): Slice {
    val toggleAction =
        SliceAction.createToggle(
            createToggleIntent(),
            "Toggle adaptive brightness",
            true
        )
    return list(context, sliceUri, ListBuilder.INFINITY) {
        row {
            title = "Adaptive brightness"
            subtitle = "Optimizes brightness for available light"
            primaryAction = toggleAction
        }
        inputRange {
            inputAction = (brightnessPendingIntent)
            max = 100
            value = 45
        }
    }
}

fun createToggleIntent(): PendingIntent {
    val intent = Intent(context, MyBroadcastReceiver::class.java)
    return PendingIntent.getBroadcast(context, 0, intent, 0)
}

جاوا

public Slice createBrightnessSlice(Uri sliceUri) {
    if (getContext() == null) {
        return null;
    }
    SliceAction toggleAction = SliceAction.createToggle(
            createToggleIntent(),
            "Toggle adaptive brightness",
            true
    );
    ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY)
            .addRow(new ListBuilder.RowBuilder()
                    .setTitle("Adaptive brightness")
                    .setSubtitle("Optimizes brightness for available light.")
                    .setPrimaryAction(toggleAction)
            ).addInputRange(new ListBuilder.InputRangeBuilder()
                    .setInputAction(brightnessPendingIntent)
                    .setMax(100)
                    .setValue(45)
            );
    return listBuilder.build();
}

public PendingIntent createToggleIntent() {
    Intent intent = new Intent(getContext(), MyBroadcastReceiver.class);
    return PendingIntent.getBroadcast(getContext(), 0, intent, 0);
}

سپس گیرنده می‌تواند وضعیتی را که دریافت می‌کند بررسی کند:

کاتلین

class MyBroadcastReceiver : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (intent.hasExtra(Slice.EXTRA_TOGGLE_STATE)) {
            Toast.makeText(context, "Toggled:  " + intent.getBooleanExtra(
                    Slice.EXTRA_TOGGLE_STATE, false),
                    Toast.LENGTH_LONG).show()
        }
    }

    companion object {
        const val EXTRA_MESSAGE = "message"
    }
}

جاوا

public class MyBroadcastReceiver extends BroadcastReceiver {

    public static String EXTRA_MESSAGE = "message";

    @Override
    public void onReceive(Context context, Intent intent) {
        if (intent.hasExtra(EXTRA_TOGGLE_STATE)) {
            Toast.makeText(context, "Toggled:  " + intent.getBooleanExtra(
                    EXTRA_TOGGLE_STATE, false),
                    Toast.LENGTH_LONG).show();
        }
    }
}

برش‌های پویا

«برش‌ها» می‌توانند حاوی محتوای پویا نیز باشند. در مثال زیر، «برش» اکنون تعداد پخش‌های دریافتی را در محتوایش لحاظ می‌کند:

کاتلین

fun createDynamicSlice(sliceUri: Uri): Slice {
    return when (sliceUri.path) {
        "/count" -> {
            val toastAndIncrementAction = SliceAction.create(
                createToastAndIncrementIntent("Item clicked."),
                actionIcon,
                ListBuilder.ICON_IMAGE,
                "Increment."
            )
            list(context, sliceUri, ListBuilder.INFINITY) {
                row {
                    primaryAction = toastAndIncrementAction
                    title = "Count: ${MyBroadcastReceiver.receivedCount}"
                    subtitle = "Click me"
                }
            }
        }

        else -> {
            list(context, sliceUri, ListBuilder.INFINITY) {
                row {
                    primaryAction = createActivityAction()
                    title = "URI not found."
                }
            }
        }
    }
}

جاوا

public Slice createDynamicSlice(Uri sliceUri) {
    if (getContext() == null || sliceUri.getPath() == null) {
        return null;
    }
    ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY);
    switch (sliceUri.getPath()) {
        case "/count":
            SliceAction toastAndIncrementAction = SliceAction.create(
                    createToastAndIncrementIntent("Item clicked."),
                    actionIcon,
                    ListBuilder.ICON_IMAGE,
                    "Increment."
            );
            listBuilder.addRow(
                    new ListBuilder.RowBuilder()
                            .setPrimaryAction(toastAndIncrementAction)
                            .setTitle("Count: " + MyBroadcastReceiver.sReceivedCount)
                            .setSubtitle("Click me")
            );
            break;
        default:
            listBuilder.addRow(
                    new ListBuilder.RowBuilder()
                            .setPrimaryAction(createActivityAction())
                            .setTitle("URI not found.")
            );
            break;
    }
    return listBuilder.build();
}

public PendingIntent createToastAndIncrementIntent(String s) {
    Intent intent = new Intent(getContext(), MyBroadcastReceiver.class)
            .putExtra(MyBroadcastReceiver.EXTRA_MESSAGE, s);
    return PendingIntent.getBroadcast(getContext(), 0, intent, 0);
}

در این مثال، اگرچه تعداد نشان داده می‌شود، اما به‌طور خودکار به‌روز نمی‌شود. می‌توانید گیرنده رویداد ثبت‌شده را اصلاح کنید تا بااستفاده از ContentResolver#notifyChange به سیستم اطلاع دهد که تغییری رخ داده است.

کاتلین

class MyBroadcastReceiver : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (intent.hasExtra(Slice.EXTRA_TOGGLE_STATE)) {
            Toast.makeText(
                context, "Toggled:  " + intent.getBooleanExtra(
                    Slice.EXTRA_TOGGLE_STATE, false
                ),
                Toast.LENGTH_LONG
            ).show()
            receivedCount++;
            context.contentResolver.notifyChange(sliceUri, null)
        }
    }

    companion object {
        var receivedCount = 0
        val sliceUri = Uri.parse("content://com.android.example.slicesample/count")
        const val EXTRA_MESSAGE = "message"
    }
}

جاوا

public class MyBroadcastReceiver extends BroadcastReceiver {

    public static int sReceivedCount = 0;
    public static String EXTRA_MESSAGE = "message";

    private static Uri sliceUri = Uri.parse("content://com.android.example.slicesample/count");

    @Override
    public void onReceive(Context context, Intent intent) {
        if (intent.hasExtra(EXTRA_TOGGLE_STATE)) {
            Toast.makeText(context, "Toggled:  " + intent.getBooleanExtra(
                    EXTRA_TOGGLE_STATE, false),
                    Toast.LENGTH_LONG).show();
            sReceivedCount++;
            context.getContentResolver().notifyChange(sliceUri, null);
        }
    }
}

الگوها

«برش‌ها» از الگوهای مختلفی پشتیبانی می‌کنند. برای جزئیات بیشتر درباره گزینه‌ها و رفتارهای الگو، به الگوها مراجعه کنید.