Esta página foi traduzida pela API Cloud Translation.

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, período do dia) ou data (mês, dia, ano).

Exemplo de seletor de horário do 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 do material.io — **Figura 2**. Seletor modal de data.

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 uma caixa de diálogo básica em dispositivos móveis ou 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 à sua atividade.

Mostrar o seletor de horário

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

Por exemplo, aqui está 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 de 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 criada para o fragmento.

Para mostrar 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 datas

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 um DialogFragment como o exemplo anterior, você pode exibir o seletor de datas criando uma instância de DialogFragment e chamando show().

Por exemplo, aqui está 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 para preencher formulários em diferentes apps. Os seletores podem ser úteis em algumas situações de preenchimento automático, porque fornecem uma interface que permite que os usuários mudem 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 mostrar os dados do seletor quando ele não estiver visível, use 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. Em contrapartida, os serviços de preenchimento automático salvam os dados como AUTOFILL_TYPE_DATE para criar uma representação adequada. Para resolver a inconsistência nos tipos, recomendamos que você crie uma visualização personalizada herdada de EditText que implemente os métodos necessários para processar corretamente os valores do tipo AUTOFILL_TYPE_DATE.

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

Crie uma classe herdada de EditText.
Implemente o método getAutofillType(), que retorna AUTOFILL_TYPE_DATE.
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.
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 processar o parâmetro, crie uma representação de string adequada, como mm/yyyy. Use a representação de string para definir a propriedade text da visualização.
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 conferir um exemplo de uma subclasse de EditText que processa valores AUTOFILL_TYPE_DATE, consulte o exemplo da Estrutura de preenchimento automático em Java ou Kotlin (links em inglês).

Para saber mais sobre como oferecer suporte ao preenchimento automático para suas visualizações personalizadas, consulte Estrutura de preenchimento automático.