Componentes de estilo com temas modernos

Os componentes de código devem ter aparência e comportamento consistentes com os aplicativos que os hospedam. Power Apps usa tokens de tema fluente para fornecer aos autores de componentes as cores atuais do aplicativo, tipografia, espaçamento e outros valores de estilo. Em aplicativos baseados em modelo, Power Apps ajusta os tokens Fluent de espaçamento com suporte para refletir a densidade de exibição atual. Ao consumir esses tokens em vez de usar valores de estilo fixos, os componentes podem responder ao tema do aplicativo atual e, quando disponível, à densidade de exibição.

O tema moderno está disponível em aplicativos de tela por meio do recurso de controles e temas modernos e em aplicativos baseados em modelos por meio da aparência moderna e atualizada. A densidade de exibição está disponível apenas em aplicativos baseados em modelo com a atualização do cabeçalho e da navegação habilitada.

O tema da plataforma usa tokens do Fluent UI v9. Os componentes podem herdar esses tokens por meio do provedor Fluent da plataforma ou consumi-los por meio da API de temas das seguintes maneiras:

Controles do Fluent UI v9

Encapsular controles do Fluent UI v9 em um componente é a maneira mais fácil de utilizar a tematização moderna, já que o tema moderno é aplicado automaticamente a esses controles. O único pré-requisito é garantir que o componente adicione uma dependência nas bibliotecas de plataforma e controles react , conforme mostrado na seção a seguir. Essa abordagem permite que seu componente use as mesmas bibliotecas React e Fluent que a plataforma e, portanto, compartilhe o mesmo contexto React que passa os tokens de tema para o componente. Usar as bibliotecas React e Fluent da plataforma é a abordagem recomendada para o melhor desempenho e experiência de temas.

<resources>
  <code path="index.ts" order="1"/>
  <!-- Dependency on React controls & platform libraries -->
  <platform-library name="React" version="16.14.0" />
  <platform-library name="Fluent" version="9.46.2" />
</resources>

Controles do Fluent UI v8

O Fluent oferece um caminho de migração para aplicar estruturas de tema da v9 quando você usa controles do Fluent UI v8 no seu componente. Use a createV8Theme função incluída no pacote de migração v8 para v9 do Fluent para criar um tema v8 com base em tokens de tema v9, conforme mostrado no exemplo a seguir:

const theme = createV8Theme(
  context.fluentDesignLanguage.brand,
  context.fluentDesignLanguage.theme
);
return <ThemeProvider theme={theme}></ThemeProvider>;

Controles que não são do Fluent UI

Se o seu componente não usar o Fluent UI, você poderá depender diretamente dos tokens de tema v9 disponíveis por meio do parâmetro de contexto fluentDesignLanguage. Use este parâmetro para obter acesso a todos os tokens do tema, para que possa fazer referência a qualquer aspecto do tema para definir seu próprio estilo.

<span style={{ fontSize: context.fluentDesignLanguage.theme.fontSizeBase300 }}>
  {"Stylizing HTML with platform provided theme."}
</span>

Provedores de temas personalizados

Quando o componente exigir um estilo diferente do tema atual do aplicativo, crie seu próprio FluentProvider e passe seu próprio conjunto de tokens de tema para ser usado pelo componente.

<FluentProvider theme={context.fluentDesignLanguage.tokenTheme}>
  {/* your control */}
</FluentProvider>

Fazer com que o espaçamento responda à densidade de exibição

Em aplicativos controlados por modelos, a densidade de exibição ajusta o espaçamento para mostrar mais ou menos informações na tela. Os componentes de código funcionam por meio da API de temas modernos existente. Quando a densidade de exibição está disponível, a plataforma fornece os valores de espaçamento resolvidos no tema Fluent. O componente não precisa ler a configuração do aplicativo ou a preferência pessoal do usuário.

Use os seguintes tokens para espaçamento de layout personalizado que responde à densidade de exibição:

Token Exemplos de uso
spacingVerticalS Espaçamento interno vertical em torno de um campo, linha de detalhes ou elemento similarmente compacto
spacingVerticalM Separação em torno de um título de seção ou um espaçamento vertical médio
spacingVerticalL Espaçamento em torno de um card ou outro grande espaçamento vertical
spacingHorizontalL Preenchimento interno ao redor de um cartão ou outro espaçamento horizontal amplo

