Helfer: UI Builder

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

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

• Wertskripts der Komponenteneigenschaft
• Skripts für Komponentensichtbarkeit
• Ereignisnutzlastskripts
• UX-Client-Skripteinbindungen

Helpers – Helpers.modal.close(Zeichenfolge modalId)

Schließt das angegebene modale Element auf der aktuellen Seite.

Tabelle : 1. Parameter

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

Tabelle : 2. Rückgaben

Typ	Beschreibung
Keine

Dieses Beispiel zeigt das Schließen eines modalen Elements mit einer Komponenten-ID, die mit endet Warnungsmodal .

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

Helpers – Helpers.modal.Open(Zeichenfolge modalId, Objektoptionen)

Öffnet das angegebene modale Element auf der aktuellen Seite.

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

Tabelle : 3. Parameter

Name	Typ	Beschreibung
modalId	Zeichenfolge	Komponenten-ID des zu öffnenden modalen Elements. Komponenten-IDs werden automatisch generiert, wenn eine Komponente per Drag-and-Drop auf die gezogen wird UI Builder Phase. Sie können die ID auf der Eigenschaftenseite suchen.
Optionen	Objekt	Optional. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
Optionen.Inhalt	Zeichenfolge	Textinhalt für das modale Element.
Optionen.ContentVollbreite	Boolean	Kennzeichnung, die angibt, ob der horizontale Abstand um den Textkörper des Modals entfernt werden soll, um breiteren Inhalt anzupassen. Gültige Werte: Wahr: Entfernen Sie den Abstand. Falsch: Entfernen Sie den Abstand nicht. Standardwert: false
Optionen.headerBezeichnung	Zeichenfolge	Textinhalt für den modalen Header.
Optionen.Größe	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 Vollbildmodus Standard: sm

Tabelle : 4. Rückgaben

Typ	Beschreibung
Keine

Dieses Beispiel zeigt das Öffnen eines modalen Elements mit CA-Einzel-ID, das mit endet Warnungsmodal .

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

Helfer – helpers.navigate.setRouteParams(Object Parameter)

Ü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. Möglicherweise möchten Sie einer URL einen Parameter 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 zu übergeben Ausgewählter Index Einer Registerkartenkomponente, sodass sie in der URL widergespiegelt wird, um diese Registerkarte im Fokus zu halten.

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 Erstellen Sie eine Seite in UI Builder.

Tabelle : 6. Rückgaben

Typ	Beschreibung
Keine

Dieses Codebeispiel zeigt, wie die URL angehängt wird Parameter/selected-tab-index/2 . Beachten Sie, dass der Parameter in der tatsächlichen URL von Camel-Fall in Schlangenfall geändert wird, also SelectedTabIndex Wird Ausgewählter Registerkartenindex .

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

Helpers – Helpers.Navive.to(Zeichenfolgenroute, Objektfelder, Objektparameter, boolesche Umleitung, boolesche PassivNavigation, Zeichenfolge targetRoute)

Navigiert basierend auf der angegebenen Route und den Feldinformationen von einem Bildschirm zum anderen. URL-Änderungen und die jeweiligen Bildschirmladungen werden beobachtet.

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 wird in der URL widergespiegelt, und die URL wird basierend auf erstellt route, fields, Und optionalParamsSpaltenwerte: /<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2> Beispiel: /Record/Incident/12345/params/selectedTabIndex/4
Felder	Objekt	Optional. Schlüssel-Wert-Paare der erforderlichen Parameter. Beispiel: „Felder“ : {'table': 'Incident', 'sysId': '12345'} .
params	Objekt	Optional. Schlüssel-Wert-Paare optionaler Parameter. Beispiel: „Parameter“ : {'selectedTabIndex': 4} .
umleiten	Boolean	Kennzeichnung, die angibt, ob der neueste Verlaufseintrag aus dem Browserverlauf entfernt werden soll. Beispiel: Wenn Sie zu Sites A, B und dann C. wenn navigieren redirectIst auf festgelegt Wahr Beim Navigieren zu C wird der Verlaufseintrag für B entfernt. Im Browserverlauf werden nur A und C angezeigt Gültige Werte: Wahr: Entfernt den neuesten Verlaufseintrag und leitet zur neuesten URL um. Falsch: Entfernt keine Verlaufseinträge. Standardwert: false
passiveNavigation	Boolean	Kennzeichnung, die angibt, ob die Hintergrundnavigation ausgeführt werden soll. Die Hintergrundnavigation ist, wenn eine Seite geöffnet, aber nicht aktiv oder angezeigt wird. Beispiel: Öffnen Sie eine inaktive Registerkarte für die Seite, die jedoch nicht sichtbar ist, aber im Hintergrund geladen wird. Gültige Werte: Wahr: Hintergrundnavigation durchführen. Falsch: Keine Hintergrundnavigation durchführen. Standardwert: false
targetRoute	Zeichenfolge oder Objekt	Unternavigation zu einer Drilldown-, Deep-Link- oder Unterregisterkarte. Wenn auf festgelegt Aktuell , Die aktuelle Route führt eine Unternavigation unter der aktuellen URL durch. Beispiel: Wenn /Record/Incident/123 Ist die aktuelle URL, und der folgende Aufruf erfolgt: Helper.Navigieren.to('Record', {'table': 'Problem', 'sysId': '567'}, {}, falsch, falsch, „aktuell“); Die folgende URL wird generiert: /Record/Incident/123/sub/Record/Problem/567 Hinweis: targetRouteKann entweder eine Zeichenfolge wie sein „Aktuell“ Oder ein Objekt wie NAV_ITEM_SELECTED-Nutzlast der Navigation .

