Ao desenvolver para HarmonyOS, é comum precisar verificar o estado atual de uma janela — por exemplo, se ela está em tela cheia, se o modo de privacidade está ativado ou qual é o nível de brilho da tela. Embora o objeto window.Window fornecido pela API nativa do sistema ofereça acesso a essas informações, o caminho para consultá-las pode ser um pouco detalhado. Uma abordagem mais simplificada para essas operações é utilizar uma classe utilitária de janela.

O que é o WindowUtil?

O WindowUtil atua como uma camada de abstração sobre o módulo window do kit ArkUI nativo do HarmonyOS. Ele foi projetado para centralizar e simplificar o acesso a diversas funcionalidades relacionadas à gestão de janelas, transformando operações comuns em métodos estáticos e diretos. Isso elimina a necessidade de obter repetidamente uma instância do objeto Window para cada interação, permitindo chamadas mais limpas como WindowUtil.algumMetodo().

Consultando Todas as Propriedades com getWindowProperties()

A funcionalidade básica para obter uma visão abrangente do estado de uma janela é o método getWindowProperties(). Ele retorna um objeto que encapsula todas as propriedades relevantes da janela em um único conjunto.

try {
  const propriedadesAtuais = WindowUtil.getWindowProperties();
  console.log(`Tipo da Janela: ${propriedadesAtuais.type}`);
  console.log(`Modo Tela Cheia: ${propriedadesAtuais.isFullScreen}`);
  console.log(`Modo de Privacidade Ativo: ${propriedadesAtuais.isPrivacyMode}`);
  console.log(`Brilho da Tela: ${propriedadesAtuais.brightness}`);
  console.log(`É Focável: ${propriedadesAtuais.focusable}`);
  console.log(`É Tocável: ${propriedadesAtuais.touchable}`);
} catch (erro) {
  console.error(`Erro ao obter propriedades da janela: ${erro.message}`);
}

Após a execução, o console pode exibir uma saída similar a esta:

Tipo da Janela: 1
Modo Tela Cheia: false
Modo de Privacidade Ativo: false
Brilho da Tela: -1
É Focável: true
É Tocável: true

Descrição dos Campos Retornados:

• type: Indica o tipo da janela. Para janelas de aplicativos principais, o valor típico é 1.
• isFullScreen: Booleano que indica se a janela está em modo de tela cheia.
• isPrivacyMode: Booleano que indica se o modo de privacidade está ativo, o que geralmente impede capturas de tela.
• brightness: Nível de brilho da tela. Um valor de -1 geralmente significa que o brilho segue as configurações do sistema.
• focusable: Booleano que indica se a janela pode receber foco.
• touchable: Booleano que indica se a janela pode ser interagida via toque.

Este método é ideal quando a aplicação precisa ler várias propriedades da janela simultaneamente, como ao inicializar um componente que depende do estado atual da interface.

Métodos de Verificação de Estado Simplificados

Para cenários onde apenas uma propriedade específica é necessária, o WindowUtil oferece uma série de métodos isXxx() mais diretos, evitando a necessidade de buscar o objeto completo de propriedades.

// Verifica se a janela está em tela cheia
const verificarTelaCheia = () => {
  try {
    const estaEmTelaCheia = WindowUtil.isFullScreen();
    console.log(`Janela em tela cheia? ${estaEmTelaCheia}`);
  } catch (erro) {
    console.error(`Erro ao verificar tela cheia: ${erro.message}`);
  }
};
verificarTelaCheia();

// Verifica se o modo de privacidade está ativo
const verificarModoPrivacidade = () => {
  try {
    const modoPrivacidade = WindowUtil.isPrivacyMode();
    console.log(`Modo de privacidade ativado? ${modoPrivacidade}`);
  } catch (erro) {
    console.error(`Erro ao verificar modo privacidade: ${erro.message}`);
  }
};
verificarModoPrivacidade();

// Verifica se a tela está ligada (não em modo de suspensão)
const verificarTelaLigada = () => {
  try {
    const telaAtiva = WindowUtil.isKeepScreenOn();
    console.log(`Manter tela ligada? ${telaAtiva}`);
  } catch (erro) {
    console.error(`Erro ao verificar tela ligada: ${erro.message}`);
  }
};
verificarTelaLigada();

