Auxiliares - Construtor de IU

. auxiliares A API fornece funcionalidade geral que é comum em scripts de página, eliminando a necessidade de escrever scripts para funcionalidade simples, como abrir e fechar um modal.

Esta API só está disponível para scripts de página, não está disponível em nenhum outro script do Construtor de IU, incluindo:

• scripts de valor de propriedade do componente
• scripts de visibilidade do componente
• scripts de carga do evento
• Inclusões de script de cliente de UX

Helpers - helpers.modal.close(cadeia de caracteres modalId)

Fecha o modal especificado na página atual.

Tabela 1. Parâmetros

Nome	Tipo	Descrição
modalId	Cadeia de caracteres	ID do componente modal do modal a ser fechado. IDs de componente são gerados automaticamente quando um componente é arrastado e solto no Construtor de IU fase. Você pode localizar o ID na página da propriedade.

Tabela 2. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra como fechar um modal com um ID de componente que termina com alerta-modal .

function handler({api, event, imports, helpers}) {
  helpers.modal.close("[component-id$='alert_modal']")
}

Helpers - helpers.modal.open(cadeia de caracteres modalId, opções de objeto)

Abre o modal especificado na página atual.

Você só pode exibir um modal por vez em uma página. Se um modal estiver aberto no momento e você chamar esse método, o modal existente será oculto e o novo modal será exibido.

Tabela 3. Parâmetros

Nome	Tipo	Descrição
modalId	Cadeia de caracteres	ID do componente do modal a ser aberto. IDs de componente são gerados automaticamente quando um componente é arrastado e solto no Construtor de IU fase. Você pode localizar o ID na página da propriedade.
opções	Objeto	Opcional. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
options.content	Cadeia de caracteres	Conteúdo de texto para o modal.
Options.contentFullWidth	Booliano	Sinalizador que indica se o preenchimento horizontal ao redor do corpo do modal deve ser removido para caber um conteúdo mais amplo. Valores válidos: Verdadeiro: Remova o preenchimento. Falso: Não remova o preenchimento. Padrão: falso
Options.headerLabel	Cadeia de caracteres	Conteúdo de texto para o cabeçalho modal.
options.size	Cadeia de caracteres	Tamanho do contêiner modal. A maioria dos tamanhos se expande automaticamente para preencher a janela de exibição quando o tamanho da tela é pequeno. Valores válidos: sm md lg tela cheia Padrão: sm

Tabela 4. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra como abrir um modal com ID de componente que termina com alerta-modal .

function handler({api, event, imports, helpers}) {
  helpers.modal.open("[component-id$='alert_modal']")
}

Auxiliares - helpers.navigate.setRouteParams(Object parâmetros)

Passa os parâmetros especificados para outros componentes na mesma página.

Use este método em qualquer componente de página que queira adicionar um parâmetro em uma URL. Você pode querer adicionar um parâmetro a um URL quando outro componente precisar saber o valor atual desse parâmetro quando ele mudar, para que ele possa reagir a ele. Por exemplo, use este método para passar o. SelectedIndex De um componente de guia para que ele seja refletido na URL para dar foco a essa guia.

Tabela 5. Parâmetros

Nome	Tipo	Descrição
parâms	Objeto	Pares chave-valor de parâmetros opcionais para passar para outros componentes. Este deve ser um objeto simples e plano com apenas valores primitivos. As referências de matriz ou objeto são ignoradas e não adicionadas ao URL. Todas as chaves especificadas devem fazer parte dos parâmetros opcionais na configuração de rota ou também serão ignoradas. Para obter informações adicionais sobre parâmetros opcionais, consulte Crie uma página no Construtor de IU.

Tabela 6. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo de código mostra como anexar o URL params/selected-tab-index/2 . Observe que o parâmetro no URL real é alterado de caso camel para caso snake, portanto SelectedTabIndex se torna selected-tab-index .

function handler({api, event, helpers, imports}) {  
  helpers.navigate.setRouteParams({'params': {'selectedTabIndex':  2}});  
} 

Helpers - helpers.navigate.to(Rota de cadeia de caracteres, campos de objeto, parâmetros de objeto, redirecionamento booliano, passiveNavigation booliano, cadeia de caracteres targetRoute)

Navega de uma tela para outra com base nas informações de rota e campo especificadas. Mudanças de URL e as respectivas cargas de tela são observadas.

Tabela 7. Parâmetros

