API de ação de IU - ServiceNow Fluent

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

    • A API de ação de IU define ações personalizadas da interface do usuário (IU) [sys_ui_action], como botões, links e itens de menu de contexto em formulários e listas.

    Para obter informações gerais sobre ações de IU, consulte Create a UI action.

    Objeto UiAction

    Crie uma ação de IU [sys_ui_action] para exibir em um formulário.

    Tabela 1. Propriedades
    Nome Tipo Descrição
    id Cadeia de caracteres ou número Necessário. Um ID exclusivo para o objeto de metadados. Quando você cria a aplicação, este ID é hash em um sys_id exclusivo. Para obter mais informações, consulte ServiceNow Fluent construções de linguagem.

    Formato: Now.ID['Cadeia de caracteres' ou número]

    tabela Cadeia de caracteres Necessário. O nome da tabela na qual a ação de IU está disponível.

    Por padrão, a ação de IU também aparece em tabelas que estendem a tabela selecionada. Por exemplo, Ações de tarefa aparecem na tabela Incidente. Defina o valor como global para disponibilizar a ação em todas as tabelas.
    nome Cadeia de caracteres Necessário. O texto que aparece no botão, link ou item de menu de contexto. O nome deve ser exclusivo na tabela especificada.
    actionName Cadeia de caracteres Um nome exclusivo a ser usado ao fazer referência à ação de IU em scripts.
    ativo Booliano Sinalizador que indica se a ação de IU está habilitada.
    Valores válidos:
    • Verdadeiro: A ação de IU aparece e é executada.
    • Falso: A ação de IU está oculta.

    Padrão: verdadeiro
    formulário Objeto Opções de como as ações de IU aparecem nos formulários. Para obter mais informações, consulte objeto de formulário.
    lista Objeto Opções de como as ações de IU aparecem na exibição de lista. Para obter mais informações, consulte objeto da lista.
    cliente Objeto Opções para executar o script no navegador. Para obter mais informações, consulte objeto do cliente.
    espaço Objeto Opções de como as ações de IU funcionam e aparecem nos espaços de trabalho. Para obter mais informações, consulte objeto do espaço.
    substituições Referência ou cadeia de caracteres O nome ou identificador de variável de outra ação de IU que a ação de IU substitui.
    MostrarInserir Booliano Sinalizador que indica se um botão deve ser mostrado em novos registros antes de serem inseridos.
    Valores válidos:
    • Verdadeiro: O botão aparece nos registros antes de serem inseridos.
    • Falso: O botão não aparece em registros que não foram inseridos.

    Padrão: falso
    MostrarAtualizar Booliano Sinalizador que indica se um botão deve ser mostrado nos registros existentes.
    Valores válidos:
    • Verdadeiro: O botão aparece nos registros existentes.
    • Falso: O botão não aparece nos registros existentes.

    Padrão: verdadeiro
    ShowQuery Booliano Sinalizador que indica se a ação de IU está visível em uma lista quando uma consulta de filtro é aplicada.
    Valores válidos:
    • Verdadeiro: A ação de IU aparece quando uma consulta de filtro é aplicada.
    • Falso: A ação de IU não aparece e uma consulta de filtro foi aplicada.

    Padrão: falso
    MostrarAtualizaçãoMúltipla Booliano Sinalizador que indica se um botão deve ser exibido quando vários registros são selecionados.
    Valores válidos:
    • Verdadeiro: O botão aparece quando vários registros são selecionados.
    • Falso: O botão não aparece quando vários registros são selecionados.

    Padrão: falso
    condição Cadeia de caracteres Uma declaração condicional JavaScript que especifica os campos e valores que devem ser verdadeiros para que o script seja executado.
    Nota:
    • Não use esta propriedade se você incluir a declaração de condição com script propriedade.
    • O objeto atual não está disponível para condições em um menu de contexto de lista. Se a lista for MostrarContexto a propriedade é verdadeira, qualquer uso de atual nessas ações é ignorado.
    • Você pode fazer referência ao registro primário para as condições de ação de IU em um botão de lista relacionada. Por exemplo, para desabilitar o. Novo e. Editar Na lista relacionada de ICs afetados para mudanças encerradas, copie as ações globais de IU m2m para a tabela task_ci e adicione uma condição de parent.active.
    • Se você deixar um dos campos especificados na declaração de condição vazio, o padrão dessa condição será verdadeiro.
    Formato:
    • Para usar conteúdo de texto de outro arquivo, consulte um arquivo na aplicação usando o seguinte formato: Now.include('path/to/file') . Para obter mais informações, consulte ServiceNow Fluent construções de linguagem.
    • Para fornecer um script em linha, use literais de cadeia de caracteres ou literais de modelo para várias linhas de código: "Script" ou "Script" .
    script Script Um script do lado do cliente ou do lado do servidor que é executado quando a ação de IU é executada. Os nomes das funções devem ser exclusivos. Esta propriedade oferece suporte a JavaScript em linha ou a uma referência a outro arquivo na aplicação que contém um script.
    Formato:
    • Para usar conteúdo de texto de outro arquivo, consulte um arquivo na aplicação usando o seguinte formato: Now.include('path/to/file') . Para obter mais informações, consulte ServiceNow Fluent construções de linguagem.
    • Para fornecer um script em linha, use literais de cadeia de caracteres ou literais de modelo para várias linhas de código: "Script" ou "Script" .
    comentários Cadeia de caracteres Anotações internas sobre a ação de IU.
    mensagens Cadeia de caracteres Cadeias de caracteres de texto que a ação de IU pode usar como chave para pesquisar uma alternativa de mensagem localizada na tabela Mensagem [sys_ui_message]. Cada chave de mensagem está em uma linha separada no campo Mensagens.

    A instância procura uma cadeia de caracteres de mensagem localizada sempre que a ação de IU faz um getmessage('[message]') Chamada em que a cadeia de caracteres da mensagem corresponde a uma chave no campo Mensagens. Para obter mais informações, consulte Traduza uma mensagem de script do cliente .
    dica Cadeia de caracteres Uma descrição resumida da ação de IU que é exibida como dica de ferramenta ao passar o mouse sobre ela.
    pedido Número A ordem em que a ação de IU é exibida. A ordem se aplica aos botões da esquerda para a direita e às ações do menu de cima para baixo.

    Padrão: 100
    IsolateScript Booliano Sinalizador que indica se o script é executado em modo estrito, com acesso ao DOM direto, jQuery, protótipo e ao objeto window desativado.
    Valores válidos:
    • Verdadeiro: Isole o script e não o execute no modo estrito.
    • Falso: Execute o script no modo estrito.

    Padrão: falso
    funções Matriz Uma lista de identificadores de variáveis de Função Objetos ou nomes de funções necessários para que a ação de IU seja aplicada. Para obter mais informações, consulte API de função - ServiceNow Fluent.
    IncludeInViews Matriz Uma lista de nomes de exibições nas quais a ação de IU está incluída.
    ExcludeFromViews Matriz Uma lista de nomes de exibições das quais a ação de IU é excluída.
    meta Objeto Metadados dos metadados da aplicação.
    Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas.
    $meta: {
      installMethod: 'String'
}
    Valores válidos para Método de instalação :
    • Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada.
    • Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.
    		 
    import { UiAction } from '@servicenow/sdk/core'
        
