O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Esta página foi traduzida pela API Cloud Translation.

Arquitetura de informações

O Android 8.0 introduziu uma nova arquitetura de informações para o app Configurações para simplificar a maneira como as configurações são organizadas e facilitar para os usuários encontrarem rapidamente as configurações para personalizar os dispositivos Android. O Android 9 introduziu algumas melhorias para oferecer mais funcionalidades de configurações e uma implementação mais fácil.

Exemplos e origem

A maioria das páginas em "Configurações" está implementada usando o novo framework. Um bom exemplo é DisplaySettings: packages/apps/Settings/src/com/android/settings/DisplaySettings.java

Os caminhos de arquivos para componentes importantes estão listados abaixo:

CategoryKey: packages/SettingsLib/src/com/android/settingslib/drawer/CategoryKey.java
DashboardFragmentRegistry: packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragmentRegistry.java
DashboardFragment: packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragment.java
BackgroundPreferenceController: frameworks/base/packages/SettingsLib/src/com/android/settingslib/core/AbstractPreferenceController.java
BasePreferenceController (introduzido no Android 9): packages/apps/Settings/src/com/android/settings/core/BasePreferenceController.java

Implementação

Os fabricantes de dispositivos são incentivados a adaptar a arquitetura de informações de configurações existente e inserir outras páginas de configuração conforme necessário para acomodar recursos específicos do parceiro. Mover preferências da página legada (implementada como SettingsPreferencePage) para uma nova página (implementada usando DashboardFragment) pode ser complicado. A preferência da página legada provavelmente não foi implementada com um PreferenceController.

Portanto, ao mover as preferências de uma página legada para uma nova, é necessário criar um PreferenceController e mover o código para o controlador antes de instanciá-lo no novo DashboardFragment. As APIs que PreferenceController exige são descritas no nome e documentadas no Javadoc.

É altamente recomendável adicionar um teste de unidade para cada PreferenceController. Se a mudança for enviada ao AOSP, será necessário um teste de unidade. Para mais informações sobre como criar testes baseados no Robolectric, consulte o arquivo README packages/apps/Settings/tests/robotests/README.md.

Arquitetura da informação de estilo de plug-in

Cada item de configurações é implementado como uma Preferência. Uma preferência pode ser facilmente movida de uma página para outra.

Para facilitar a movimentação de várias configurações, o Android 8.0 introduziu um fragmento de host no estilo de plug-in que contém itens de configuração. Os itens de configuração são modelados como controladores no estilo de plug-in. Portanto, uma página de configurações é criada por um único fragmento de host e vários controladores de configuração.

DashboardFragment

O DashboardFragment é o host de controladores de preferência do estilo de plug-in. O fragmento é herdado de PreferenceFragment e tem hooks para expandir e atualizar listas de preferências estáticas e dinâmicas.

Preferências estáticas

Uma lista de preferências estáticas é definida em XML usando a tag <Preference>. Uma implementação de DashboardFragment usa o método getPreferenceScreenResId() para definir qual arquivo XML contém a lista estática de preferências a serem mostradas.

Preferências dinâmicas

Um item dinâmico representa um bloco com intent, levando a uma atividade externa ou interna. Normalmente, a intent leva a uma página de configuração diferente. Por exemplo, o item de configuração "Google" na página inicial "Configurações" é dinâmico. Os itens dinâmicos são definidos em AndroidManifest (discutidos abaixo) e carregados por meio de um FeatureProvider (definido como DashboardFeatureProvider).

As configurações dinâmicas são mais pesadas do que as definidas estaticamente. Portanto, normalmente os desenvolvedores precisam implementar a configuração como estática. No entanto, a configuração dinâmica pode ser útil quando alguma das seguintes condições é verdadeira:

A configuração não é implementada diretamente no app Configurações, por exemplo, injetando uma configuração implementada por apps de OEM/operadora.
A configuração deve aparecer na página inicial de Configurações.
Você já tem uma atividade para a configuração e não quer implementar a configuração estática extra.

Para definir uma atividade como dinâmica, faça o seguinte:

