Barra de título personalizada (10.1.68) - Mobile Platform as a Service: Central de Documentação do Alibaba Cloud

O contêiner Nebula permite personalizar a barra de navegação. Você pode definir o estilo da barra, como a posição do título e o formato do botão Voltar. Este tópico descreve como personalizar uma barra de navegação na baseline 10.1.68.

Pré-requisitos

Antes de ler este guia, observe os seguintes pontos importantes:

Para desenvolver uma barra de navegação compartilhada entre Mini Programs e páginas HTML5, considere o uso das barras tanto em páginas HTML5 quanto em Mini Programs. Ignore esta regra se pretender usar a barra de navegação apenas em Mini Programs ou apenas em páginas HTML5.
A barra de navegação personalizada deve seguir o processo padrão de chamada de operações de API no contêiner. Leia atentamente este documento e desenvolva a barra de navegação personalizada conforme necessário.
Por padrão, os Mini Programs utilizam a barra de navegação integrada. Para usar uma barra personalizada em Mini Programs, consulte Configurar o contêiner HTML5.
A cor da barra de navegação pode ser definida dinamicamente. Para garantir a melhor experiência, prepare dois conjuntos de configurações de tema e alterne entre eles conforme o cenário.

Procedimento

Herde a classe abstrata AbsTitleView e implemente uma barra de navegação personalizada.

Implemente H5ViewProvider. No método createTitleView, crie e retorne uma instância da barra de navegação personalizada.

public class H5ViewProviderImpl implements H5ViewProvider {
     @Override
     public H5TitleView createTitleView(Context context) {
         return new NewH5TitleViewImpl(context);
     }

     @Override
     public H5NavMenuView createNavMenu() {
         return null;
     }

     @Override
     public H5PullHeaderView createPullHeaderView(Context context, ViewGroup viewGroup) {
         return null;
     }

     @Override
     public H5WebContentView createWebContentView(Context context) {
         return null;
     }
 }

Defina H5ViewProvider no contêiner em cenários específicos, como na inicialização do aplicativo.
```
MPNebula.setCustomViewProvider(new H5ViewProviderImpl());
```

Caso seu projeto utilize a arquitetura Portal e Bundle, configure os parâmetros adicionais abaixo.

H5Utils.setProvider(H5ReplaceResourceProvider.class.getName(), new H5ReplaceResourceProvider() {
     @Override
     public String getReplaceResourcesBundleName() {
         return BuildConfig.BUNDLE_NAME;
     }
 });

Mais informações

Cor de fundo

/**
     * Return the value of the background color of the navigation bar.
     * @return
     */
    public abstract int getBackgroundColor();

    /**
     * Set the transparency of the navigation bar.
     * @param alpha
     */
    public abstract void setBackgroundAlphaValue(int alpha);

    /**
     * Sets the background color of the navigation bar without using Alpha values.
     * @param color
     */
    public abstract void setBackgroundColor(int color);

    /**
     * Resets the navigation bar.
     */
    public abstract void resetTitle();

A operação resetTitle é acionada quando a JSAPI setTitleColor é invocada em uma página em primeiro plano. Nesse caso, recomenda-se redefinir os elementos de exibição para seus padrões. Esses elementos incluem o fundo da barra de navegação e os valores de cor de outros componentes mencionados posteriormente neste tópico.

Título

Subtítulos são suportados apenas em cenários de páginas HTML5. Se o aplicativo não necessitar de subtítulo, ignore sua implementação.

Para permitir que uma página HTML5 escute eventos de toque na barra de título, ative a barra de navegação para chamar o método invokeTitleClickEvent nos cenários especificados. Já para ative a escuta de eventos de toque na barra de subtítulo, configure a barra para invocar o método invokeSubTitleClickEvent.

/**
     * Return the text of the main title.
     * @return
     */
    public abstract String getTitle();

    /**
     * Set the text of the main title.
     * @param title
     */
    public abstract void setTitle(String title);

    /**
     * Set the text of the subtitle.
     * @param subTitle
     */
    public abstract void setSubTitle(String subTitle);

    /**
     * Return the view of the main title.
     * @return
     */
    public abstract TextView getMainTitleView();

    /**
     * Return the view of the subtitle.
     * @return
     */
    public abstract TextView getSubTitleView();

Seção de controle à esquerda