UiAction({
    $id: Now.ID['car_info'],
    table: 'x_snc_ts_custom_cars',
    actionName: 'Car Information',
    name: 'View car info',
    active: true,
    showInsert: true,
    showUpdate: true,
    hint: 'View car info',
    condition: "current.type == 'SUV'",
    form: {
        showButton: true,
        showLink: true,
        showContextMenu: false,
        style: 'destructive',
    },
    list: {
        showLink: true,
        style: 'primary',
        showButton: true,
        showContextMenu: false,
        showListChoice: false,
        showBannerButton: true,
        showSaveWithFormButton: true,
    },
    workspace: {
        isConfigurableWorkspace: true,
        showFormButtonV2: true,
        showFormMenuButtonV2: true,
        clientScriptV2: `function onClick(g_form) {
                        }`,
    },
    script: `current.name =  "updated by script";
                current.update();`,
    roles: ['u_requestor'],
    client: {
        isClient: true,
        isUi11Compatible: true,
        isUi16Compatible: true,
        },
    order: 100,
    showQuery: false,
    showMultipleUpdate: false,
    isolateScript: false,
    includeInViews: ['specialView'],
    excludeFromViews: [],
})

    objeto de formulário

    Configure como uma ação de IU aparece em um formulário.

    . formulário o objeto é uma propriedade em UiAction objeto.

    Tabela 2. Propriedades
    Nome Tipo Descrição
    MostrarBotão Booliano Sinalizador que indica se um botão deve ser incluído em um formulário.
    Valores válidos:
    • Verdadeiro: Um botão aparece nos formulários.
    • Falso: Um botão não aparece nos formulários.

    Padrão: falso
    ShowLink Booliano Sinalizador que indica se um link deve ser incluído na seção Links relacionados de um formulário.
    Valores válidos:
    • Verdadeiro: Um link aparece na seção Links relacionados.
    • Falso: Um link não aparece na seção Links relacionados.

    Padrão: falso
    MostrarContexto Booliano Sinalizador que indica se um item deve ser incluído no menu de contexto de um formulário.
    Valores válidos:
    • Verdadeiro: Um item aparece no menu de contexto.
    • Falso: Um item não aparece no menu de contexto.

    Padrão: falso
    estilo Cadeia de caracteres Um estilo que define como os botões de ação de IU aparecem em um formulário.
    Valores válidos:
    • Primário: Colora a ação de IU em azul.
    • Destrutivo: Colora a ação de IU em vermelho.
    • Sem estilo: A ação de IU não está estilizada.
    meta Objeto Metadados dos metadados da aplicação.
    Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas.
    $meta: {
      installMethod: 'String'
}
    Valores válidos para Método de instalação :
    • Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada.
    • Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.
    		 
    form: {
  showButton: true,
  showLink: true,
  showContextMenu: false,
  style: 'destructive',
}

    objeto da lista

    Configure como uma ação de IU aparece na exibição de lista.

    . lista o objeto é uma propriedade em UiAction objeto.

    Tabela 3. Propriedades
    Nome Tipo Descrição
    MostrarBotão Booliano Sinalizador que indica se um botão deve ser incluído na parte inferior de uma lista.
    Nota:
    Os botões na parte inferior de uma lista aparecem independentemente da condição e são avaliados por registro na execução.
    Valores válidos:
    • Verdadeiro: Um botão aparece na parte inferior das listas.
    • Falso: Um botão não aparece na parte inferior das listas.

    Padrão: falso
    ShowLink Booliano Sinalizador que indica se um link deve ser incluído na seção Links relacionados de uma lista.
    Valores válidos:
    • Verdadeiro: Um link aparece na seção Links relacionados.
    • Falso: Um link não aparece na seção Links relacionados.

    Padrão: falso
    MostrarContexto Booliano Sinalizador que indica se um item deve ser incluído no menu de contexto de uma lista.
    Valores válidos:
    • Verdadeiro: Um item aparece no menu de contexto.
    • Falso: Um item não aparece no menu de contexto.

    Padrão: falso
    estilo Cadeia de caracteres Um estilo que define como os botões de ação de IU aparecem na exibição de lista.
    Valores válidos:
    • Primário: Colora a ação de IU em azul.
    • Destrutivo: Colora a ação de IU em vermelho.
    • Sem estilo: A ação de IU não está estilizada.
    MostListEscolha Booliano Sinalizador que indica se uma opção deve ser incluída na lista de ações de uma lista.
    Nota:
    As opções na lista Ações aparecem independentemente da condição e são avaliadas por registro na execução.
    Valores válidos:
    • Verdadeiro: Uma opção aparece na lista Ações.
    • Falso: Uma opção não aparece na lista de ações.

    Padrão: falso
    MostrarBotão BannerBannerButton Booliano Sinalizador que indica se um botão deve ser incluído na faixa de uma lista.
    Nota:
    Os botões no banner de uma lista não se destinam a oferecer suporte a condições específicas do registro. Somente a primeira linha é considerada quando a condição é avaliada para determinar se o botão aparece na lista. Não use condições específicas do registro, como GetValue('estado'): "Encerrado" .
    Valores válidos:
    • Verdadeiro: Um botão aparece na faixa de listas.
    • Falso: Um botão não aparece na faixa de listas.

    Padrão: falso
    MostSalvar WithFormButton Booliano Sinalizador que indica se o formulário foi salvo quando acessado em uma lista antes de executar o botão de ação de IU.
    Valores válidos:
    • Verdadeiro: O formulário deve ser salvo antes da execução da ação de IU.
    • Falso: O formulário não precisa ser salvo antes que a ação de IU seja executada.

    Padrão: falso
    meta Objeto Metadados dos metadados da aplicação.
    Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas.
    $meta: {
      installMethod: 'String'
}
    Valores válidos para Método de instalação :
    • Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada.
    • Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.
    		 
    list: {
  showButton: true,
  showLink: true,
  showContextMenu: false,
  style: 'primary',
  showListChoice: false,
  showBannerButton: true,
  showSaveWithFormButton: true,
}

    objeto do cliente

    Configure opções para executar o script de ação de IU no navegador.

    . cliente o objeto é uma propriedade em UiAction objeto.

    Tabela 4. Propriedades
    Nome Tipo Descrição
    IsCliente Booliano Sinalizador que indica onde o script de ação de IU é executado.
    Valores válidos:
    • Verdadeiro: O script é executado no cliente (o navegador do usuário).
    • Falso: O script é executado no servidor.

    Padrão: falso
    IsUi11Compatible Booliano Sinalizador que indica se a ação de IU é compatível com a IU legada 11.
    Valores válidos:
    • Verdadeiro: A ação de IU é compatível com a IU legada 11.
    • Falso: A ação de IU não é compatível com a IU legada 11.

    Padrão: falso
    IsUi16Compatible Booliano Sinalizador que indica se a ação de IU é compatível com a IU principal.
    Valores válidos:
    • Verdadeiro: A ação de IU é compatível com a IU principal.
    • Falso: A ação de IU não é compatível com a IU principal.

    Padrão: falso
    Em clique Cadeia de caracteres O nome da função JavaScript a ser executada quando a ação de IU é executada. A função é definida com script propriedade.
    meta Objeto Metadados dos metadados da aplicação.
    Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas.
    $meta: {
      installMethod: 'String'
}
    Valores válidos para Método de instalação :
    • Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada.
    • Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.
    		 
    client: {
  isClient: true,
  isUi11Compatible: true,
  isUi16Compatible: true,
  onClick: 'reopenIncident()'
}

    objeto do espaço

    Configure como uma ação de IU funciona e aparece nos espaços de trabalho.

    . espaço o objeto é uma propriedade em UiAction objeto.

    Tabela 5. Propriedades
    Nome Tipo Descrição
    IsConfigurable Workspace Booliano Sinalizador que indica o tipo de espaço ao qual uma ação de IU se aplica.
    Valores válidos:
    • Verdadeiro: A ação de IU se aplica a espaços configuráveis.
    • Falso: A ação de IU se aplica a espaços legados.

    Padrão: falso
    MostroFormButtonV2 Booliano Sinalizador que indica se um botão deve ser incluído em formulários em um espaço.
    Valores válidos:
    • Verdadeiro: Um botão aparece nos formulários.
    • Falso: Um botão não aparece nos formulários.

    Padrão: falso
    MostroMenuFormMenuV2 Booliano Sinalizador que indica se um item deve ser incluído no menu Mais ações em um espaço.
    Valores válidos:
    • Verdadeiro: Um item aparece no menu Mais ações.
    • Falso: Um item não aparece no menu Mais ações.

    Padrão: falso
    ScriptV2 Cadeia de caracteres Um script que é executado quando a ação de IU é executada em espaços de trabalho. Esta propriedade oferece suporte a JavaScript em linha ou a uma referência a outro arquivo na aplicação que contém um script.
    Formato:
    • Para usar conteúdo de texto de outro arquivo, consulte um arquivo na aplicação usando o seguinte formato: Now.include('path/to/file') . Para obter mais informações, consulte ServiceNow Fluent construções de linguagem.
    • Para fornecer um script em linha, use literais de cadeia de caracteres ou literais de modelo para várias linhas de código: "Script" ou "Script" .
    meta Objeto Metadados dos metadados da aplicação.
    Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas.
    $meta: {
      installMethod: 'String'
}
    Valores válidos para Método de instalação :
    • Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada.
    • Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.
    		 
    workspace: {
  isConfigurableWorkspace: true,
  showFormButtonV2: true,
  showFormMenuButtonV2: true,
  clientScriptV2: `function onClick(g_form) {
  }`,
}