helpers – UI Builder

Die Hilfs -API bietet allgemeine Funktionen, die in Seitenskripts gleich sind, sodass keine Skripts für einfache Funktionen wie das Öffnen und Schließen eines modalen Elements geschrieben werden müssen.

Diese API ist nur für Seitenskripts verfügbar. Sie ist in keinen anderen UI Builder-Skripts verfügbar, einschließlich:

• Skripts für Komponenteneigenschaftswert
• Skripts für Komponentensichtbarkeit
• Event-Nutzlastskripts
• UX-Client-Skripteinbindungen

helpers – helpers.modal.close(String modalId)

Schließt das angegebene Dialogfeld auf der aktuellen Seite.

Tabelle : 1. Parameter

Name	Typ	Beschreibung
modalId	Zeichenfolge	Modale Komponenten-ID des zu schließenden modalen Elements. Komponenten-IDs werden automatisch generiert, wenn eine Komponente per Drag-and-Drop in die Phase UI Builder verschoben wird. Sie finden die ID auf der Eigenschaftenseite.

Tabelle : 2. Ergebnisse

Typ	Beschreibung
Keine

Dieses Beispiel zeigt, wie ein modales Element mit einer Komponenten-ID geschlossen wird, die mit alert-modalendet.

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

helpers – helpers.modal.open(String modalId, Object options)

Öffnet das angegebene Dialogfeld auf der aktuellen Seite.

Sie können auf einer Seite jeweils nur ein modales Element anzeigen. Wenn derzeit ein Modal geöffnet ist und Sie diese Methode aufrufen, wird das vorhandene Modal ausgeblendet und das neue Modal angezeigt.

Tabelle : 3. Parameter

Name	Typ	Beschreibung
modalId	Zeichenfolge	Komponenten-ID des zu öffnenden Modals. Komponenten-IDs werden automatisch generiert, wenn eine Komponente per Drag-and-Drop in die Phase UI Builder verschoben wird. Sie finden die ID auf der Eigenschaftenseite.
Optionen	Objekt	Optional. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
options.content	Zeichenfolge	Textinhalt für das Modal.
options.contentFullWidth	Boolean	Kennzeichnung, die angibt, ob die horizontale Auffüllung um den Textkörper des modalen Elements entfernt werden soll, um breiteren Inhalt anzupassen. Gültige Werte: true: Abstand entfernen. false: Abstand nicht entfernen. Standardwert: false
Optionen.headerLabel	Zeichenfolge	Textinhalt für den modalen Header.
options.size	Zeichenfolge	Größe des modalen Containers. Die meisten Größen werden automatisch erweitert, um den Viewport auszufüllen, wenn die Bildschirmgröße klein ist. Gültige Werte: sm md lg Vollbild Standard: sm

Tabelle : 4. Ergebnisse

Typ	Beschreibung
Keine

Dieses Beispiel zeigt das Öffnen eines Modals mit der Komponenten-ID ca, das mit alert-modalendet.

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

helpers – helpers.navigate.setRouteParams(Object params)

Übergibt die angegebenen Parameter an andere Komponenten auf derselben Seite.

Verwenden Sie diese Methode in jeder Seitenkomponente, die einen Parameter in einer URL hinzufügen möchte. Sie können einen Parameter zu einer URL hinzufügen, wenn eine andere Komponente den aktuellen Wert dieses Parameters kennen muss, wenn er sich ändert, damit sie darauf reagieren kann. Verwenden Sie diese Methode beispielsweise, um den selectedIndex einer Registerkartenkomponente so zu übergeben, dass er in der URL angezeigt wird, um den Fokus auf diese Registerkarte zu legen.

Tabelle : 5. Parameter

