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
PreferenceController
s 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
PreferenceController
s 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.
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 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á emcreatePreferenceControllers()
. O controlador pode ser declarado diretamente em XML.Observação: a preferência pode não ter um
PreferenceController
. - Instancie o
PreferenceController
nocreatePreferenceControllers()
da página de destino. Se aPreferenceController
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. Você encontra essas informações no método
- 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á emgetPreferenceControllers()
. - Instancie o
PreferenceController
nogetPreferenceControllers()
da página de destino.
getPreferenceScreenResId()
da página.
Observação:é possível que a preferência não tenha um
PreferenceController
.
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étodogetPreferenceControllers()
da página.- No Android 8.x e, opcionalmente, no Android 9, instancie um
PreferenceController
para essa preferência no métodocreatePreferenceControllers()
da página.Se essa preferência já existia em outros lugares, é possível que já exista um
PreferenceController
para ela. É possível reutilizar oPreferenceController
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"/>
- No Android 8.x e, opcionalmente, no Android 9, instancie um
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.