Ten dokument zawiera szczegółowe informacje o tym, jak używać kreatorów szablonów w Android Jetpack do tworzenia wycinków.
Definiowanie szablonu wycinka
Wycinki tworzy się za pomocą ListBuilder
. ListBuilder umożliwia dodawanie różnych typów wierszy wyświetlanych na liście. W tej sekcji opisujemy poszczególne typy wierszy i sposób ich tworzenia.
Działanie na wycinku
Podstawowym elementem szablonu wycinka jest SliceAction
. SliceAction
zawiera etykietę wraz z PendingIntent
i jest jednym z tych elementów:
- Przycisk ikony
- Przełącznik domyślny
- Niestandardowy przełącznik (element, który można przeciągać, włączając i wyłączając)
Tabela SliceAction
jest używana przez kreatory szablonów opisane w pozostałej części tej sekcji. Element SliceAction
może mieć zdefiniowany tryb obrazu, który określa sposób prezentacji obrazu w ramach tego działania:
ICON_IMAGE
: mały rozmiar i możliwość zmiany rozmiaruSMALL_IMAGE
: mały rozmiar i niekolorowyLARGE_IMAGE
: największy rozmiar i niekolorowy
Twórca nagłówków
W większości przypadków nagłówek należy ustawić za pomocą właściwości HeaderBuilder
.
Nagłówek może obsługiwać te elementy:
- tytuł;
- Podtytuł
- Podtytuł podsumowania
- Główne działanie
Poniżej znajdziesz przykładowe konfiguracje nagłówków. Pamiętaj, że szare pola pokazują potencjalną ikonę i miejsca dopełnienia:
Renderowanie nagłówka na różnych platformach
Gdy potrzebny jest wycinek, wyświetlana powierzchnia określa sposób renderowania. Pamiętaj, że w przypadku platform hostujących renderowanie może się nieco różnić.
W mniejszych formatach zwykle wyświetla się tylko nagłówek, jeśli taki istnieje. Jeśli określisz podsumowanie w nagłówku, wyświetli się ono zamiast tekstu podtytułu.
Jeśli w szablonie nie określisz nagłówka, zazwyczaj zamiast niego wyświetla się pierwszy wiersz dodany do elementu ListBuilder
.
Przykład strony HeaderBuilder – prosty wycinek listy z nagłówkiem
Kotlin
fun createSliceWithHeader(sliceUri: Uri) = list(context, sliceUri, ListBuilder.INFINITY) { setAccentColor(0xff0F9D) // Specify color for tinting icons header { title = "Get a ride" subtitle = "Ride in 4 min" summary = "Work in 1 hour 45 min | Home in 12 min" } row { title = "Home" subtitle = "12 miles | 12 min | $9.00" addEndItem( IconCompat.createWithResource(context, R.drawable.ic_home), ListBuilder.ICON_IMAGE ) } }
Java
public Slice createSliceWithHeader(Uri sliceUri) { if (getContext() == null) { return null; } // Construct the parent. ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY) .setAccentColor(0xff0F9D58) // Specify color for tinting icons. .setHeader( // Create the header and add to slice. new HeaderBuilder() .setTitle("Get a ride") .setSubtitle("Ride in 4 min.") .setSummary("Work in 1 hour 45 min | Home in 12 min.") ).addRow(new RowBuilder() // Add a row. .setPrimaryAction( createActivityAction()) // A slice always needs a SliceAction. .setTitle("Home") .setSubtitle("12 miles | 12 min | $9.00") .addEndItem(IconCompat.createWithResource(getContext(), R.drawable.ic_home), SliceHints.ICON_IMAGE) ); // Add more rows if needed... return listBuilder.build(); }
SliceActions w nagłówkach
Nagłówki wycinków mogą też wyświetlać te działania:
Kotlin
fun createSliceWithActionInHeader(sliceUri: Uri): Slice { // Construct our slice actions. val noteAction = SliceAction.create( takeNoteIntent, IconCompat.createWithResource(context, R.drawable.ic_pencil), ICON_IMAGE, "Take note" ) val voiceNoteAction = SliceAction.create( voiceNoteIntent, IconCompat.createWithResource(context, R.drawable.ic_mic), ICON_IMAGE, "Take voice note" ) val cameraNoteAction = SliceAction.create( cameraNoteIntent, IconCompat.createWithResource(context, R.drawable.ic_camera), ICON_IMAGE, "Create photo note" ) // Construct the list. return list(context, sliceUri, ListBuilder.INFINITY) { setAccentColor(0xfff4b4) // Specify color for tinting icons header { title = "Create new note" subtitle = "Easily done with this note taking app" } addAction(noteAction) addAction(voiceNoteAction) addAction(cameraNoteAction) } }
Java
public Slice createSliceWithActionInHeader(Uri sliceUri) { if (getContext() == null) { return null; } // Construct our slice actions. SliceAction noteAction = SliceAction.create(takeNoteIntent, IconCompat.createWithResource(getContext(), R.drawable.ic_pencil), ListBuilder.ICON_IMAGE, "Take note"); SliceAction voiceNoteAction = SliceAction.create(voiceNoteIntent, IconCompat.createWithResource(getContext(), R.drawable.ic_mic), ListBuilder.ICON_IMAGE, "Take voice note"); SliceAction cameraNoteAction = SliceAction.create(cameraNoteIntent, IconCompat.createWithResource(getContext(), R.drawable.ic_camera), ListBuilder.ICON_IMAGE, "Create photo note"); // Construct the list. ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY) .setAccentColor(0xfff4b400) // Specify color for tinting icons .setHeader(new HeaderBuilder() // Construct the header. .setTitle("Create new note") .setSubtitle("Easily done with this note taking app") ) .addRow(new RowBuilder() .setTitle("Enter app") .setPrimaryAction(createActivityAction()) ) // Add the actions to the ListBuilder. .addAction(noteAction) .addAction(voiceNoteAction) .addAction(cameraNoteAction); return listBuilder.build(); }
Kreator wierszy
Wiersz treści możesz utworzyć za pomocą RowBuilder
. Wiersz może obsługiwać dowolne z tych elementów:
- tytuł;
- Podtytuł
- Element początkowy: SliceAction, Icon lub sygnatura czasowa
- Elementy końcowe: SliceAction, Icon lub sygnatura czasowa
- Główne działanie
Zawartość wierszy możesz łączyć na wiele sposobów, podlegając tym ograniczeniom:
- Elementy początkowe nie będą wyświetlane w pierwszym wierszu wycinka.
- Elementy końcowe nie mogą składać się z obiektów
SliceAction
iIcon
- Wiersz może zawierać tylko 1 sygnaturę czasową
Przykładowe wiersze treści są pokazane na tych obrazach. Pamiętaj, że szare pola pokazują potencjalne lokalizacje ikon i dopełnienia:
Przykład RowBuilder – przełącznik Wi-Fi
Przykład poniżej pokazuje wiersz z działaniem głównym i przełącznikiem domyślnym.
Kotlin
fun createActionWithActionInRow(sliceUri: Uri): Slice { // Primary action - open wifi settings. val wifiAction = SliceAction.create( wifiSettingsPendingIntent, IconCompat.createWithResource(context, R.drawable.ic_wifi), ICON_IMAGE, "Wi-Fi Settings" ) // Toggle action - toggle wifi. val toggleAction = SliceAction.createToggle( wifiTogglePendingIntent, "Toggle Wi-Fi", isConnected /* isChecked */ ) // Create the parent builder. return list(context, wifiUri, ListBuilder.INFINITY) { setAccentColor(0xff4285) // Specify color for tinting icons / controls. row { title = "Wi-Fi" primaryAction = wifiAction addEndItem(toggleAction) } } }
Java
public Slice createActionWithActionInRow(Uri sliceUri) { if (getContext() == null) { return null; } // Primary action - open wifi settings. SliceAction primaryAction = SliceAction.create(wifiSettingsPendingIntent, IconCompat.createWithResource(getContext(), R.drawable.ic_wifi), ListBuilder.ICON_IMAGE, "Wi-Fi Settings" ); // Toggle action - toggle wifi. SliceAction toggleAction = SliceAction.createToggle(wifiTogglePendingIntent, "Toggle Wi-Fi", isConnected /* isChecked */); // Create the parent builder. ListBuilder listBuilder = new ListBuilder(getContext(), wifiUri, ListBuilder.INFINITY) // Specify color for tinting icons / controls. .setAccentColor(0xff4285f4) // Create and add a row. .addRow(new RowBuilder() .setTitle("Wi-Fi") .setPrimaryAction(primaryAction) .addEndItem(toggleAction)); // Build the slice. return listBuilder.build(); }
Kreator siatki
Siatę treści możesz utworzyć za pomocą elementu GridBuilder
. Siatka może obsługiwać te typy obrazów:
ICON_IMAGE
: mały rozmiar i możliwość zmiany rozmiaruSMALL_IMAGE
: mały rozmiar i niekolorowyLARGE_IMAGE
: największy rozmiar i niekolorowy
Komórkę siatki można utworzyć przy użyciu elementu CellBuilder
. Komórka może obsługiwać maksymalnie 2 wiersze tekstu i 1 obraz. Komórka nie może być pusta.
Przykłady siatki są widoczne na tych ilustracjach:
Przykład elementu GridRowBuilder – restauracje w pobliżu
Przykład poniżej pokazuje wiersz siatki zawierający obrazy i tekst.
Kotlin
fun createSliceWithGridRow(sliceUri: Uri): Slice { // Create the parent builder. return list(context, sliceUri, ListBuilder.INFINITY) { header { title = "Famous restaurants" primaryAction = SliceAction.create( pendingIntent, icon, ListBuilder.ICON_IMAGE, "Famous restaurants" ) } gridRow { cell { addImage(image1, LARGE_IMAGE) addTitleText("Top Restaurant") addText("0.3 mil") contentIntent = intent1 } cell { addImage(image2, LARGE_IMAGE) addTitleText("Fast and Casual") addText("0.5 mil") contentIntent = intent2 } cell { addImage(image3, LARGE_IMAGE) addTitleText("Casual Diner") addText("0.9 mi") contentIntent = intent3 } cell { addImage(image4, LARGE_IMAGE) addTitleText("Ramen Spot") addText("1.2 mi") contentIntent = intent4 } } } }
Java
public Slice createSliceWithGridRow(Uri sliceUri) { if (getContext() == null) { return null; } // Create the parent builder. ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY) .setHeader( // Create the header. new HeaderBuilder() .setTitle("Famous restaurants") .setPrimaryAction(SliceAction .create(pendingIntent, icon, ListBuilder.ICON_IMAGE, "Famous restaurants")) ) // Add a grid row to the list. .addGridRow(new GridRowBuilder() // Add cells to the grid row. .addCell(new CellBuilder() .addImage(image1, ListBuilder.LARGE_IMAGE) .addTitleText("Top Restaurant") .addText("0.3 mil") .setContentIntent(intent1) ).addCell(new CellBuilder() .addImage(image2, ListBuilder.LARGE_IMAGE) .addTitleText("Fast and Casual") .addText("0.5 mil") .setContentIntent(intent2) ) .addCell(new CellBuilder() .addImage(image3, ListBuilder.LARGE_IMAGE) .addTitleText("Casual Diner") .addText("0.9 mi") .setContentIntent(intent3)) .addCell(new CellBuilder() .addImage(image4, ListBuilder.LARGE_IMAGE) .addTitleText("Ramen Spot") .addText("1.2 mi") .setContentIntent(intent4)) // Every slice needs a primary action. .setPrimaryAction(createActivityAction()) ); return listBuilder.build(); }
Kreator zakresu
RangeBuilder
pozwala utworzyć wiersz zawierający pasek postępu lub zakres danych wejściowych, np. suwak.
Przykłady postępów i suwaków pokazane są na tych obrazach:
Przykład obiektu RangeBuilder – Slider
Przykład poniżej pokazuje, jak za pomocą elementu InputRangeBuilder
utworzyć wycinek zawierający suwak woluminu. Aby utworzyć wiersz postępu, użyj addRange()
.
Kotlin
fun createSliceWithRange(sliceUri: Uri): Slice { return list(context, sliceUri, ListBuilder.INFINITY) { inputRange { title = "Ring Volume" inputAction = volumeChangedPendingIntent max = 100 value = 30 } } }
Java
public Slice createSliceWithRange(Uri sliceUri) { if (getContext() == null) { return null; } // Construct the parent. ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY) .addRow(new RowBuilder() // Every slice needs a row. .setTitle("Enter app") // Every slice needs a primary action. .setPrimaryAction(createActivityAction()) ) .addInputRange(new InputRangeBuilder() // Create the input row. .setTitle("Ring Volume") .setInputAction(volumeChangedPendingIntent) .setMax(100) .setValue(30) ); return listBuilder.build(); }
Opóźnione treści
Wycinek należy zwrócić jak najszybciej z SliceProvider.onBindSlice()
.
Czasochłonne połączenia mogą powodować problemy z wyświetlaniem, takie jak migotanie i nagłe zmiany rozmiaru.
Jeśli masz wycinek treści, którego nie można szybko wczytać, możesz utworzyć wycinek z zawartością zastępczą, a jednocześnie poinformować w konstruktorze, że zawartość się wczytuje. Gdy treść będzie gotowa do wyświetlenia, wywołaj getContentResolver().notifyChange(sliceUri, null)
przy użyciu identyfikatora URI wycinka. Powoduje to ponowne wywołanie funkcji SliceProvider.onBindSlice()
, w której możesz utworzyć wycinek ponownie z nową treścią.
Przykład opóźnionych treści – Jedź do pracy
W poniższym wierszu Przejazd do pracy odległość do pracy jest określana dynamicznie i może nie być dostępna natychmiast. Przykładowy kod pokazuje, jak użyć pustego podtytułu jako symbolu zastępczego podczas wczytywania treści:
Kotlin
fun createSliceShowingLoading(sliceUri: Uri): Slice { // We’re waiting to load the time to work so indicate that on the slice by // setting the subtitle with the overloaded method and indicate true. return list(context, sliceUri, ListBuilder.INFINITY) { row { title = "Ride to work" setSubtitle(null, true) addEndItem(IconCompat.createWithResource(context, R.drawable.ic_work), ICON_IMAGE) } } }
Java
public Slice createSliceShowingLoading(Uri sliceUri) { if (getContext() == null) { return null; } // Construct the parent. ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY) // Construct the row. .addRow(new RowBuilder() .setPrimaryAction(createActivityAction()) .setTitle("Ride to work") // We’re waiting to load the time to work so indicate that on the slice by // setting the subtitle with the overloaded method and indicate true. .setSubtitle(null, true) .addEndItem(IconCompat.createWithResource(getContext(), R.drawable.ic_work), ListBuilder.ICON_IMAGE) ); return listBuilder.build(); } private SliceAction createActivityAction() { 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" ); }
Wyłączaj przewijanie w wycinku
Powierzchnia, na której wyświetlany jest szablon wycinka, może nie obsługiwać przewijania w jego obrębie. W takim przypadku niektóre treści mogą się nie wyświetlać.
Przykładem może być wycinek zawierający listę sieci Wi-Fi:
Jeśli lista Wi-Fi jest długa, a przewijanie jest wyłączone, możesz dodać przycisk Zobacz więcej, aby umożliwić użytkownikom przeglądanie wszystkich jej elementów. Możesz dodać ten przycisk, używając parametru addSeeMoreAction()
, jak w tym przykładzie:
Kotlin
fun seeMoreActionSlice(sliceUri: Uri) = list(context, sliceUri, ListBuilder.INFINITY) { // [START_EXCLUDE] // [END_EXCLUDE] setSeeMoreAction(seeAllNetworksPendingIntent) // [START_EXCLUDE] // [END_EXCLUDE] }
Java
public Slice seeMoreActionSlice(Uri sliceUri) { if (getContext() == null) { return null; } ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY); // [START_EXCLUDE] listBuilder.addRow(new RowBuilder() .setTitle("Hello") .setPrimaryAction(createActivityAction()) ); // [END_EXCLUDE] listBuilder.setSeeMoreAction(seeAllNetworksPendingIntent); // [START_EXCLUDE] // [END_EXCLUDE] return listBuilder.build(); }
Jak widać na tym zdjęciu:
Kliknięcie Zobacz więcej powoduje wysłanie seeAllNetworksPendingIntent
.
Jeśli chcesz podać niestandardowy komunikat lub wiersz, możesz też dodać obiekt RowBuilder:
Kotlin
fun seeMoreRowSlice(sliceUri: Uri) = list(context, sliceUri, ListBuilder.INFINITY) { // [START_EXCLUDE] // [END_EXCLUDE] seeMoreRow { title = "See all available networks" addEndItem( IconCompat.createWithResource(context, R.drawable.ic_right_caret), ICON_IMAGE ) primaryAction = SliceAction.create( seeAllNetworksPendingIntent, IconCompat.createWithResource(context, R.drawable.ic_wifi), ListBuilder.ICON_IMAGE, "Wi-Fi Networks" ) } }
Java
public Slice seeMoreRowSlice(Uri sliceUri) { if (getContext() == null) { return null; } ListBuilder listBuilder = new ListBuilder(getContext(), sliceUri, ListBuilder.INFINITY) // [START_EXCLUDE] .addRow(new RowBuilder() .setTitle("Hello") .setPrimaryAction(createActivityAction()) ) // [END_EXCLUDE] .setSeeMoreRow(new RowBuilder() .setTitle("See all available networks") .addEndItem(IconCompat .createWithResource(getContext(), R.drawable .ic_right_caret), ListBuilder.ICON_IMAGE) .setPrimaryAction(SliceAction.create(seeAllNetworksPendingIntent, IconCompat.createWithResource(getContext(), R.drawable.ic_wifi), ListBuilder.ICON_IMAGE, "Wi-Fi Networks")) ); // [START_EXCLUDE] // [END_EXCLUDE] return listBuilder.build(); }
Wiersz lub działanie dodane za pomocą tej metody wyświetlają się tylko wtedy, gdy spełniony jest jeden z tych warunków:
- Prezenter wycinka wyłączył przewijanie widoku
- W dostępnym miejscu nie można wyświetlić wszystkich wierszy
Łączenie szablonów
Możesz utworzyć bogaty, dynamiczny wycinek, łącząc wiele typów wierszy. Na przykład wycinek może zawierać wiersz nagłówka, siatkę z jednym obrazem i siatkę z dwiema komórkami z tekstem.
Oto wycinek z wierszem nagłówka i siatką zawierającą 3 komórki.