Name	Typ	Beschreibung
params	Objekt	Schlüssel-Wert-Paare optionaler Parameter, die an andere Komponenten übergeben werden sollen. Dies muss ein einfaches, flaches Objekt mit nur primitiven Werten sein. Array- oder Objektreferenzen werden ignoriert und der URL nicht hinzugefügt. Alle angegebenen Schlüssel müssen Teil der optionalen Parameter in der Routenkonfiguration sein, oder sie werden ebenfalls ignoriert. Weitere Informationen zu optionalen Parametern finden Sie unter Seiten in UI Builder erstellen.

Tabelle : 6. Ergebnisse

Typ	Beschreibung
Keine

Dieses Code-Beispiel zeigt, wie die URL params/selected-tab-index/2 angehängt wird. Beachten Sie, dass der Parameter in der tatsächlichen URL von Camel-Case in Schlangen-Case geändert wurde, sodass selectedTabIndex zu selected-tab-indexwird.

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

helpers – helpers.navigate.to(String route, Object fields, Object params, Boolean weitergeleitet, Boolean passiveNavigation, String targetRoute)

Navigiert basierend auf der angegebenen Route und den Feldinformationen von einem Bildschirm zu einem anderen. URL-Änderungen und die entsprechenden Bildschirmlasten werden beachtet.

Tabelle : 7. Parameter

