Criar um Fragment

Um fragmento representa uma parte modular da interface do usuário em uma atividade. Um fragmento tem ciclo de vida próprio e recebe os próprios eventos de entrada. Você pode adicionar ou remover fragmentos enquanto a atividade contida está em execução.

Este documento descreve como criar um fragmento e incluí-lo em uma atividade.

Configurar o ambiente

Os fragmentos exigem uma dependência na biblioteca AndroidX Fragment. Você precisa adicionar o repositório Maven do Google ao arquivo settings.gradle do projeto para incluir essa dependência.

Groovy

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        ...
    }
}

Kotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        ...
    }
}

Para incluir a biblioteca AndroidX Fragment no projeto, adicione as seguintes dependências ao arquivo build.gradle do app:

Groovy

dependencies {
    def fragment_version = "1.8.3"

    // Java language implementation
    implementation "androidx.fragment:fragment:$fragment_version"
    // Kotlin
    implementation "androidx.fragment:fragment-ktx:$fragment_version"
}

Kotlin

dependencies {
    val fragment_version = "1.8.3"

    // Java language implementation
    implementation("androidx.fragment:fragment:$fragment_version")
    // Kotlin
    implementation("androidx.fragment:fragment-ktx:$fragment_version")
}

Criar uma classe de fragmento

Para criar um fragmento, estenda a classe Fragment do AndroidX e substitua os métodos para inserir a lógica do seu app, de modo semelhante a como você criaria uma classe Activity. Para criar um fragmento mínimo que defina o próprio layout, forneça o recurso de layout do fragmento para o construtor base, conforme mostrado no exemplo a seguir:

Kotlin

class ExampleFragment : Fragment(R.layout.example_fragment)

Java

class ExampleFragment extends Fragment {
    public ExampleFragment() {
        super(R.layout.example_fragment);
    }
}

A biblioteca Fragment também oferece classes base de fragmentos mais especializados:

DialogFragment

Exibe uma caixa de diálogo flutuante. Usar essa classe para criar uma caixa de diálogo é uma boa alternativa para o uso dos métodos auxiliares de caixa de diálogo na classe Activity, já que os fragmentos processam automaticamente a criação e a limpeza da Dialog. Consulte Como exibir caixas de diálogo com DialogFragment para ver mais detalhes.

PreferenceFragmentCompat

Exibe uma hierarquia de objetos Preference como uma lista. Você pode usar PreferenceFragmentCompat para criar uma tela de configurações para o app.

Adicionar um fragmento a uma atividade

Geralmente, o fragmento precisa ser incorporado a uma FragmentActivity do AndroidX para contribuir com parte da IU para o layout dessa atividade. FragmentActivity é a classe base de AppCompatActivity. Portanto, caso você já tenha subclasses AppCompatActivity para oferecer compatibilidade com versões anteriores no seu app, não será necessário mudar a classe base de atividades.

É possível adicionar seu fragmento à hierarquia de visualização da atividade definindo o fragmento no arquivo de layout da atividade ou definindo um contêiner de fragmento no arquivo de layout da atividade e, em seguida, adicionando o fragmento de maneira programática pela atividade. Em ambos os casos, é necessário adicionar uma FragmentContainerView que defina o local em que o fragmento será colocado na hierarquia de visualização da atividade. É altamente recomendável usar uma FragmentContainerView como o contêiner de fragmentos, já que FragmentContainerView inclui correções específicas de fragmentos que outros grupos de visualização, como FrameLayout, não oferecem.

Adicionar um fragmento por XML

Para adicionar um fragmento de maneira declarativa ao XML do layout da atividade, use um elemento FragmentContainerView.

Veja um exemplo de layout de atividade que contém uma única FragmentContainerView:

<!-- res/layout/example_activity.xml -->
<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/fragment_container_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:name="com.example.ExampleFragment" />

O atributo android:name especifica o nome da classe do Fragment a ser instanciado. Quando o layout da atividade é inflado, o fragmento especificado é instanciado, onInflate() é chamado no fragmento recém-instanciado e uma FragmentTransaction é criada para adicionar o fragmento ao FragmentManager.