Nome	Tipo	Descrição
rota	Cadeia de caracteres	Nome da rota. Deve ser uma entrada válida das Rotas de aplicações UX (sys_ux_app_route.list). Este valor é refletido no URL e o URL é criado com base em route, fieldse optionalParamsvalores de coluna: /<route>/<field1Value>//<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2> Por exemplo: /Record/incident/12345/params/selectedTabIndex/4
campos	Objeto	Opcional. Pares de chave-valor de parâmetros obrigatórios. Por exemplo: "Campos": "Tabela": "Incidente", "sySID": "12345" .
parâms	Objeto	Opcional. Pares chave-valor de parâmetros opcionais. Por exemplo: "params": "SelectedTabIndex": 4 .
redirect	Booliano	Sinalizador que indica se a entrada de histórico mais recente deve ser removida do histórico do navegador. Por exemplo, se você navegar até os sites A, B e C. Se redirectestá definido como verdadeiro Ao navegar até C, a entrada de histórico de B é removida. O histórico do navegador mostra somente A e C. Valores válidos: Verdadeiro: Remove a entrada de histórico mais recente e redireciona para o URL mais recente. Falso: Não remove entradas de histórico. Padrão: falso
passiveNavigation	Booliano	Sinalizador que indica se a navegação em segundo plano deve ser executada. A navegação em segundo plano ocorre quando uma página é aberta, mas não está ativa ou mostrada. Por exemplo, abrir uma guia inativa para a página, mas ela não está visível, mas carregada em segundo plano. Valores válidos: Verdadeiro: Execute a navegação em segundo plano. Falso: Não execute navegação em segundo plano. Padrão: falso
targetRoute	Cadeia de caracteres ou objeto	Subnavegação para detalhar, link profundo ou subguia. Se definido como atual , A rota atual faz uma subnavegação no URL atual. Por exemplo, se /record/incident/123 É o URL atual e a seguinte chamada é feita: Helper.navigate.to('record',['table': 'Problem', 'sySID': '567', false, falso, 'atual'); A seguinte URL é gerada: /record/incident/123/sub/record/problem/567 Nota: targetRoutepode ser uma cadeia de caracteres, como 'atual' ou um objeto, como Carga de navegação NAV_ITEM_SELECTED .

Tabela 8. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra como navegar até uma página passando apenas por routeparâmetro.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test');
}

Este exemplo mostra como navegar até uma página que passa por routee. fieldsparâmetros.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test', {'key': 'value'});
}

Este exemplo mostra como navegar até uma página que passa por route, fieldse paramsparâmetros.

function handler({api, event, helpers, imports}) {
  helpers.navigate.to('test', {'key': 'value'}, {'first': 'FirstName', 'last': 'Last Name'});
}

Helpers - helpers.screen.updateStatus(Object statusObj)

Permite que as páginas relatem suas atualizações de status, como título, ícone, estado sujo, mensagem, e mudanças de erro.

As atualizações de status são relatadas para WorkspaceChrome ou AppShell, seja qual for a camada externa, e agindo como o host.

Tabela 9. Parâmetros

Nome	Tipo	Descrição
StatusObj	Objeto	Carga a ser enviada para a página atual para relatar que o conteúdo foi atualizado. Valores válidos: dirtyModalId(Cadeia de caracteres) ID do modal que foi alterado. hasErrorSinalizador (booliano) que indica que há erros na página. hasUpdateSinalizador (booliano) que indica que houve atualizações na página. icon(Cadeia de caracteres) Nome do ícone atualizado ou novo. isDirtySinalizador (booliano) que indica se a página está incorreta (os valores foram alterados). message(Cadeia de caracteres) Mensagem atualizada/nova. screenKeyID da tela na qual a mudança ocorreu. Cada tela tem um screenKeycomo uma propriedade na tela macroponent dentro sn-canvas-screen. status(Cadeia de caracteres) Operação de status desta ação. Este valor deve ser um dos seguintes: Inserido, excluído, salvo ou encerrado. title(Cadeia de caracteres) Título de exibição atualizado/novo. tooltipPreview(JSON) Dica de ferramenta atualizada ou nova. Por exemplo, TooltipPreview

Tabela 10. Retornos

Tipo	Descrição
Nenhum

screen.updateStatus({'dirtyModalId': 'customModalId', 'isDirty': true});

Helpers - helpers.snHttp (url de cadeia de caracteres, opções de objeto)

Faz uma solicitação HTTP para ServiceNow e retorna uma promessa com os resultados.

Nota:

Há um problema conhecido em que objetos nomeados optionsSão omitidos da resposta HTTP.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

Tabela 11. Parâmetros