Tabelle : 8. Rückgaben

Typ	Beschreibung
Keine

Dieses Beispiel zeigt, wie Sie zu einer Seite navigieren, die nur übergibt routeParameter.

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

Dieses Beispiel zeigt, wie Sie zu einer Seite navigieren, die übergeben wird routeUnd fieldsParameter.

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

Dieses Beispiel zeigt, wie Sie zu einer Seite navigieren, die übergeben wird route, fields, Und paramsParameter.

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, fehlerhafter Status, Nachricht, und Fehleränderungen.

Statusaktualisierungen werden an WorkspaceChrome oder AppShell gemeldet, je nachdem, was 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 geänderten Modals. hasError: Kennzeichnung (boolesch), die angibt, dass auf der Seite Fehler vorhanden sind. hasUpdate: Kennzeichnung (boolesch), die angibt, dass die Seite aktualisiert wurde. icon: (Zeichenfolge) Name des aktualisierten oder neuen Symbols. isDirty: Kennzeichnung (Boolesch), die angibt, ob die Seite fehlerhaft ist (Werte haben sich geändert). message: (Zeichenfolge) aktualisierte/neue Nachricht. screenKey: (Zeichenfolge) ID des Bildschirms, auf dem der Change aufgetreten ist. Jeder Bildschirm hat einen screenKeyAls Eigenschaft im Bildschirm-Macroponent in sn-Canvas-screen. status: (Zeichenfolge) Statusvorgang für diese Aktion. Dieser Wert muss einer der folgenden Werte sein: Eingefügt, gelöscht, gespeichert oder Geschlossen. title: (Zeichenfolge) aktualisierter/neuer Anzeigentitel. tooltipPreview: (JSON) aktualisierter oder neuer Tooltip. Beispiel: TooltipPreview: { PrimaryTitle, secondaryContent: {} }

Tabelle : 10. Rückgaben

Typ	Beschreibung
Keine

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

Helpers – helpers.snHttp(Zeichenfolgen-url, Objektoptionen)

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

Hinweis:

Es gibt ein bekanntes Problem mit dem Namen von Objekten optionsWerden in der HTTP-Antwort ausgelassen.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

Tabelle : 11. Parameter

Name	Typ	Beschreibung
URL	Zeichenfolge	HTTP-Endpunkt relativ zur Instanz-URL. 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" }
Optionen.Batch	Boolean	Optional. Kennzeichnung, die angibt, ob diese HTTP-Anforderung mit anderen HTTP-Anforderungen an die Instanz kombiniert werden soll. Gültige Werte: Wahr: Anforderung als Teil einer Batch-Anforderung stellen. Falsch: Dedizierte Anforderung stellen. Standardwert: wahr
Optionen.Text	Objekt	Optional. Daten, die als Anforderungstext gesendet werden sollen. Gilt nur für Anforderungsmethoden PLATZIEREN , VERÖFFENTLICHEN , Und PATCH . Elemente im Objekt hängen vom Typ der HTTP-Methode ab. Weitere Informationen finden Sie in den Codebeispielen unten. Standard: {}
Optionen.Header	Objekt	Optional. Zusätzliche HTTP-Anforderungsheader. Zum Beispiel: headers: { "Content-Type": "application/json", "Accept": "application/xml" }
Optionen.Methode	Zeichenfolge	Optional. HTTP-Methode. Gültige Werte: LÖSCHEN GET PATCH POST PUT Standard: GET

Tabelle : 12. Rückgaben

