Adicionar seletores ao app

O Android oferece controles para que o usuário escolha uma hora ou data como caixas de diálogo prontas para uso. Esses seletores fornecem controles para selecionar cada parte do horário (hora, minuto, AM/PM) ou data (mês, dia, ano).

Exemplo de seletor de horário em material.io
Figura 1. Seleção de horário em um seletor de agenda para dispositivos móveis.

O uso desses seletores ajuda a garantir que os usuários possam escolher um horário ou data válido, com o formato correto e ajustado para a localidade do usuário.

Exemplo de seletor de data modal em material.io.
Figura 2. Seletor de data modal.

Recomendamos que você use DialogFragment para hospedar cada seletor de horário ou data. O DialogFragment gerencia o ciclo de vida da caixa de diálogo e permite exibir seletores em diferentes configurações de layout, como em uma caixa de diálogo básica em smartphones ou como uma parte incorporada do layout em telas grandes.

Criar um seletor de horário

Para mostrar um TimePickerDialog usando DialogFragment, defina uma classe de fragmento que estenda DialogFragment e retorne um TimePickerDialog do método onCreateDialog() do fragmento.

Estender o DialogFragment para um seletor de horário

Para definir um DialogFragment para um TimePickerDialog, faça o seguinte:

  • Defina o método onCreateDialog() para retornar uma instância de TimePickerDialog.
  • Implemente a interface TimePickerDialog.OnTimeSetListener para receber um callback quando o usuário definir o horário.

Veja um exemplo:

Kotlin

class TimePickerFragment : DialogFragment(), TimePickerDialog.OnTimeSetListener {

    override fun onCreateDialog(savedInstanceState: Bundle): Dialog {
        // Use the current time as the default values for the picker.
        val c = Calendar.getInstance()
        val hour = c.get(Calendar.HOUR_OF_DAY)
        val minute = c.get(Calendar.MINUTE)

        // Create a new instance of TimePickerDialog and return it.
        return TimePickerDialog(activity, this, hour, minute, DateFormat.is24HourFormat(activity))
    }

    override fun onTimeSet(view: TimePicker, hourOfDay: Int, minute: Int) {
        // Do something with the time the user picks.
    }
}

Java

public static class TimePickerFragment extends DialogFragment
                            implements TimePickerDialog.OnTimeSetListener {

    @Override
    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // Use the current time as the default values for the picker.
        final Calendar c = Calendar.getInstance();
        int hour = c.get(Calendar.HOUR_OF_DAY);
        int minute = c.get(Calendar.MINUTE);

        // Create a new instance of TimePickerDialog and return it.
        return new TimePickerDialog(getActivity(), this, hour, minute,
                DateFormat.is24HourFormat(getActivity()));
    }

    public void onTimeSet(TimePicker view, int hourOfDay, int minute) {
        // Do something with the time the user picks.
    }
}

Consulte a classe TimePickerDialog para informações sobre os argumentos do construtor.

Agora você só precisa de um evento que adicione uma instância desse fragmento à atividade.

Mostrar o seletor de horário

Depois de definir um DialogFragment como o do exemplo anterior, você pode mostrar o seletor de horário criando uma instância de DialogFragment e chamando o método show().

Por exemplo, este é um botão que, quando tocado, chama um método para mostrar a caixa de diálogo:

<Button
    android:id="@+id/pickTime"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Pick time" />

Quando o usuário toca nesse botão, o sistema chama o seguinte método:

Kotlin

findViewById<Button>(R.id.pickTime).setOnClickListener {
    TimePickerFragment().show(supportFragmentManager, "timePicker")
}

Java

findViewById<Button>(R.id.pickTime).setOnClickListener {
    TimePickerFragment().show(supportFragmentManager, "timePicker");
}

Esse método chama show() em uma nova instância do DialogFragment definida no exemplo anterior. O método show() requer uma instância de FragmentManager e um nome de tag exclusivo para o fragmento.

Criar um seletor de data

Criar um DatePickerDialog é como criar um TimePickerDialog. A diferença é a caixa de diálogo que você cria para o fragmento.

Para exibir um DatePickerDialog usando DialogFragment, defina uma classe de fragmento que estenda DialogFragment e retorne um DatePickerDialog do método onCreateDialog() do fragmento.

Estender o DialogFragment para um seletor de data

Para definir um DialogFragment para um DatePickerDialog, faça o seguinte:

  • Defina o método onCreateDialog() para retornar uma instância de DatePickerDialog.
  • Implemente a interface DatePickerDialog.OnDateSetListener para receber um callback quando o usuário definir a data.

Veja um exemplo:

Kotlin

class DatePickerFragment : DialogFragment(), DatePickerDialog.OnDateSetListener {