/**
     * Set whether to show the Close button.
     * @param visible
     */
    public abstract void showCloseButton(boolean visible);

    /**
     * Set whether to show the Back button.
     * @param visible
     */
    public abstract void showBackButton(boolean visible);

    /**
     * Set whether to show the Home button.
     * @param visible
     */
    public abstract void showBackHome(boolean visible);

    /**
     * Set whether to show the loading progress icon in the title bar.
     * @param visible
     */
    public abstract void showTitleLoading(boolean visible);

Botão Fechar

Conforme destacado no quadro vermelho da figura anterior, o botão Fechar aparece somente em páginas HTML5. Quando houver mais de uma página online no histórico do navegador, o contêiner chama o método showCloseButton para controlar a visibilidade desse botão. Ao tocar no botão Fechar, chame o método invokePageCloseEvent para cumprir a especificação de comportamento do contêiner.

Botão Voltar

O botão Voltar, indicado pelo quadro vermelho acima, é um controle cuja implementação é obrigatória em qualquer barra de navegação personalizada. O contêiner utiliza o método showBackButton para gerenciar sua exibição. Sempre que o usuário tocar nesse botão, invoque o método invokePageBackEvent para respeitar as normas de comportamento do contêiner.

Botão Início

Este botão é exclusivo dos Mini Programs. Caso o usuário seja redirecionado para uma página que não seja a inicial do Mini Program, o contêiner aciona o método showBackHome para determinar se o botão deve aparecer. Ao detectar o toque no botão Início, execute o método invokeHomeClickEvent para manter a conformidade com o comportamento esperado do contêiner.

Ícone de progresso de carregamento

Sempre que uma página HTML5 ou um Mini Program solicitar a animação de carregamento na barra de navegação via API, o contêiner usará o método showTitleLoading para alternar a visibilidade do ícone de progresso.

Seção de controle à direita

Também conhecida como seção OptionMenu, esta área serve principalmente para oferecer operações adicionais aos usuários.

No contêiner HTML5:
Em Mini Programs:

Como ilustrado nas figuras anteriores, reserve duas áreas de visualização para a seção OptionMenu. O contêiner gerencia essas áreas por meio de índices, organizados da direita para a esquerda, começando em 0.

public abstract void showOptionMenu(boolean visible);

    public abstract View getOptionMenuContainer(int index);

    public abstract void setOptionMenu(boolean reset, boolean override, boolean isTinyApp, List<MenuData> menus);

O contêiner invoca o método showOptionMenu para definir a visibilidade da seção OptionMenu. Em certas situações, ele precisa obter a visualização dessa seção para executar operações específicas; portanto, implemente corretamente o método getOptionMenuContainer.

Para implementar o método setOptionMenu, consulte os parâmetros de solicitação em Definir botões superiores direitos. O parâmetro icontype refere-se a um estilo de botão integrado, disponível apenas para páginas HTML5. Se o seu cenário não envolver páginas HTML5, ignore esse parâmetro; caso contrário, configure os botões para os diferentes estilos. Assim como icontype, o parâmetro redDot também é opcional.

Para que uma página HTML5 ou um Mini Program detecte toques nos botões superiores direitos, chame o método invokeOptionClickEvent.

Atente-se às seguintes configurações específicas para Mini Programs:

Para diferenciar páginas HTML5 de Mini Programs, defina o parâmetro isTinyApp como true no método setOptionMenu.
Ao configurar múltiplos botões, comece sempre pelo segundo botão a partir da direita.

Seção de controle superior direita em Mini Programs

Em Mini Programs, a implementação da seção direita exige passos específicos:

Utilize a classe abstrata legada AbsTinyOptionMenuView para criar a seção de controle personalizada.
Configure TinyOptionMenuViewProvider no contêiner durante eventos específicos, como a inicialização do aplicativo.

H5Utils.setProvider(TinyOptionMenuViewProvider.class.getName(), new TinyOptionMenuViewProvider() {
    @Override
    public AbsTinyOptionMenuView createView(Context context) {
        return new TinyOptionMenuView(context);
    }
});

Implemente e configure as visualizações dos botões Mais e Fechar seguindo as especificações do contêiner.

public abstract void setOptionMenuOnClickListener(View.OnClickListener listener);

    public abstract void setCloseButtonOnClickListener(View.OnClickListener listener);

    public abstract void setCloseButtonOnLongClickListener(View.OnLongClickListener listener);

    public abstract void onStateChanged(TinyAppActionState currentState);

    public abstract View getView();

O contêiner usa os três primeiros métodos do código acima para estabelecer callbacks de resposta adequados. Configure esses callbacks na visualização correspondente.