Typ	Beschreibung
Fehler	Objekt, das jeden Fehler beschreibt, der von der REST API zurückgegeben wird. 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	Nachricht, 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 Anforderungsheader enthält. Datentyp: Objekt
Fehler.Optionen.responseHeader	Objekt, das eine Liste aller in der Anforderung gesendeten Antwortheader enthält. Datentyp: Objekt
Fehler.Status	HTTP-Fehlerstatuscode zurückgegeben, z. B. 400, 405 oder 500. Datentyp: Zahl
Fehler.statusText	HTTP-Statusnachricht zurückgegeben, z. B. Ungültige Anforderung . Datentyp: Zeichenfolge
response	Wird zurückgegeben, wenn die HTTP-Anforderung erfolgreich ist. Die Antwort auf die HTTP-Anforderung. Datentyp: Beliebig

Das folgende Beispiel zeigt, wie Sie anrufen SnHttp() 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 Sie anrufen SnHttp() Verwenden Asynchron Und Warten .

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 Sie eine POST-Anforderung einrichten.

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 Sie eine PUT-Anforderung einrichten.

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)

Bricht die Ausführung der Funktion ab, die über einen vorherigen geplant wurde SetIntervall () Rufen Sie an.

Tabelle : 13. Parameter

Name	Typ	Beschreibung
TimeoutId	Anzahl	Eindeutiger Bezeichner der geplanten Funktion, die gelöscht werden soll. Dieser Wert wird von der entsprechenden zurückgegeben SetIntervall () Rufen Sie an.

Tabelle : 14. Rückgaben

Typ	Beschreibung
Keine

Dieses Beispiel zeigt mit ClearInterval() Dient zum Abbrechen eines Zeitvorgangs, der zuvor mit festgelegt wurde SetIntervall () Methode. Diese Funktion kann aufgerufen werden, indem ein Anwender auf klickt Deaktivieren Sie die automatische Aktualisierung Schaltfläche auf einer Seite.

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

Helpers – Helpers.Timing.ClearTimeout(Number timeoutId)

Bricht die Ausführung der Funktion ab, die über einen vorherigen geplant wurde SetTimeout() Rufen Sie an.

Tabelle : 15. Parameter

Name	Typ	Beschreibung
TimeoutId	Anzahl	Eindeutiger Bezeichner der geplanten Funktion, die gelöscht werden soll. Dieser Wert wird von der entsprechenden zurückgegeben SetTimeout() Rufen Sie an.

Tabelle : 16. Rückgaben

Typ	Beschreibung
Keine

Dieses Codebeispiel zeigt, wie ein Timer mit dem angegebenen beendet wird TimeoutId .

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

Helfer – helpers.timing.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 zum nativen JavaScript SetIntervall () Methode: Diese Methode unterstützt die Übergabe einer Codeszeichenfolge zur Auswertung als erstes Argument nicht. 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	Anzahl	Länge des Zeitintervalls zwischen den einzelnen Funktionsausführungen. Einheit: Millisekunden

Tabelle : 18. Rückgaben

Typ	Beschreibung
Anzahl	Eindeutiger Bezeichner des Funktionsausführungsvorgangs. Verwenden Sie diesen Wert in Helpers – Helpers.Timing.ClearInterval(Number timeoutId) Methode, wenn Sie diesen Vorgang abbrechen müssen.

Dieses Codebeispiel zeigt, wie der Zeitstempel auf einer Seite jede Sekunde aktualisiert wird. Diese Funktion kann aufgerufen werden, indem ein Anwender auf klickt Aktivieren Sie die automatische Aktualisierung Schaltfläche auf einer Seite.

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

Helfer – helpers.timing.setTimeout(Function FN, Nummernverzögerung)

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

Im Gegensatz zum nativen JavaScript SetTimeout() Methode: Diese Methode unterstützt die Übergabe einer Codeszeichenfolge zur Auswertung als erstes Argument nicht. Alle zusätzlichen Argumente werden an die Funktion selbst übergeben.

Tabelle : 19. Parameter

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

Tabelle : 20. Rückgaben

Typ	Beschreibung
Anzahl	Eindeutiger Bezeichner des Funktionsausführungsvorgangs. Verwenden Sie diesen Wert in Helpers – Helpers.Timing.ClearTimeout(Number timeoutId) Methode, wenn Sie diesen Vorgang abbrechen müssen.

Dieses Codebeispiel zeigt, wie ein 20-Minuten-Timer festgelegt wird. Sie können diese Funktion einer Schaltfläche zuordnen Erinnern Sie mich in 20 Minuten .

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(Zeichenfolgennachricht, Zeichenfolgentoken)

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

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

Hinweis:

Sie können diese Methode mit einer Zusage oder aufrufen Asynchron 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. Zum Beispiel: helpers.translate('Text {0} {1}', 'to', 'translate');

Tabelle : 22. Rückgaben

Typ	Beschreibung
Zeichenfolge	Übersetzte Textzeichenfolge.

Das folgende Beispiel zeigt, wie Tabellenfeldreferenzen übergeben werden, um 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 die Verwendung Asynchron Und Warten In Ihrer Funktion anstelle einer Zusage.

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