Marque a atividade como uma configuração dinâmica adicionando um filtro de intent a ela.
Informe ao app Configurações a que categoria ele pertence. A categoria é uma constante, definida em CategoryKey.
Opcional: adicione um texto de resumo quando a configuração for exibida.

Aqui está um exemplo retirado do app Configurações de DisplaySettings.

<activity android:name="Settings$DisplaySettingsActivity"
                   android:label="@string/display_settings"
                   android:icon="@drawable/ic_settings_display">
             <!-- Mark the activity as a dynamic setting -->
              <intent-filter>
                     <action android:name="com.android.settings.action.IA_SETTINGS" />
              </intent-filter>
             <!-- Tell Settings app which category it belongs to -->
              <meta-data android:name="com.android.settings.category"
                     android:value="com.android.settings.category.ia.homepage" />
             <!-- Add a summary text when the setting is displayed -->
              <meta-data android:name="com.android.settings.summary"
                     android:resource="@string/display_dashboard_summary"/>
             </activity>

No momento da renderização, o fragmento solicita uma lista de preferências do XML estático e das configurações dinâmicas definidas em AndroidManifest. Independentemente de os PreferenceControllers serem definidos em código Java ou em XML, o DashboardFragment gerencia a lógica de processamento de cada configuração pelo PreferenceController (discutido abaixo). Em seguida, eles são exibidos na interface como uma lista mista.

PreferenceController

Há diferenças entre a implementação de PreferenceController no Android 9 e no Android 8.x, conforme descrito nesta seção.

PreferenceController na versão do Android 9

Um PreferenceController contém toda a lógica para interagir com a preferência, incluindo exibição, atualização, indexação de pesquisa etc.

A interface de PreferenceController é definida como BasePreferenceController. Por exemplo, consulte o código em packages/apps/Settings/src/com/android/settings/core/ BasePreferenceController.java

Há várias subclasses de BasePreferenceController, cada uma associada a um estilo de interface específico que tem suporte do app Configurações por padrão. Por exemplo, TogglePreferenceController tem uma API que mapeia diretamente para como o usuário precisa interagir com uma interface de preferências baseadas em alternância.

BasePreferenceController tem APIs como getAvailabilityStatus(), displayPreference(), handlePreferenceTreeClicked(), etc. A documentação detalhada de cada API está na classe de interface.

Uma restrição à implementação de BasePreferenceController (e suas subclasses, como TogglePreferenceController) é que a assinatura do construtor precisa corresponder a um dos itens abaixo:

public MyController(Context context, String key) {}
public MyController(Context context) {}

Ao instalar uma preferência para o fragmento, o painel fornece um método para anexar um PreferenceController antes do tempo de exibição. No momento da instalação, o controlador é conectado ao fragmento para que todos os eventos relevantes futuros sejam enviados ao controlador.

DashboardFragment mantém uma lista de PreferenceControllers na tela. No onCreate() do fragmento, todos os controladores são invocados para o método getAvailabilityStatus() e, se ele retornar verdadeiro, displayPreference() será invocado para processar a lógica de exibição. getAvailabilityStatus() também é importante para informar ao framework de configurações quais itens estão disponíveis durante a pesquisa.

PreferenceController nas versões do Android 8.x

Um PreferenceController contém toda a lógica para interagir com a preferência, incluindo exibição, atualização, indexação de pesquisa etc.

Correspondendo às interações de preferência, a interface de PreferenceController tem as APIs isAvailable(), displayPreference(), handlePreferenceTreeClicked() etc. A documentação detalhada de cada API pode ser encontrada na classe da interface.

DashboardFragment mantém uma lista de PreferenceControllers na tela. No onCreate() do fragmento, todos os controladores são invocados para o método isAvailable() e, se ele retornar "true", displayPreference() é invocado para processar a lógica de exibição.

Usar o DashboardFragment

Mover uma preferência da página A para B

Se a preferência estiver estaticamente listada no arquivo XML de preferências da página original, siga o procedimento de movimentação Estático abaixo para sua versão do Android. Caso contrário, siga o procedimento de movimentação Dinâmica para sua versão do Android.

