Crie componentes personalizados para reutilizar em páginas com o construtor de componentes

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 11 min. de leitura

    • Reutilize componentes personalizados em experiências e páginas em Construtor de IU.

    Crie componentes personalizados em Construtor de IUIU de criação de componente de. A IU de criação de componente compartilha muitas semelhanças com a criação de páginas e permite configurar componentes da mesma maneira que você faria ao configurar uma página no Construtor de IU.

    O poder dos componentes personalizados

    A criação de componentes personalizados melhora a eficiência, a consistência e a capacidade de manutenção em toda a sua experiência. Ao criar elementos de IU reutilizáveis, você evita duplicar configurações, garante uma aparência uniforme e facilita o gerenciamento de atualizações ou mudanças de design. Os componentes personalizados também simplificam layouts complexos, oferecem suporte a configurações flexíveis e permitem testes e depuração mais fáceis. Eles também são úteis em ambientes de equipe, onde os componentes compartilhados ajudam a simplificar a colaboração e manter a experiência do usuário consistente em escala.

    Os componentes personalizados são especialmente valiosos ao projetar páginas para diferentes tipos de usuário na sua experiência. Por exemplo, você pode criar um componente reutilizável que inclua uma lista e uma visualização de dados e, em seguida, personalizar seu conteúdo ou comportamento com base no grupo de usuários, permitindo que você mantenha um layout consistente enquanto fornece informações específicas da função.

    Os componentes editados no Construtor de componentes serão atualizados automaticamente em todas as páginas em que forem usados.

    Importante:
    Os componentes personalizados criados em uma instância permanecem disponíveis somente nessa instância até que sejam migrados para outras instâncias usando conjuntos de atualizações ou instalações de aplicações.

    Coleções de páginas ou componentes personalizados

    Para criar experiências digitais eficientes e escaláveis, é importante reutilizar elementos sempre que possível. Duas maneiras de fazer isso são por meio de componentes personalizados e coleções de páginas. Cada serve a um propósito distinto, dependendo do escopo de reutilização de que você precisa.

    Componentes personalizados
    Use componentes personalizados quando quiser replicar uma parte específica de uma página, como um título, lista, formulário ou botões em várias páginas.
    Você deseja aplicar um tema ou configuração consistente a um componente ou grupo de componentes.
    Você está criando páginas para serem modulares ou flexíveis, onde partes de uma página podem mudar, mas os componentes compartilhados permanecem consistentes.
    Você deseja gerenciar mudanças em um só lugar e atualizá-las em todos os lugares em que o componente é usado.
    Várias equipes estão trabalhando simultaneamente em diferentes seções da mesma página.
    Coleções de páginas
    Você deseja reutilizar um layout de página inteiro e uma configuração em várias páginas ou experiências.
    Você deve criar uma variação de páginas completas para diferentes usuários ou fluxos de trabalho.

    Você deseja usar um conjunto de guias em várias páginas ou experiências.

    IU do componente personalizado

    Você pode acessar o construtor de componentes em Construtor de IUselecionando Criar no cabeçalho ou Componente lado a lado no Construtor de IUpágina inicial.

    Figura 1. Página inicial do Construtor de IU
    Página inicial do Construtor de IU com setas apontando os botões Criar componente.
    Figura 2. IU do Construtor de componentes
    Página inicial do construtor de componentes.

    Componentes criados com Construtor de IUpode ser encontrado na caixa de ferramentas ao adicionar um componente a uma página e na lista de componentes na página inicial de Construtor de IU. Você pode atualizar ou modificar componentes personalizados localizando-os na lista de componentes na página inicial do Construtor de IU.

    Figura 3. Valores de teste no Construtor de componentes
    O modal de texto alternativo é exibido quando os valores de teste são selecionados.

    Use valores de teste no construtor de componentes para fornecer valores simulados para parâmetros de URL obrigatórios e opcionais ao criar um componente personalizado. Os valores de teste ajudam a validar como um componente agirá quando adicionado a uma página, garantindo que as vinculações e os recursos de dados estejam funcionando corretamente. Para obter mais informações sobre valores de teste, consulte, Testar valores em uma página.

    Figura 4. Lista de componentes
    Página inicial do Construtor de IU que exibe a guia Componentes.

    Você pode duplicar rapidamente um componente personalizado na tela de configurações do componente selecionando Duplicado , que cria uma cópia exata do componente para reutilização ou modificação.

    Figura 5. Configurações de componente personalizadas
    Tela de configurações do componente com uma seta exibindo a opção Duplicar.

    Construtor de componentes versus Desenvolvimento de componente da NOW CLI

    Há duas maneiras de criar componentes para Construtor de IU. O primeiro é usar o componente low-code no Construtor de IU, que oferece uma interface de arrastar e soltar para criar componentes personalizados. O segundo está usando Ferramentas do desenvolvedor do NOW CLI para criar componentes por meio de código. Ambos os métodos produzem componentes que podem ser adicionados à caixa de ferramentas do UIB e reutilizados em todas as experiências. Tenha em mente que as mudanças nos componentes incluídos podem afetar ambos os tipos.

    Embora ambas as ferramentas criem componentes para Construtor de IU, há diferenças importantes a serem consideradas.

    Construtor de componentes em Construtor de IU:
    • Componentes criados dentro Construtor de IUpode referenciar controladores e recursos de dados.
    • Cria "Componentes do macroponent", que são armazenados na tabela sys_ux_macroponent.
    • O Construtor de componentes é ideal para usuários que preferem uma interface visual de arrastar e soltar para criar componentes.
    • Excelente para criar rapidamente componentes simples a moderadamente complexos.
    Componentes da NOW CLI:
    • Destinado a desenvolvedores que precisam escrever HTML, CSS e JavaScript personalizados.
    • Adequado para a construção de componentes complexos e personalizáveis.
    • Os componentes criados com a NOW CLI são armazenados na tabela sys_uib_toolbox_component.

    Práticas recomendadas

    . Construtor de IUo construtor de componentes personalizados não tem recursos de governança e pode levar à duplicação e inconsistência em sua experiência. As equipes podem criar componentes semelhantes com pequenas variações, resultando em uma IU fragmentada e em uma experiência do usuário confusa. É recomendável que sua equipe conclua auditorias regulares e a comunicação entre equipes para manter o alinhamento e evitar a fragmentação à medida que suas experiências crescem.

    Todos os componentes são projetados para serem seguros para upgrade, desde que sua política de segurança esteja definida como read_only . Isso fornece maior proteção de upgrade para componentes maiores ou parciais de página em comparação com outras unidades implantáveis, como pacotes e modelos de página. No entanto, isso também significa que os componentes prontos para uso (OOTB) podem não ser editáveis.

    Crie componentes para reutilizar em todas as páginas

    Crie componentes personalizados reutilizáveis para usar em experiências e páginas no Construtor de IU.

    Antes de Iniciar

    Função necessária: ui_builder_admin

    Por Que e Quando Desempenhar Esta Tarefa

    Neste exemplo do Construtor de componentes, criaremos um componente de Cronômetro para rastrear o tempo decorrido, que pode ser adicionado a qualquer página. O componente incluirá propriedades personalizáveis que podem ser modificadas depois que for colocado em uma página.

    Procedimento

    1. Navegar até Tudo > Estrutura do Now Experience > Construtor de IU.
    2. Selecione Criar em Construtor de IUpágina inicial.
      Página inicial do Construtor de IU com o botão Criar componente.
    3. Selecione Componente .
    4. No formulário, preencha os campos.
      Figura 6. Criar uma caixa de diálogo de componente
      Crie um formulário de componente.
      Tabela 1. Crie um formulário de componente
      Campo Descrição
      Nome Adicione um nome para rastrear seu componente internamente. O nome do componente aparece na caixa de ferramentas. Para este exemplo, é Cronômetro .
      Categorias Adicione uma categoria ao seu componente para ajudar a encontrá-lo facilmente na caixa de ferramentas. Você pode atualizar a categoria mais tarde nas Configurações. Para este exemplo, selecione Conteúdo .
      Descrição Adicione uma descrição para descrever quando e como usar seu componente.
      Ícone Selecione um ícone para representar o componente na caixa de ferramentas.
    5. Selecione Criar.
      A página é aberta na exibição Construtor de componentes.

      IU de criação de componente personalizada mostrando as barras laterais de conteúdo e configuração.

    6. Selecione uma propriedade de componente personalizada - Adicionar propriedade em Propriedades e política seção.
      Selecione Adicionar propriedade para adicionar conteúdo
      1. Selecione Cadeia de caracteres da lista.
      2. Insira os seguintes valores no painel de configuração.
        Tabela 2. Propriedades do componente
        Campo Valor
        Rótulo da propriedade Origem da imagem SVG
        ID de propriedade SvgImageSource
        Valor padrão animateddino.svg

        IU de criação de componente personalizada com setas apontando para os campos Rótulo de propriedade, ID de propriedade e Origem da imagem SVG no painel de configuração.

      3. Selecione Save (Salvar).
    7. Para configurar o layout do componente personalizado, selecione - Adicionar conteúdo botão.
      1. Selecione Coluna única , em seguida, selecione Adicionar .
      2. Na árvore de conteúdo, em Coluna 1 , selecione - Adicionar conteúdo .
      3. Selecione Contêiner-base do cartão , em seguida, selecione Adicionar .
      4. Na árvore de conteúdo, em Contêiner base do cartão 1 , selecione - Adicionar conteúdo .
      5. Selecione Layouts .
      6. Selecione Flexbox , em seguida, selecione Adicionar .
      7. Selecione Save (Salvar).
        Adicione conteúdo a um contêiner
    8. Selecione um componente de texto estilizado em nosso contêiner Flexbox - Adicionar conteúdo em Contêiner 1 .
      1. Selecione Texto estilizado e selecione Adicionar .
      2. Selecione Cancelar para fechar a janela predefinida.
      3. Selecione Save (Salvar).
        Adicione texto estilizado a um contêiner
    9. Para configurar o componente de texto estilizado, adicionaremos alguns parâmetros de estado do cliente.
      1. Selecione Parâmetros de estado do cliente em Dados e scripts seção.
      2. Em Edite parâmetros de estado do cliente , insira os seguintes valores:
        Tabela 3. Parâmetros de estado do cliente
        Nome Tipo Valor inicial
        startTime Número
        Tempo decorrido Cadeia de caracteres 00:00:00
        intervalo de tempo JSON
        StopwatchExecutando Booliano
        IntervaliId Cadeia de caracteres
      3. Selecione Aplicar.
        Lista de parâmetros de estado do cliente adicionados ao componente personalizado.
      4. Selecione Save (Salvar).
    10. Para configurar o componente de texto estilizado, vincularemos o. Tempo decorrido parâmetro de estado do cliente.
      1. Selecione Texto estilizado 1 componente na árvore de conteúdo.
      2. Selecione o ícone de vinculação ao apontar para Texto campo do componente de texto estilizado.
        Vincule texto estilizado no componente
      3. Selecione estados do cliente .
      4. Clique duas vezes em Tempo decorrido pílula.
        Vincule o parâmetro de tempo decorrido ao texto
      5. Selecione Aplicar.
      6. Selecione Save (Salvar).
    11. Adicione um contêiner Flexbox para segurar os botões.
      1. Selecione E ícone sob o componente de texto estilizado.
        Selecione o sinal de mais no componente de texto
      2. Selecione Layouts .
      3. Selecione Flexbox .
      4. Selecione Adicionar.
    12. Adicione e configure o renderizador em execução do Cronômetro e o botão Iniciar.
      1. Selecione - Adicionar conteúdo no contêiner que você adicionou na etapa anterior e adicione um Renderizador condicional .
      2. Selecione - Adicionar condição na árvore de conteúdo.
      3. Selecione Componente único , em seguida, selecione Próximo .
      4. Selecione Botão icônico , em seguida, selecione Próximo .
      5. Em Editar configurações , insira os seguintes valores:
        • Rótulo do componente: Iniciar
        • ID do componente: start_button
        • Renderizar conteúdo: Sempre
      6. Selecione Aplicar.
      7. Selecione Iniciar na árvore de conteúdo.
      8. Defina as seguintes propriedades no painel de configuração.
        Tabela 4. Propriedades do componente
        Campo Valor
        Ícone cronômetro-preenchimento
        Variante Primário
        Tamanho Grande
        Texto de dica de ferramenta Iniciar
      9. Selecione Save (Salvar).
        IU de criação de componente personalizada com setas apontando para o rótulo do componente e campos de texto de ícone, variante, tamanho e dica de ferramenta no painel de configuração.
    13. Configure o botão de parada para ser exibido enquanto o Cronômetro estiver em execução.
      1. Selecione - Adicionar condição na árvore de conteúdo.
      2. Selecione Contêiner vazio , em seguida, selecione Próximo .
      3. Em Editar configurações , insira os seguintes valores:
        • Rótulo do componente: Em execução
        • ID do componente: running_contêiner
        • Renderizar conteúdo: Quando a condição abaixo for verdadeira
      4. Selecione o ícone de vinculação enquanto aponta para Condição campo.
        Editar modal de configurações onde você seleciona vincular
      5. Selecione estados do cliente , em seguida, clique duas vezes em StopwatchExecutando pílula.
      6. Selecione Aplicar.
      7. Selecione Aplicar.
      8. Selecione - Adicionar conteúdo em Em execução contêiner e adicione um Botão icônico .
      9. Selecione Botão icônico 1 no painel de configuração e insira os seguintes valores:
        • Rótulo do componente: Parar
        • ID do componente: stop_button
      10. Selecione Aplicar.
      11. Defina as seguintes propriedades no painel de configuração.
        Tabela 5. Propriedades do componente
        Campo Valor
        Ícone cronômetro-preenchimento
        Variante Secundário(a)
        Tamanho Grande
        Texto de dica de ferramenta Parar
      12. Selecione Save (Salvar).
        IU de criação de componente personalizada com setas apontando para o rótulo do componente e campos de texto de ícone, variante, tamanho e dica de ferramenta no painel de configuração.
    14. Reordene as condições para que Em execução aparece acima Iniciar .
      1. Selecione Renderizador condicional 1 na árvore de conteúdo.
      2. No painel de configuração, selecione e arraste o ícone de alça de arrastar para mover as condições para a posição.
        Componente do renderizador condicional no painel de configuração com a condição "Em execução" colocada perto da condição "Início".

        As condições são avaliadas em ordem de cima para baixo, portanto Em execução deve aparecer acima Iniciar para que os botões sejam exibidos corretamente.

    15. Selecione a lógica para o componente E ao lado de Scripts do cliente em Dados e scripts seção.
      1. Entrar Iniciar em Nome do script campo.
      2. Cole o script a seguir no campo de script. 
        function handler({ api, helpers }) {
  console.log('Start script running');
 
  if (api.state.stopwatchRunning === undefined) {
    api.setState('stopwatchRunning', false);
    api.setState('elapsedTime', '00:00:00');
    api.setState('startTime', null);
    api.setState('intervalId', null);
  }
 
  let running = api.state.stopwatchRunning;
 
  function pad(n) {
    return n < 10 ? '0' + n : n.toString();
  }
 
  function updateElapsedTime(startTime) {
    if (!running) {
      if (api.state.intervalId) {
        helpers.timing.clearInterval(api.state.intervalId);
        api.setState('intervalId', null);
        console.log('Interval cleared');
      }
      return;
    }
 
    if (!startTime) {
      console.log('No startTime passed to updateElapsedTime, cannot update');
      return;
    }
 
    const now = Date.now();
    const elapsedMs = now - startTime;
 
    const totalSeconds = Math.floor(elapsedMs / 1000);
    const hours = pad(Math.floor(totalSeconds / 3600));
    const minutes = pad(Math.floor((totalSeconds % 3600) / 60));
    const seconds = pad(totalSeconds % 60);
 
    const formattedTime = `${hours}:${minutes}:${seconds}`;
 
    console.log('Setting elapsedTime:', formattedTime);
    api.setState('elapsedTime', formattedTime);
  }
 
  if (!running) {
    const now = Date.now();
 
    api.setState('startTime', now);
    api.setState('elapsedTime', '00:00:00');
    api.setState('stopwatchRunning', true);
    running = true;
 
    if (api.state.intervalId) {
      helpers.timing.clearInterval(api.state.intervalId);
      api.setState('intervalId', null);
      console.log('Existing interval cleared before starting new one');
    }
 
    // Pass startTime directly here
    updateElapsedTime(now);
 
    const id = helpers.timing.setInterval(() => {
      updateElapsedTime(now);
    }, 1000);
    api.setState('intervalId', id);
    console.log('Interval started with id:', id);
  } else {
    if (!api.state.intervalId) {
      // Use existing startTime from state, but be mindful it might still lag
      const storedStartTime = api.state.startTime || Date.now();
      const id = helpers.timing.setInterval(() => {
        updateElapsedTime(storedStartTime);
      }, 1000);
      api.setState('intervalId', id);
      console.log('Interval restarted with id:', id);
    }
  }
}
      3. Selecione Aplicar.
        Edite o modal de script do cliente sobrepondo o editor do Construtor de IU.
      4. Selecione E ao lado de Scripts do cliente para adicionar um segundo script.
      5. Entrar Parar em Nome do script campo.
      6. Cole o script a seguir no campo de script. 
        function handler({ api, helpers }) {
  console.log('Stop script running');
 
  if (api.state.stopwatchRunning === undefined) {
    // If state is not initialized yet, initialize it to avoid errors
    api.setState('stopwatchRunning', false);
    api.setState('elapsedTime', '00:00:00');
    api.setState('startTime', 0);
    api.setState('intervalId', null);
  }
 
  if (api.state.stopwatchRunning) {
    api.setState('stopwatchRunning', false);
    if (api.state.intervalId) {
      helpers.timing.clearInterval(api.state.intervalId);
      api.setState('intervalId', null);
    }
  }
}
      7. Selecione Aplicar.
      8. Selecione Save (Salvar).
    16. Adicione manipuladores de eventos aos botões que criamos nas etapas anteriores.
      1. Selecione Iniciar na árvore de conteúdo e abra o. Eventos no painel de configuração.
      2. Selecione Adicione manipulador em Ícone do botão clicado , em seguida, selecione Iniciar script de cliente que criamos nas etapas anteriores.
        Adicione o modal do manipulador de eventos com uma seta apontando para um script de cliente rotulado "Iniciar".
      3. Selecione Continuar , em seguida, selecione Adicionar .
      4. Selecione Parar na árvore de conteúdo e abra o. Eventos no painel de configuração.
      5. Selecione Adicione manipulador , em seguida, selecione Parar script de cliente que criamos nas etapas anteriores.
      6. Selecione Continuar , em seguida, selecione Adicionar .
      7. Selecione Save (Salvar).
    17. Selecione Visualização para testar os componentes configurados.
      Visualização do Construtor de IU da página com o componente do Cronômetro em execução.

    Resultado

    Seu componente personalizado agora está disponível no Construtor de IUcaixa de ferramentas.