O método onStateChanged é invocado em cenários de LBS (serviço baseado em localização) e Bluetooth. Por exemplo, enquanto um Mini Program utiliza recursos de geolocalização, o contêiner aciona este método para que você possa responder ao callback. A imagem abaixo ilustra o estilo resultante.

O código de exemplo a seguir serve como referência.

public class TinyOptionMenuView extends AbsTinyOptionMenuView {

    private View container;

    private ImageView ivMore;

    private View ivClose;

    private Context context;

    public TinyOptionMenuView(Context context) {
        this.context = context;
        ViewGroup parent = null;
        if (context instanceof Activity) {
            parent = (ViewGroup) ((Activity) context).findViewById(android.R.id.content);
        }
        container = LayoutInflater.from(context).inflate(R.layout.layout_tiny_right, parent, false);
        ivClose = container.findViewById(R.id.close);
        ivMore = (ImageView) container.findViewById(R.id.more);

    }

    @Override
    public View getView() {
        return container;
    }

    @Override
    public void setOptionMenuOnClickListener(View.OnClickListener onClickListener) {
        ivMore.setOnClickListener(onClickListener);
    }

    @Override
    public void setCloseButtonOnClickListener(View.OnClickListener onClickListener) {
        ivClose.setOnClickListener(onClickListener);
    }

    @Override
    public void setCloseButtonOnLongClickListener(View.OnLongClickListener onLongClickListener) {
        ivClose.setOnLongClickListener(onLongClickListener);
    }

    @Override
    public void onStateChanged(TinyAppActionState state) {
        if (state == null) {
            ivMore.setImageDrawable(context.getResources().getDrawable(R.drawable.icon_more));
        } else if (state.getAction().equals(TinyAppActionState.ACTION_LOCATION)) {
            ivMore.setImageDrawable(context.getResources().getDrawable(R.drawable.icon_miniprogram_location));
        }
    }
}

Alterações de tema

Diferentes Mini Programs ou aplicativos HTML5 podem adotar cores de fundo distintas em suas barras de navegação. Para aprimorar a experiência do usuário, ajuste também outros elementos da barra, como a seção de controle superior direita, em resposta a essas mudanças de cor.

Na extensão da barra de navegação, a seção de controle superior direita e a própria barra são componentes separados. Por isso, existem APIs dedicadas para sincronizar a seção de controle com as alterações da barra.

A classe AbsTinyOptionMenuView oferece o método onTitleChanged, permitindo usar override para reagir às modificações na barra de navegação. Quando chamado, esse método recebe um objeto H5TitleView, fornecendo acesso a informações como a cor de fundo. Além disso, a classe disponibiliza o método getTitleBar para recuperação direta dos objetos da barra. Alternativamente, converta H5TitleView para um objeto de barra de navegação customizado, já que a classe AbsTitleView implementa H5TitleView. Isso possibilita acessar dados mais detalhados sobre a barra.
```
 protected void onTitleChange(H5TitleView title)
```

Chame proativamente o método notifyTitleBarChanged da classe AbsTitleView para garantir a execução da operação onTitleChange, por exemplo, ao definir a cor de fundo da barra. Consulte o exemplo de código abaixo.

 package com.mpaas.demo.nebula;

  public class NewH5TitleViewImpl extends AbsTitleView {

      @Override
      public void setBackgroundAlphaValue(int i) {
          content.getContentBgView().setAlpha(i);
          notifyTitleBarChanged();
      }

      @Override
      public void setBackgroundColor(int i) {
          content.getContentBgView().setColor(i);
          notifyTitleBarChanged();
      }

      @Override
      public void resetTitle() {
          content.getContentBgView().setColor(context.getResources().getColor(R.color.h5_default_titlebar_color));
          notifyTitleBarChanged();
      }
  }

No exemplo anterior, note que os objetos da subclasse AbsTinyOptionMenuView podem não estar totalmente inicializados quando notifyTitleBarChange for chamado. Portanto, recomenda-se sobrescrever o método setH5Page para obter as informações da barra e identificar o tema atual. Veja o código de referência a seguir.

 public class TinyOptionMenuView extends AbsTinyOptionMenuView {

      @Override
      public void setH5Page(H5Page h5Page) {
          super.setH5Page(h5Page);
          // title becomes available from here.
          if (getTitleBar().getBackgroundColor() == -1) {
              bgView.setBackgroundColor(Color.RED);
          }
      }
  }