Nome	Tipo	Descrição
URL	Cadeia de caracteres	Endpoint HTTP relativo ao URL da instância. Por exemplo, /api/now/table/incident ou /api/now/table/incident/a83820b58f723300e7e16c7827bdeed .
opções	Objeto	Descreve o conteúdo da solicitação HTTP. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }
options.batch	Booliano	Opcional. Sinalizador que indica se esta solicitação HTTP deve ser colocada em lote com outras solicitações HTTP feitas para a instância. Valores válidos: Verdadeiro: Faça a solicitação como parte de uma solicitação em lote. Falso: Faça solicitação dedicada. Padrão: verdadeiro
options.body	Objeto	Opcional. Dados a serem enviados como o corpo da solicitação. Aplicável somente para métodos de solicitação COLOCAR , PUBLICAR e PATCH . Os elementos no objeto dependem do tipo de método HTTP. Para obter detalhes, consulte os exemplos de código abaixo. Padrão: .
options.headers	Objeto	Opcional. Cabeçalhos de solicitação HTTP adicionais. Por exemplo: headers: { "Content-Type": "application/json", "Accept": "application/xml" }
options.method	Cadeia de caracteres	Opcional. Método HTTP. Valores válidos: DELETE GET PATCH POST PUT Padrão: GET

Tabela 12. Retornos

Tipo	Descrição
erro	Objeto que descreve qualquer erro retornado pela REST API. Tipo de dados: Objeto "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
error.data	Resposta retornada da API HTTP. Tipo de dados: Definido pela REST API
mensagem.erro	Mensagem descrevendo o erro encontrado ao tentar processar a solicitação HTTP. Nota: Este parâmetro nem sempre é retornado. Tipo de dados: Cadeia de caracteres
error.options	Descreve a solicitação HTTP original. Tipo de dados: Objeto "options": { "headers": {Object}, "responseHeader": {Object} }
cabeçalhos.options.error	Objeto que contém uma lista de todos os cabeçalhos de solicitação enviados na solicitação. Tipo de dados: Objeto
Error.options.ResponseHeaders	Objeto que contém uma lista de todos os cabeçalhos de resposta enviados na solicitação. Tipo de dados: Objeto
error.status	Código de status de erro HTTP retornado, como 400, 405 ou 500. Tipo de dados: Número
Error.statusText	Mensagem de status HTTP retornada, como Solicitação incorreta . Tipo de dados: Cadeia de caracteres
resposta	Retornado quando a solicitação HTTP é bem-sucedida. A resposta à solicitação HTTP. Tipo de dados: Qualquer

O exemplo a seguir mostra como chamar SnHttp() que retorna uma promessa.

function handler({api, event, helpers, imports}) {
  helpers.snHttp('/api/now/table/u_movie', {method: 'GET'})
    .then(({response}) => {
      // do something with the table data
    })
    .catch(({error}) => {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
    });
  });
}

O exemplo a seguir mostra como chamar SnHttp() usando assíncrono e. aguardar .

async function handler({helpers}) {
  try {
    const result = await helpers.snHttp('/api/now/table/u_movie', {method: 'GET'});
  } catch ({error}) {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
      });
  }
}

O exemplo a seguir mostra como configurar uma solicitação POST.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident", {
      method: "POST",
      body: {
        description: "Sample description",
        close_notes: "Sample close notes",
        order: "-1"
      }
    })
    .then(({ response }) => {
      // handle POST request response
    })
    .catch(({ error }) => {
      // handle POST request errors
    });
}

O exemplo a seguir mostra como configurar uma solicitação PUT.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident/a83820b58f723300e7e16c7827bdeed2", {
      method: "PUT",
      body: {
        activity_due: "1970-04-02 18:26:17"
      },
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/xml"
      }
    })
    .then(({ response }) => {
      // handle PUT request response
    })
    .catch(({ error }) => {
      // handle PUT request errors
    });
}

Helpers - helpers.timing.clearInterval(Number timeoutId)

Cancela a execução da função que foi programada por meio de um anterior SetInterval() chamada.

Tabela 13. Parâmetros

Nome	Tipo	Descrição
TimeoutId	Número	Identificador exclusivo da função programada a ser limpa. Este valor é retornado pelo correspondente SetInterval() chamada.

Tabela 14. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra usando ClearInterval() para cancelar uma operação de tempo que foi definida anteriormente usando SetInterval() método. Esta função pode ser invocada por um usuário clicando em Desativar atualização automática botão em uma página.

function handler({api, helpers}) {
  api.setState('intervalId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearInterval(currentValue);
    }
    return -1;
  });
}

Helpers - helpers.timing.clearTimeout(number timeoutId)

Cancela a execução da função que foi programada por meio de um anterior SetTimeout() chamada.

Tabela 15. Parâmetros

Nome	Tipo	Descrição
TimeoutId	Número	Identificador exclusivo da função programada a ser limpa. Este valor é retornado pelo correspondente SetTimeout() chamada.