Name	Typ	Beschreibung
Weiterleitung	Zeichenfolge	Name der Route. Muss ein gültiger Eintrag aus UX-App-Routen (sys_ux_app_route.list) sein. Dieser Wert spiegelt sich in der URL wider, und die URL wird basierend auf den Spaltenwerten route, fieldsund optionalParams erstellt: /<route> /<field1Value> /{<field2Value> /Parameter/<optionalParamKey1> /<optionalParamValue1> /<optionalParamKey2> /<optionalParamValue2> Beispiel: /record/incident/12345/params/selectedTabIndex/4
Felder	Objekt	Optional. Schlüssel-Wert-Paare der erforderlichen Parameter. Beispiel: 'fields' : {'table': 'incident', 'sysId': '12345'}.
params	Objekt	Optional. Schlüssel-Wert-Paare optionaler Parameter. Beispiel: 'params' : {'selectedTabIndex': 4}.
umleiten	Boolean	Kennzeichnung, die angibt, ob der aktuelle Verlaufseintrag aus dem Browserverlauf entfernt werden soll. Beispiel: Wenn Sie zu den Sites A, B und dann C navigieren. Wenn redirect beim Navigieren zu C auf „ true “ festgelegt wird, wird der Verlaufseintrag für B entfernt. Der Browserverlauf zeigt nur A und C an. Gültige Werte: true: Entfernt den letzten Verlaufseintrag und leitet zur neuesten URL um. false: Entfernt keine Verlaufseinträge. Standardwert: false
passiveNavigation	Boolean	Kennzeichnung, die angibt, ob die Hintergrundnavigation ausgeführt werden soll. Die Hintergrundnavigation liegt vor, wenn eine Seite geöffnet wird, aber nicht aktiv ist oder angezeigt wird. Beispiel: Öffnen einer inaktiven Registerkarte für die Seite, die jedoch nicht sichtbar ist, sondern im Hintergrund geladen wird. Gültige Werte: true: Hintergrundnavigation durchführen. false: Keine Hintergrundnavigation durchführen. Standardwert: false
targetRoute	Zeichenfolge oder Objekt	Untergeordnete Navigation zu einem Drilldown, Deep-Link oder einer Unterregisterkarte. Bei Festlegung auf currentführt die aktuelle Route eine Unternavigation unter der aktuellen URL durch. Beispiel: Wenn /record/incident/123 die aktuelle URL ist und der folgende Aufruf erfolgt: helper.navigate.to('record', {'table': 'problem', 'sysId': '567'}, {}, false, false, 'current'); Die folgende URL wird generiert: /record/incident/123/sub/record/problem/567 Hinweis: targetRoute kann entweder eine Zeichenfolge wie „current“ oder ein Objekt wie „ navigation NAV_ITEM_SELECTED payload“ sein.

Tabelle : 8. Ergebnisse

Typ	Beschreibung
Keine

Dieses Beispiel zeigt, wie Sie zu einer Seite navigieren, indem Sie nur den Parameter route übergeben.

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

Dieses Beispiel zeigt, wie Sie zu einer Seite navigieren, indem Sie die Parameter route und fields übergeben.

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

Dieses Beispiel zeigt, wie Sie zu einer Seite navigieren, indem Sie die Parameter route, fieldsund params übergeben.

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

helpers – helpers.screen.updateStatus(Object statusObj)

Ermöglicht Seiten, ihre Statusaktualisierungen zu melden, z. B. Titel, Symbol, geänderter Status, Meldung und Fehleränderungen.

Statusaktualisierungen werden an WorkspaceChrome oder AppShell gemeldet, je nachdem, welche die äußere Ebene ist und als Host fungiert.

Tabelle : 9. Parameter

Name	Typ	Beschreibung
statusObj	Objekt	Nutzlast, die an die aktuelle Seite gesendet werden soll, um zu melden, dass der Inhalt aktualisiert wurde. Gültige Werte: dirtyModalId: (Zeichenfolge) ID des modalen Elements, das sich geändert hat. hasError: (Boolean) Kennzeichnung, die angibt, dass auf der Seite Fehler vorhanden sind. hasUpdate: (Boolean) Kennzeichnung, die angibt, dass die Seite aktualisiert wurde. icon: (Zeichenfolge) Name des aktualisierten oder neuen Symbols. isDirty: (Boolean) Kennzeichnung, die angibt, ob die Seite fehlerhaft ist (Werte haben sich geändert). message: (Zeichenfolge) Aktualisierte/neue Nachricht. screenKey: (Zeichenfolge) ID des Bildschirms, in dem die Änderung aufgetreten ist. Jeder Bildschirm hat screenKey als Eigenschaft im Bildschirm-Macroponent in sn-canvas-screen. status: (Zeichenfolge) Statusvorgang für diese Aktion. Dieser Wert muss einer der folgenden sein: eingefügt, gelöscht, gespeichert oder geschlossen. title: (Zeichenfolge) Aktualisierter/neuer Anzeigetitel. tooltipPreview: (JSON) Aktualisierter oder neuer Tooltip. Beispiel: TooltipPreview: {primärerTitel, sekundärerInhalt: {}}

Tabelle : 10. Ergebnisse

Typ	Beschreibung
Keine

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

helpers – helpers.snHttp(String url, Object options)

Sendet eine HTTP-Anforderung an die Instanz ServiceNow und gibt eine Zusage mit den Ergebnissen zurück.

Hinweis:

Es gibt ein bekanntes Problem, bei dem Objekte mit dem Namen options in der HTTP-Antwort ausgelassen werden.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

Tabelle : 11. Parameter

Name	Typ	Beschreibung
URL	Zeichenfolge	HTTP-Endpunkt relativ zur Instanz-URL. Zum Beispiel /api/now/table/incident oder /api/now/table/incident/a83820b58f723300e7e16c7827bdeed.
Optionen	Objekt	Beschreibt den Inhalt der HTTP-Anforderung. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }
options.batch	Boolean	Optional. Kennzeichnung, die angibt, ob diese HTTP-Anforderung in einem Batch mit anderen HTTP-Anforderungen an die Instanz zusammengefasst werden soll. Gültige Werte: true: Anforderung als Teil einer Batch-Anforderung erstellen. false: Dedizierte Anforderung senden. Standardwert: true
options.text	Objekt	Optional. Daten, die als Anforderungstext gesendet werden sollen. Gilt nur für die Anforderungsmethoden PUT, POSTund PATCH. Elemente im Objekt hängen vom Typ der HTTP-Methode ab. Weitere Informationen finden Sie in den folgenden Codebeispielen. Standard: {}
options.headers	Objekt	Optional. Zusätzliche HTTP-Anforderungskopfzeilen. Beispiel: headers: { "Content-Type": "application/json", "Accept": "application/xml" }
options.method	Zeichenfolge	Optional. HTTP-Methode. Gültige Werte: LÖSCHEN GET PATCH POST PUT Standard: GET