Movimento estático no Android 9

Encontre os arquivos XML de preferência para a página original e a página de destino. Você encontra essas informações no método getPreferenceScreenResId() da página.
Remova a preferência do XML da página original.
Adicione a preferência ao XML da página de destino.
Remova o PreferenceController dessa preferência da implementação Java da página original. Normalmente, ele está em createPreferenceControllers(). O controlador pode ser declarado diretamente em XML.
Observação: a preferência pode não ter um PreferenceController.
Instancie o PreferenceController no createPreferenceControllers() da página de destino. Se a PreferenceController estiver definida em XML na página antiga, defina-a em XML para a nova página também.

Movimento dinâmico no Android 9

Descubra qual categoria hospeda a página original e a de destino. Você pode encontrar essas informações em DashboardFragmentRegistry.
Abra o arquivo AndroidManifest.xml que contém a configuração que você precisa mover e encontre a entrada "Atividade" que representa essa configuração.
Defina o valor dos metadados da atividade para com.android.settings.category como a chave de categoria da nova página.

Movimento estático nas versões do Android 8.x

Encontre os arquivos XML de preferências para a página original e a página de destino.

getPreferenceScreenResId()

Remova a preferência no XML da página original.
Adicione a preferência ao XML da página de destino.
Remova o PreferenceController dessa preferência na implementação de Java da página original. Normalmente, está em getPreferenceControllers().

Observação:é possível que a preferência não tenha um PreferenceController.

Instancie o PreferenceController no getPreferenceControllers() da página de destino.

Movimento dinâmico nas versões do Android 8.x

Descubra qual categoria hospeda a página original e a de destino. Você pode encontrar essas informações em DashboardFragmentRegistry.
Abra o arquivo AndroidManifest.xml que contém a configuração que você precisa mover e encontre a entrada "Atividade" que representa essa configuração.
Mude o valor de metadados da atividade para com.android.settings.category e defina o ponto de valor como a chave de categoria da nova página.

Criar uma nova preferência em uma página

Se a preferência estiver listada estaticamente no arquivo XML de preferências da página original, siga o procedimento estático abaixo. Caso contrário, siga o procedimento dinâmico.

Criar uma preferência estática

Encontre os arquivos XML de preferência para a página. Essas informações podem ser encontradas no método getPreferenceScreenResId() da página.
Adicione um novo item de preferência no XML. Verifique se ele tem um android:key exclusivo.
Defina um PreferenceController para essa preferência no método getPreferenceControllers() da página.
- No Android 8.x e, opcionalmente, no Android 9, instancie um PreferenceController para essa preferência no método createPreferenceControllers() da página.
  Se essa preferência já existia em outros lugares, é possível que já exista um PreferenceController para ela. É possível reutilizar o PreferenceController sem criar um novo.
- A partir do Android 9, você pode declarar o PreferenceController em XML ao lado da preferência. Por exemplo:
```
<Preference
        android:key="reset_dashboard"
        android:title="@string/reset_dashboard_title"
        settings:controller="com.android.settings.system.ResetPreferenceController"/>
```

Criar uma preferência dinâmica

Descubra qual categoria hospeda a página original e a de destino. Você pode encontrar essas informações em DashboardFragmentRegistry.
Criar uma nova atividade em AndroidManifest
Adicione os metadados necessários à nova atividade para definir a configuração. Defina o valor dos metadados de com.android.settings.category com o mesmo valor definido na etapa 1.

Criar nova página

Crie um novo fragmento, herdado de DashboardFragment.
Defina a categoria no DashboardFragmentRegistry.
Observação:esta etapa é opcional. Se você não precisar de preferências dinâmicas nessa página, não vai ser preciso fornecer uma chave de categoria.
Siga as etapas para adicionar as configurações necessárias a esta página. Para mais informações, consulte a seção Implementação.

Validação

Execute os testes Robolectric nas Configurações. Todos os testes novos e atuais precisam ser aprovados.
Crie e instale as Configurações e abra manualmente a página que está sendo modificada. A página será atualizada imediatamente.