Tabela 16. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo de código mostra como encerrar um temporizador com o especificado TimeoutId .

function handler({api, helpers}) {
  api.setState('timeoutId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearTimeout(currentValue);
    }
    return -1;
  });
}

Auxiliares - helpers.timing.setInterval(Function fn, atraso de número)

Executa repetidamente a função especificada, usando o valor de atraso especificado como o intervalo entre as chamadas de função.

Ao contrário do JavaScript nativo SetInterval() este método não é compatível com a passagem de uma cadeia de caracteres de código para avaliar como o primeiro argumento. Todos os argumentos adicionais são passados para a própria função.

Tabela 17. Parâmetros

Nome	Tipo	Descrição
fn	Função	Função a ser executada repetidamente.
atraso	Número	Duração do intervalo de tempo entre cada execução de função. Unidade: Milissegundos

Tabela 18. Retornos

Tipo	Descrição
Número	Identificador exclusivo da operação de execução da função. Use este valor em Helpers - helpers.timing.clearInterval(Number timeoutId) se você precisar cancelar esta operação.

Este exemplo de código mostra como atualizar o carimbo de data/hora em uma página a cada segundo. Esta função pode ser invocada por um usuário clicando em Habilitar atualização automática botão em uma página.

function handler({api, helpers}) {
  // Every one second, refresh the value of current timestamp client state parameter
  const intervalId = helpers.timing.setInterval(() => {
    api.setState('currentTimestamp', new Date().toString())
  }, 1000);

  // The interval ID is kept in state to use when calling the helpers.timing.clearInterval() method at a later point
  api.setState('intervalId', intervalId);
}

Auxiliares - helpers.timing.setTimeout(Function fn, atraso de número)

Executa a função especificada após o atraso especificado.

Ao contrário do JavaScript nativo SetTimeout() este método não é compatível com a passagem de uma cadeia de caracteres de código para avaliar como o primeiro argumento. Todos os argumentos adicionais são passados para a própria função.

Tabela 19. Parâmetros

Nome	Tipo	Descrição
fn	Função	Função a ser executada.
atraso	Número	Tempo de espera antes de chamar a função especificada. Unidade: Milissegundos

Tabela 20. Retornos

Tipo	Descrição
Número	Identificador exclusivo da operação de execução da função. Use este valor em Helpers - helpers.timing.clearTimeout(number timeoutId) se você precisar cancelar esta operação.

Este exemplo de código mostra como definir um temporizador de 20 minutos. Você pode associar esta função a um botão Lembre-me em 20 minutos .

function handler({api, helpers}) {
  const timeoutId = helpers.timing.setTimeout(() => {
    api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
      id: 'alert5',
      status: 'high',
      icon: 'info-circle-outline',
      content: 'Try to look away at something that is 20 feet away from you for a total of 20 minutes.',
      action: { type: 'dismiss' }
    });
  }, 20 * 60 * 1000);

  // The timeout ID is kept in state to use when calling the helpers.timing.clearTimeout() method at a later point
  api.setState('timeoutId', timeoutId);
}

Helpers - helpers.translate (mensagem de cadeia de caracteres, tokens de cadeia de caracteres)

Recupera e traduz de forma assíncrona a mensagem especificada com base no idioma da sessão do usuário atual.

Você pode usar este método com SetState(cadeia de caracteres stateParam, qualquer valor) para vincular o valor traduzido a outros campos na página.

Nota:

Você pode chamar este método usando uma promessa ou assíncrono e. aguardar . Os exemplos de código abaixo mostram as duas implementações.

Tabela 21. Parâmetros

Nome	Tipo	Descrição
message	Cadeia de caracteres	Mensagem a ser traduzida.
tokens	Cadeia de caracteres	Opcional. Lista separada por vírgulas de parâmetros a serem usados para substituir variáveis de cadeia de caracteres. Por exemplo: helpers.translate('Text {0} {1}', 'to', 'translate');

Tabela 22. Retornos

Tipo	Descrição
Cadeia de caracteres	Cadeia de caracteres de texto traduzida.

O exemplo a seguir mostra como passar referências de campo de tabela para incorporar nas variáveis correspondentes em uma cadeia de caracteres, usando uma promessa.

function handler ({api, helpers}) {
  helpers.translate('Welcome {0} {1}!', user.firstName, user.lastName)
    .then((translatedText) => {
      api.setState('greeting', translatedText);
    });
}

O exemplo a seguir mostra como usar assíncrono e. aguardar em sua função em vez de uma promessa.

async function handler ({api, helpers}) {
  const translatedText = await helpers.translate('Welcome to {0}', 'ServiceNow');
    api.setState('greeting', translatedText);
}