Tabelle : 12. Ergebnisse

Typ	Beschreibung
Fehler	Objekt, das alle von der REST-API zurückgegebenen Fehler beschreibt. Datentyp: Objekt "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
Fehler.Daten	Antwort, die von der HTTP-API zurückgegeben wird. Datentyp: Definiert durch REST API
Fehler.Nachricht	Meldung, die den Fehler beschreibt, der beim Versuch, die HTTP-Anforderung zu verarbeiten, aufgetreten ist. Hinweis: Dieser Parameter wird nicht immer zurückgegeben. Datentyp: Zeichenfolge
Fehler.Optionen	Beschreibt die ursprüngliche HTTP-Anforderung. Datentyp: Objekt "options": { "headers": {Object}, "responseHeader": {Object} }
Fehler.Optionen.Header	Objekt, das eine Liste aller in der Anforderung gesendeten Anforderungskopfzeilen enthält. Datentyp: Objekt
Fehler.Optionen.AntwortHeader	Objekt, das eine Liste aller in der Anforderung gesendeten Antwortkopfzeilen enthält. Datentyp: Objekt
Fehler.Status	Zurückgegebener HTTP-Fehlerstatuscode, z. B. 400, 405 oder 500. Datentyp: Zahl
Fehler.StatusText	Zurückgegebene HTTP-Statusmeldung, z. B. Ungültige Anforderung. Datentyp: Zeichenfolge
Antwort	Wird zurückgegeben, wenn die HTTP-Anforderung erfolgreich ist. Die Antwort auf die HTTP-Anforderung. Datentyp: Beliebig

Das folgende Beispiel zeigt, wie snHttp() aufgerufen wird, was eine Zusage zurückgibt.

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' }
    });
  });
}

Das folgende Beispiel zeigt, wie snHttp() mit „ async “ und „ await“ aufgerufen wird.

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' }
      });
  }
}

Das folgende Beispiel zeigt, wie eine POST-Anforderung eingerichtet wird.

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
    });
}

Das folgende Beispiel zeigt, wie eine PUT-Anforderung eingerichtet wird.

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.timeing.clearInterval(Number timeoutId)

Bricht die Ausführung der Funktion ab, die durch einen vorherigen setInterval()- Aufruf geplant wurde.

Tabelle : 13. Parameter

Name	Typ	Beschreibung
Zeitüberschreitungs-ID	Nummer	Eindeutiger Bezeichner der zu löschenden geplanten Funktion. Dieser Wert wird vom entsprechenden setInterval()- Aufruf zurückgegeben.

Tabelle : 14. Ergebnisse

Typ	Beschreibung
Keine

Dieses Beispiel zeigt die Verwendung von clearInterval(), um einen Zeitvorgang abzubrechen, der zuvor mit dersetInterval()- Methode festgelegt wurde. Diese Funktion kann von einem Benutzer aufgerufen werden, der auf einer Seite auf die Schaltfläche Automatische Aktualisierung deaktivieren klickt.

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

helpers – helpers.timeout.clearTimeout(Number timeoutId)

Bricht die Ausführung der Funktion ab, die durch einen vorherigen setTimeout()- Aufruf geplant wurde.

Tabelle : 15. Parameter

Name	Typ	Beschreibung
Zeitüberschreitungs-ID	Nummer	Eindeutiger Bezeichner der zu löschenden geplanten Funktion. Dieser Wert wird vom entsprechenden setTimeout()- Aufruf zurückgegeben.

Tabelle : 16. Ergebnisse

Typ	Beschreibung
Keine

Dieses Codebeispiel zeigt, wie ein Timer mit der angegebenen timeoutId beendet wird.

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

helpers – helpers.timer.setInterval(Function fn, Nummernverzögerung)