    override fun onCreateDialog(savedInstanceState: Bundle): Dialog {
        // Use the current date as the default date in the picker.
        val c = Calendar.getInstance()
        val year = c.get(Calendar.YEAR)
        val month = c.get(Calendar.MONTH)
        val day = c.get(Calendar.DAY_OF_MONTH)

        // Create a new instance of DatePickerDialog and return it.
        return DatePickerDialog(requireContext(), this, year, month, day)

    }

    override fun onDateSet(view: DatePicker, year: Int, month: Int, day: Int) {
        // Do something with the date the user picks.
    }
}

Java

public static class DatePickerFragment extends DialogFragment
                            implements DatePickerDialog.OnDateSetListener {

    @Override
    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // Use the current date as the default date in the picker.
        final Calendar c = Calendar.getInstance();
        int year = c.get(Calendar.YEAR);
        int month = c.get(Calendar.MONTH);
        int day = c.get(Calendar.DAY_OF_MONTH);

        // Create a new instance of DatePickerDialog and return it.
        return new DatePickerDialog(requireContext(), this, year, month, day);
    }

    public void onDateSet(DatePicker view, int year, int month, int day) {
        // Do something with the date the user picks.
    }
}

Consulte a classe DatePickerDialog para informações sobre os argumentos do construtor.

Você só precisa de um evento que adicione uma instância desse fragmento à atividade.

Mostrar o seletor de data

Depois de definir uma DialogFragment como o exemplo anterior, você pode exibir o seletor de data criando uma instância de DialogFragment e chamando show().

Por exemplo, este é um botão que, quando tocado, chama um método para mostrar a caixa de diálogo:

<Button
    android:id="@+id/pickDate"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Pick date"/>

Quando o usuário toca nesse botão, o sistema chama o seguinte método:

Kotlin

findViewById<Button>(R.id.pickDate).setOnClickListener {
    val newFragment = DatePickerFragment()
    newFragment.show(supportFragmentManager, "datePicker")
}

Java

findViewById<Button>(R.id.pickDate).setOnClickListener {
    val newFragment = DatePickerFragment();
    newFragment.show(supportFragmentManager, "datePicker");
}

Esse método chama show() em uma nova instância do DialogFragment definida no exemplo anterior. O método show() requer uma instância de FragmentManager e um nome de tag exclusivo para o fragmento.

Usar seletores com o preenchimento automático

Em 2017, o Android lançou a Estrutura de preenchimento automático, que permite que os usuários salvem dados que podem ser usados para preencher formulários em diferentes apps. Os seletores podem ser úteis em situações de preenchimento automático, fornecendo uma interface que permite aos usuários mudar o valor de um campo que armazena dados de data ou hora. Por exemplo, em um formulário de cartão de crédito, um seletor de data permite que os usuários insiram ou mudem a data de validade do cartão.

Como os seletores são caixas de diálogo, eles não são exibidos em uma atividade junto com outros campos. Para exibir os dados do seletor quando ele não estiver visível, você pode usar outra visualização, como EditText, que pode mostrar o valor quando o seletor não estiver visível.

Um objeto EditText espera nativamente o preenchimento automático de dados do tipo AUTOFILL_TYPE_TEXT. Por outro lado, os serviços de preenchimento automático salvam os dados como AUTOFILL_TYPE_DATE para criar uma representação adequada deles. Para resolver a inconsistência nos tipos, recomendamos que você crie uma visualização personalizada herdada de EditText e que implemente os métodos necessários para processar corretamente os valores do tipo AUTOFILL_TYPE_DATE.

Siga estas etapas para criar uma subclasse de EditText que possa processar valores do tipo AUTOFILL_TYPE_DATE:

  1. Crie uma classe herdada de EditText.
  2. Implemente o método getAutofillType(), que retorna AUTOFILL_TYPE_DATE.
  3. Implemente o método getAutofillValue(), que retorna um objeto AutofillValue que representa a data em milissegundos. Para criar o objeto de retorno, use o método forDate() para gerar um objeto AutofillValue.
  4. Implemente o método autofill(). Esse método fornece a lógica para processar o parâmetro AutofillValue, que é do tipo AUTOFILL_TYPE_DATE. Para manipular o parâmetro, crie uma representação de string adequada dele, como mm/yyyy. Use a representação de string para definir a propriedade text da sua visualização.
  5. Implemente a funcionalidade que exibe um seletor quando o usuário quer editar a data na subclasse personalizada de EditText. A visualização atualiza a propriedade text com uma representação de string do valor que o usuário seleciona no seletor.

Para ver um exemplo de uma subclasse de EditText que processa valores AUTOFILL_TYPE_DATE, consulte o exemplo de Estrutura de preenchimento automático em Java ou Kotlin.

Para saber mais sobre como provar a compatibilidade com o preenchimento automático para visualizações personalizadas, consulte Estrutura de preenchimento automático.