Somente esses tokens de espaçamento atualmente recebem ajustes de densidade de exibição. Outros tokens de espaçamento, tipografia, dimensões de controle, ícones e tamanhos de alvo de interação não são alterados automaticamente.

Se o componente usar o Fluent UI v9 e herdar o provedor Fluent da plataforma, faça referência aos tokens em seus estilos:

import { makeStyles, tokens } from "@fluentui/react-components";

const useStyles = makeStyles({
  card: {
    paddingBlock: tokens.spacingVerticalL,
    paddingInline: tokens.spacingHorizontalL,
  },
  row: {
    paddingBlock: tokens.spacingVerticalS,
    rowGap: tokens.spacingVerticalM,
  },
});

Se o componente possui seus estilos ou usa elementos não Fluent, use os valores correspondentes do tema do token atual:

const tokenTheme = context.fluentDesignLanguage.tokenTheme;

const rowStyle = {
  paddingBlock: tokenTheme.spacingVerticalS,
  paddingInline: tokenTheme.spacingHorizontalL,
  rowGap: tokenTheme.spacingVerticalM,
};

Não copie os valores de pixel para um nível de densidade ou infera a densidade selecionada dos valores de token. A plataforma resolve as configurações do aplicativo, as preferências pessoais e a disponibilidade de densidade antes de fornecer o tema.

Escolha tokens de acordo com sua função de layout e compare seus valores normais com o layout atual. Substituir um valor fixo por um token que tenha um valor normal diferente pode alterar involuntariamente o componente na densidade confortável padrão.

Processe o tema atual sempre que o método updateView do componente for executado. Não mantenha o tema inicial ou os valores de espaçamento durante todo o ciclo de vida do componente. Valide o componente na densidade Confortável, Aconchegante e Compacta , inclusive após as alterações de tema ou densidade.

Note

A densidade de exibição ajusta os valores de espaçamento com suporte; não disponibiliza Confortável, Aconchegante ou Compacto como um valor público para componentes no código. Use os valores de token fornecidos diretamente em vez de inferir um nível de densidade e aplicar estilos condicionalmente. Componentes com alturas fixas das linhas, layouts virtualizados ou outro dimensionamento específico do componente podem exigir trabalho adicional de design além de consumir tokens de espaçamento.

Controles de exemplo

Para obter exemplos das abordagens modernas de temas, consulte o Controle da API de Temas Modernos.

perguntas frequentes

Esta seção contém perguntas frequentes. Se você tiver alguma dúvida sobre esse recurso, use o botão Feedback de Esta página, na parte inferior da página, para criar um problema no GitHub.

Q: Meu controle usa o Fluent UI v9 e tem uma dependência das bibliotecas da plataforma, mas não quero usar a tematização moderna. Como posso desabilitá-lo para o meu componente?

R: Você pode fazer isso de duas maneiras diferentes:

  1. Você pode criar seu próprio nível de componente FluentProvider

    <FluentProvider theme={customFluentV9Theme}>
  {/* your control */}
</FluentProvider>

  2. Você pode encapsular seu controle dentro IdPrefixContext.Provider e definir seu próprio idPrefix valor. Isso impede que seu componente receba tokens de tema da plataforma.

    <IdPrefixProvider value="custom-control-prefix">
  <Label weight="semibold">This label is not getting Modern Theming</Label>
</IdPrefixProvider>

P: Alguns dos meus controles v9 do Fluent UI não estão recebendo estilos

A: Os controles do Fluent v9 que dependem do React Portal precisam ser encapsulados novamente no provedor de tema para garantir que os estilos sejam aplicados corretamente. Você pode usar FluentProvider.

P: Como posso verificar se o tema moderno está habilitado

A: Você pode verificar se os tokens estão disponíveis: context.fluentDesignLanguage?.tokenTheme. Ou em aplicativos controlados por modelo, você pode verificar as configurações do aplicativo: context.appSettings.getIsFluentThemingEnabled().

Temas (referência da API da estrutura de componentes do Power Apps)
Controle da API moderna de tematização
Usar temas modernos em aplicativos de tela (versão prévia)

  • Última atualização em