Führt die angegebene Funktion wiederholt aus, wobei der angegebene Verzögerungswert als Intervall zwischen Funktionsaufrufen verwendet wird.

Im Gegensatz zur nativen JavaScript-Methode setInterval() unterstützt diese Methode nicht die Übergabe einer Codezeichenfolge, die als erstes Argument ausgewertet werden soll. Alle zusätzlichen Argumente werden an die Funktion selbst übergeben.

Tabelle : 17. Parameter

Name	Typ	Beschreibung
fn	Funktion	Funktion, die wiederholt ausgeführt werden soll.
Verzögerung	Nummer	Länge des Zeitintervalls zwischen jeder Funktionsausführung. Einheit: Millisekunden

Tabelle : 18. Ergebnisse

Typ	Beschreibung
Nummer	Eindeutiger Bezeichner des Funktionsausführungsvorgangs. Verwenden Sie diesen Wert in der Methode helpers – helpers.timeing.clearInterval(Number timeoutId), wenn Sie diesen Vorgang abbrechen müssen.

Dieses Codebeispiel zeigt, wie der Zeitstempel auf einer Seite jede Sekunde aktualisiert wird. Diese Funktion kann von einem Benutzer aufgerufen werden, der auf einer Seite auf die Schaltfläche Automatische Aktualisierung aktivieren klickt.

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);
}

helpers – helpers.timeout.setTimeout(Function fn, Number Delay)

Führt die angegebene Funktion nach der angegebenen Verzögerung aus.

Im Gegensatz zur nativen JavaScript-Methode setTimeout() unterstützt diese Methode nicht die Übergabe einer Codezeichenfolge, die als erstes Argument ausgewertet werden soll. Alle zusätzlichen Argumente werden an die Funktion selbst übergeben.

Tabelle : 19. Parameter

Name	Typ	Beschreibung
fn	Funktion	Auszuführende Funktion.
Verzögerung	Nummer	Dauer der Wartezeit, bevor die angegebene Funktion aufgerufen wird. Einheit: Millisekunden

Tabelle : 20. Ergebnisse

Typ	Beschreibung
Nummer	Eindeutiger Bezeichner des Funktionsausführungsvorgangs. Verwenden Sie diesen Wert in der Methode helpers – helpers.timeout.clearTimeout(Number timeoutId), wenn Sie diesen Vorgang abbrechen müssen.

Dieses Code-Beispiel zeigt, wie ein 20-Minuten-Timer eingestellt wird. Sie können diese Funktion einer Schaltfläche In 20 Minuten erinnern zuordnen.

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(String message, String tokens)

Ruft die angegebene Nachricht asynchron ab und übersetzt sie basierend auf der Sitzungssprache des aktuellen Anwenders.

Sie können diese Methode mit api – setState(String stateParam, Beliebiger Wert) verwenden, um den übersetzten Wert an andere Felder auf der Seite zu binden.

Hinweis:

Sie können diese Methode mit einer Zusage oder asynchron aufrufen und warten. Die folgenden Codebeispiele zeigen beide Implementierungen.

Tabelle : 21. Parameter

Name	Typ	Beschreibung
Nachricht	Zeichenfolge	Zu übersetzende Nachricht.
Token	Zeichenfolge	Optional. Kommagetrennte Liste von Parametern, die zum Ersetzen von Zeichenfolgenvariablen verwendet werden sollen. Beispiel: helpers.translate('Text {0} {1}', 'to', 'translate');

Tabelle : 22. Ergebnisse

Typ	Beschreibung
Zeichenfolge	Übersetzte Textzeichenfolge.

Das folgende Beispiel zeigt, wie Tabellenfeldreferenzen übergeben werden, um sie mithilfe einer Zusage in die entsprechenden Variablen in einer Zeichenfolge einzubetten.

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

Das folgende Beispiel zeigt, wie Sie „async“ und „ await “ in Ihrer Funktion anstelle einer Zusage verwenden.

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