// Verifica se a janela pode receber foco
const verificarFocavel = () => {
  try {
    const podeFocar = WindowUtil.isFocusable();
    console.log(`Janela é focável? ${podeFocar}`);
  } catch (erro) {
    console.error(`Erro ao verificar focabilidade: ${erro.message}`);
  }
};
verificarFocavel();

Eses métodos são síncronos, retornando o resultado imediatamente sem a necessidade de await ou callbacks.

Verificação Assíncrona de Gama de Cores (Wide Gamut)

O método isWindowSupportWideGamut() é uma exceção por ser assíncrono e, portanto, requer tratamento com .then() ou async/await.

const verificarSuporteGamaCores = async () => {
  try {
    const suportaGamaAmpla = await WindowUtil.isWindowSupportWideGamut();
    console.log(`Suporte a Wide Color Gamut: ${suportaGamaAmpla}`);
  } catch (erro) {
    console.error(`Falha ao verificar suporte a gama de cores: ${erro.message}`);
  }
};
verificarSuporteGamaCores();

O suporte a uma gama de cores mais ampla (como o espaço de cor P3) é uma característica de telas mais avançadas, sendo particularmente útil para aplicações que lidam com edição de imagem ou reprodução de vídeo de alta qualidade.

Obtendo Tipo e Estado da Janela

Além das propriedades booleanas, é possível consultar o tipo numérico e o estado atual da janela.

// Consulta o tipo da janela (valor enumerado)
const obterTipoJanela = () => {
  try {
    const tipoNumerico = WindowUtil.getWindowType();
    console.log(`Tipo da Janela (numérico): ${tipoNumerico}`);
  } catch (erro) {
    console.error(`Erro ao obter tipo da janela: ${erro.message}`);
  }
};
obterTipoJanela();

// Consulta o estado atual da janela (normal, minimizada, maximizada, etc.)
const obterEstadoJanela = () => {
  try {
    const estadoAtual = WindowUtil.getWindowStatus();
    console.log(`Estado da Janela: ${estadoAtual}`);
  } catch (erro) {
    console.error(`Erro ao obter estado da janela: ${erro.message}`);
  }
};
obterEstadoJanela();

getWindowType() retorna um valor da enumeração window.WindowType (TYPE_APP é geralmente 1 para janelas de aplicativos). getWindowStatus() retorna um valor de window.WindowStatusType, como FULL_SCREEN ou FLOATING, útil para aplicações que se adaptam a diferentes estados de janela, como em cenários de tela dividida.

Acessando Instâncias de Janela: findWindow e getLastWindow

Para operações de nível mais baixo que exigem o objeto de janela em si, existem métodos para localizar ou obter a instância da janela.

// Busca uma janela pelo nome da sua habilidade
const buscarJanelaPorNome = (nomeComponente: string) => {
  const instanciaJanela = WindowUtil.findWindow(nomeComponente);
  console.log(`Janela '${nomeComponente}' encontrada? ${!!instanciaJanela}`);
};
buscarJanelaPorNome('MinhaHabilidadePrincipal'); // Exemplo de uso

// Obtém a instância da janela mais ao topo no contexto atual (assíncrono)
const obterJanelaSuperior = async () => {
  try {
    const janelaNoTopo = await WindowUtil.getLastWindow();
    console.log(`Janela superior obtida: ${!!janelaNoTopo}`);
  } catch (erro) {
    console.error(`Erro ao obter janela superior: ${erro.message}`);
  }
};
obterJanelaSuperior();

findWindow retorna um objeto do tipo window.Window | undefined, enquanto getLastWindow é um método assíncrono que entrega a instância da janela mais visível no momento.

Importância do Tratamento de Erros

É crucial notar que todos os exemplos de métodos síncronos foram envolvidos em blocos try/catch. Esta prática não é um excesso, pois se o WindowUtil não tiver sido devidamente inicializado ou se a janela correspondente já tiver sido destruída, essas chamadas podem lançar exceções. Recomenda-se sempre encapsular as chamadas a esses utilitários em blocos de tratamento de erros para garantir a robustez da aplicação e evitar interrupções inesperadas.