Observação: é possível usar o atributo class em vez de android:name, como uma forma alternativa de especificar qual Fragment será instanciado.

Adicionar um fragmento de forma programática

Para adicionar um fragmento ao layout da atividade de forma programática, o layout precisa incluir uma FragmentContainerView para servir como contêiner de fragmento, conforme mostrado no exemplo a seguir:

<!-- res/layout/example_activity.xml -->
<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/fragment_container_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Ao contrário da abordagem XML, aqui o atributo android:name não é usado na FragmentContainerView. Portanto, nenhum fragmento específico é instanciado automaticamente. Em vez disso, uma FragmentTransaction é usada para instanciar um fragmento e adicioná-lo ao layout da atividade.

Enquanto a atividade está em execução, você pode fazer transações de fragmentos, como adicionar, remover ou substituir um fragmento. Na FragmentActivity, é possível receber uma instância do FragmentManager, que pode ser usada para criar uma FragmentTransaction. Em seguida, instancie o fragmento no método onCreate() da atividade usando FragmentTransaction.add() e transmitindo o ID de ViewGroup do contêiner no layout e a classe de fragmento que você quer adicionar. Em seguida, confirme a transação, como mostrado no exemplo a seguir.

Kotlin

class ExampleActivity : AppCompatActivity(R.layout.example_activity) {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState == null) {
            supportFragmentManager.commit {
                setReorderingAllowed(true)
                add<ExampleFragment>(R.id.fragment_container_view)
            }
        }
    }
}

Java

public class ExampleActivity extends AppCompatActivity {
    public ExampleActivity() {
        super(R.layout.example_activity);
    }
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            getSupportFragmentManager().beginTransaction()
                .setReorderingAllowed(true)
                .add(R.id.fragment_container_view, ExampleFragment.class, null)
                .commit();
        }
    }
}

Observação: sempre use setReorderingAllowed(true) ao executar uma FragmentTransaction. Para ver mais informações sobre transações reordenadas, consulte Transações de fragmentos.

No exemplo anterior, a transação do fragmento só é criada quando savedInstanceState é null. Isso garante que o fragmento seja adicionado somente uma vez, quando a atividade é criada. Quando uma mudança de configuração ocorre e a atividade é recriada, savedInstanceState deixa de ser null e o fragmento não precisa ser adicionado novamente, já que ele é automaticamente restaurado do savedInstanceState.

Caso o fragmento exija alguns dados iniciais, os argumentos poderão ser transmitidos para o fragmento, fornecendo um Bundle na chamada de FragmentTransaction.add(), conforme mostrado abaixo:

Kotlin

class ExampleActivity : AppCompatActivity(R.layout.example_activity) {
      override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState == null) {
            val bundle = bundleOf("some_int" to 0)
            supportFragmentManager.commit {
                setReorderingAllowed(true)
                add<ExampleFragment>(R.id.fragment_container_view, args = bundle)
            }
        }
    }
}

Java

public class ExampleActivity extends AppCompatActivity {
    public ExampleActivity() {
        super(R.layout.example_activity);
    }
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            Bundle bundle = new Bundle();
            bundle.putInt("some_int", 0);

            getSupportFragmentManager().beginTransaction()
                .setReorderingAllowed(true)
                .add(R.id.fragment_container_view, ExampleFragment.class, bundle)
                .commit();
        }
    }
}

Os argumentos Bundle podem ser recuperados do fragmento chamando requireArguments(), e os métodos getter de Bundle adequados podem ser usados para recuperar cada argumento.

Kotlin

class ExampleFragment : Fragment(R.layout.example_fragment) {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        val someInt = requireArguments().getInt("some_int")
        ...
    }
}

Java

class ExampleFragment extends Fragment {
    public ExampleFragment() {
        super(R.layout.example_fragment);
    }

    @Override
    public void onViewCreated(@NonNull View view, Bundle savedInstanceState) {
        int someInt = requireArguments().getInt("some_int");
        ...
    }
}

Veja também

As transações de fragmentos e FragmentManager são abordados mais detalhadamente no Guia do gerenciador de fragmentos.