도우미 - UI 빌더

도우미 - helpers.modal.close(문자열 modalId)

현재 페이지에서 지정된 모달을 닫습니다.

표 1. 매개변수
이름	유형	설명
modalId	문자열	모달 구성요소 닫을 모달의 ID입니다. 구성요소 ID는 구성요소를 스테이지에서 UI 빌더 드래그 앤 드롭할 때 자동으로 생성됩니다. ID는 속성 페이지에서 찾을 수 있습니다.

표 2. 반환
유형	설명
없음

이 예는 alert-modal로 끝나는 구성요소 ID가 있는 모달을 닫는 것을 보여줍니다.

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

helpers - helpers.modal.open(문자열 modalId, 객체 옵션)

현재 페이지에서 지정된 모달을 엽니다.

페이지 내에서 한 번에 하나의 모달만 표시할 수 있습니다. 모달이 현재 열려 있는 경우 이 메서드를 호출하면 기존 모달이 숨겨지고 새 모달이 나타납니다.

표 3. 매개변수
이름	유형	설명
modalId	문자열	열 모달의 구성요소 ID입니다. 구성요소 ID는 구성요소를 스테이지에서 UI 빌더 드래그 앤 드롭할 때 자동으로 생성됩니다. ID는 속성 페이지에서 찾을 수 있습니다.
옵션	객체	옵션입니다. `"options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }`
옵션.콘텐츠	문자열	모달의 텍스트 컨텐츠입니다.
options.contentFullWidth (옵션.contentFullWidth)	부울	더 넓은 컨텐츠에 맞추기 위해 모달 본문 주변의 가로 패딩을 제거할지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 패딩을 제거합니다. false: 패딩을 제거하지 않습니다. 기본값: false
options.headerLabel	문자열	모달 헤더의 텍스트 컨텐츠입니다.
옵션.크기	문자열	모달 컨테이너의 크기입니다. 대부분의 크기는 화면 크기가 작을 때 뷰포트를 채우기 위해 자동으로 확장됩니다. 유효한 값은 다음과 같습니다. sm MD Lg 전체 화면 기본값: sm

표 4. 반환
유형	설명
없음

이 예는 alert-modal로 끝나는 ca omponent ID를 사용하여 모달을 여는 방법을 보여줍니다.

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

helpers - helpers.navigate.setRouteParams(Object params)

지정된 매개변수를 같은 페이지의 다른 구성요소에 전달합니다.

URL에 매개 변수를 추가하려는 모든 페이지 구성 요소에서 이 메서드를 사용합니다. 다른 구성요소가 해당 매개변수가 변경될 때 해당 매개변수의 현재 값을 알아야 반응할 수 있도록 URL에 매개변수를 추가할 수 있습니다. 예를 들어 이 메서드를 사용하여 탭 구성 요소의 selectedIndex 를 전달하여 URL에 반영하여 해당 탭에 포커스를 부여합니다.

표 5. 매개변수
이름	유형	설명
매개변수	객체	다른 구성요소에 전달할 선택적 매개변수의 키-값 쌍입니다. 이것은 기본 값만 있는 단순하고 평평한 개체여야 합니다. 배열 또는 개체 참조는 무시되고 URL에 추가되지 않습니다. 지정된 모든 키는 경로 구성에서 선택적 매개 변수의 일부여야 하며, 그렇지 않으면 무시됩니다. 선택적 매개변수에 대한 자세한 내용은 UI 빌더에서 페이지 생성을 참조하십시오.

표 6. 반환
유형	설명
없음

이 코드 예제에서는 URL params/selected-tab-index/2를 추가하는 방법을 보여 줍니다. 실제 URL의 매개 변수는 카멜식 대/소문자에서 뱀 대/소문자로 변경되므로 selectedTabIndex 는 selected-tab-index가 됩니다.

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

helpers - helpers.navigate.to(문자열 경로, 객체 필드, 객체 매개변수, 부울 리디렉션, 부울 passiveNavigation, 문자열 targetRoute)

지정된 경로 및 필드 정보에 따라 한 화면에서 다른 화면으로 이동합니다. URL이 변경되고 각 화면 로드가 관찰됩니다.

표 7. 매개변수
이름	유형	설명
경로	문자열	경로의 이름입니다. UX 앱 경로(sys_ux_app_route.list)에서 유효한 항목이어야 합니다. 이 값은 URL에 반영되며, fieldsoptionalParams URL은 route`/<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2>` 예: `/record/incident/12345/params/selectedTabIndex/4`
필드	객체	옵션입니다. 필수 매개변수의 키-값 쌍입니다. 예: `'fields' : {'table': 'incident', 'sysId': '12345'}`.
매개변수	객체	옵션입니다. 선택적 매개변수의 키-값 쌍입니다. 예: `'params' : {'selectedTabIndex': 4}`.
redirect	부울	브라우저 이력에서 최신 이력 항목을 제거할지 여부를 나타내는 플래그입니다. 예를 들어 사이트 A, B, C로 이동하는 경우입니다. redirect C로 이동하는 동안 `true` 로 설정하면 B에 대한 히스토리 항목이 제거됩니다. 브라우저 기록에는 A와 C만 표시됩니다. 유효한 값은 다음과 같습니다. true: 최신 기록 항목을 제거하고 최신 URL로 리디렉션합니다. false: 기록 항목을 제거하지 않습니다. 기본값: false
passiveNavigation	부울	백그라운드 탐색을 수행할지 여부를 나타내는 플래그입니다. 배경 탐색은 페이지가 열려 있지만 활성화되지 않았거나 표시되지 않을 때입니다. 예를 들어 페이지에 대한 비활성 탭을 열었지만 표시되지 않고 백그라운드에 로드됩니다. 유효한 값은 다음과 같습니다. true: 백그라운드 탐색을 수행합니다. false: 백그라운드 탐색을 수행하지 않습니다. 기본값: false
targetRoute	문자열 또는 객체	드릴다운, 딥 링크 또는 하위 탭으로의 하위 탐색 `current`로 설정하면 현재 경로는 현재 URL에서 하위 탐색을 수행합니다. 예를 들어, `/record/incident/123` 이 현재 URL이고 다음 호출이 이루어지는 경우: `helper.navigate.to('기록', {'테이블': '문제', 'sysId': '567'}, {}, 거짓, 거짓, '현재');` 다음 URL이 생성됩니다. `/record/incident/123/sub/record/problem/567` 주: targetRoute`'현재'`와 같은 문자열이거나 `탐색 NAV_ITEM_SELECTED 페이로드`와 같은 객체일 수 있습니다.

표 8. 반환
유형	설명
없음

이 예제에서는 매개 변수만 route 전달하는 페이지로 이동하는 방법을 보여 줍니다.

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

이 예제에서는 and fields 매개 변수를 전달하는 route 페이지로 이동하는 방법을 보여 줍니다.

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

이 예제에서는 , fields및 params 매개 변수를 전달하는 route페이지로 이동하는 방법을 보여 줍니다.

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

도우미 - helpers.screen.updateStatus(개체 statusObj)

페이지에서 제목, 아이콘, 더티 상태, 메시지 및 오류 변경과 같은 상태 업데이트를 보고할 수 있습니다.

상태 업데이트는 WorkspaceChrome 또는 AppShell(외부 계층이 무엇이든 간에)에 보고되고 호스트 역할을 합니다.

표 9. 매개변수
이름	유형	설명
상태Obj	객체	컨텐츠가 업데이트되었음을 보고하기 위해 현재 페이지로 보낼 페이로드입니다. 유효한 값은 다음과 같습니다. dirtyModalId:(문자열) 변경된 모달의 ID입니다. hasError:(부울) 페이지에 오류가 있음을 나타내는 플래그입니다. hasUpdate:(부울) 페이지가 업데이트되었음을 나타내는 플래그입니다. icon:(문자열) 업데이트된 아이콘 또는 새 아이콘의 이름입니다. isDirty:(부울) 페이지가 더티한지 여부를 나타내는 플래그입니다(값이 변경됨). message: (문자열) 업데이트된/새 메시지입니다. screenKey:(문자열) 변경이 발생한 화면의 ID입니다. 모든 화면에는 sn-canvas-screen 내부의 화면 macroponent에 대한 속성으로 있습니다 screenKey . status:(문자열) 이 작업에 대한 상태 작업입니다. 이 값은 삽입됨, 삭제됨, 저장됨 또는 닫힘 중 하나여야 합니다. title:(문자열) 업데이트된/새로운 표시 제목입니다. tooltipPreview: (JSON) 도구 설명이 업데이트되거나 새로워졌습니다. 예: `tooltipPreview : { primaryTitle, secondaryContent: {} }`

표 10. 반환
유형	설명
없음

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

도우미 - helpers.snHttp(문자열 URL, 개체 옵션)

인스턴스에 HTTP 요청을 ServiceNow 하고 그 결과와 함께 promise를 반환합니다.

주:

명명된 options 개체가 HTTP 응답에서 생략되는 알려진 문제가 있습니다.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

표 11. 매개변수
이름	유형	설명
URL	문자열	인스턴스 URL을 기준으로 하는 HTTP 엔드포인트입니다. 예를 들어 `/api/now/table/incident` 또는 `/api/now/table/incident/a83820b58f723300e7e16c7827bdeed`입니다.
옵션	객체	HTTP 요청의 내용을 설명합니다. `"options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }`
옵션.배치	부울	옵션입니다. 이 HTTP 요청을 인스턴스에 대한 다른 HTTP 요청과 함께 배치해야 하는지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 일괄 처리 요청의 일부로 요청합니다. false: 전용 요청을 만듭니다. 기본값: true
옵션.본문	객체	옵션입니다. 요청 본문으로 보낼 데이터입니다. 요청 메서드 `PUT`, `POST` 및 `PATCH`에만 적용할 수 있습니다. 개체의 요소는 HTTP 메서드의 형식에 따라 달라집니다. 자세한 내용은 아래 코드 예제를 참조하세요. 기본값 : `{}`
옵션.헤더	객체	옵션입니다. 추가 HTTP 요청 헤더입니다. 예: `headers: { "Content-Type": "application/json", "Accept": "application/xml" }`
옵션.방법	문자열	옵션입니다. HTTP 메소드를 사용할 수 있습니다. 유효한 값은 다음과 같습니다. 삭제 임포트 패치 게시 넣기 기본값: GET

표 12. 반환
유형	설명
오류	REST API에서 반환되는 오류를 설명하는 객체입니다. 데이터 유형: 객체 `"error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }`
오류.데이터	HTTP API에서 반환된 응답입니다. 데이터 형식: REST API에 의해 정의됨
오류.메시지	HTTP 요청을 처리하려고 할 때 발생한 오류를 설명하는 메시지입니다. 주: 이 매개 변수가 항상 반환되는 것은 아닙니다. 데이터 유형: 문자열
오류.옵션	원래 HTTP 요청을 설명합니다. 데이터 유형: 객체 `"options": { "headers": {Object}, "responseHeader": {Object} }`
error.options.headers	요청에서 전송된 모든 요청 헤더의 목록을 포함하는 객체입니다. 데이터 유형: 객체
error.options.responseHeaders	요청에서 전송된 모든 응답 헤더의 목록을 포함하는 객체입니다. 데이터 유형: 객체
오류.상태	반환된 HTTP 오류 상태 코드(예: 400, 405 또는 500)입니다. 데이터 유형: 숫자
error.statusText (오류.상태 텍스트)	`잘못된 요청`과 같은 반환된 HTTP 상태 메시지입니다. 데이터 유형: 문자열
response	HTTP 요청이 성공하면 반환됩니다. HTTP 요청에 대한 응답입니다. 데이터 유형: 모두

다음 예제에서는 promise를 반환하는 snHttp() 를 호출하는 방법을 보여 줍니다.

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

다음 예제에서는 async 및 await를 사용하여 snHttp()를 호출하는 방법을 보여 줍니다.

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

다음 예제에서는 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
    });
}

다음 예제에서는 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.timing.clearInterval(Number timeoutId)

이전 setInterval() 호출을 통해 예약된 함수의 실행을 취소합니다.

표 13. 매개변수
이름	유형	설명
timeoutId입니다.	번호	지울 예약된 기능의 고유 식별자입니다. 이 값은 해당 setInterval() 호출에 의해 반환됩니다.

표 14. 반환
유형	설명
없음

이 예제에서는 clearInterval() 을 사용하여setInterval() 메서드를 사용하여 이전에 설정된 타이밍 작업을 취소하는 방법을 보여 줍니다. 이 함수는 사용자가 페이지에서 자동 새로 고침 사용 안 함 버튼을 클릭하여 호출할 수 있습니다.

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

도우미 - helpers.timing.clearTimeout(Number timeoutId)

이전 setTimeout() 호출을 통해 예약된 함수의 실행을 취소합니다.

표 15. 매개변수
이름	유형	설명
timeoutId입니다.	번호	지울 예약된 기능의 고유 식별자입니다. 이 값은 해당 setTimeout() 호출에 의해 반환됩니다.

표 16. 반환
유형	설명
없음

이 코드 예제에서는 지정된 timeoutId를 사용하여 타이머를 종료하는 방법을 보여 줍니다.

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

helpers - helpers.timing.setInterval(함수 fn, 숫자 지연)

지정된 지연 값을 함수 호출 사이의 간격으로 사용하여 지정된 기능을 반복적으로 실행합니다.

기본 JavaScript setInterval() 메서드와 달리 이 메서드는 첫 번째 인수로 평가할 코드 문자열 전달을 지원하지 않습니다. 추가 인수는 함수 자체에 전달됩니다.

표 17. 매개변수
이름	유형	설명
에프엔(fn)	기능	반복적으로 실행하는 함수입니다.
지연	번호	각 기능 실행 사이의 시간 간격 길이입니다. 단위: 밀리초

표 18. 반환
유형	설명
번호	함수 실행 작업의 고유 식별자입니다. 이 작업을 취소해야 하는 경우 메서드에서 도우미 - helpers.timing.clearInterval(Number timeoutId) 이 값을 사용합니다.

이 코드 예제에서는 1초마다 페이지의 타임스탬프를 새로 고치는 방법을 보여 줍니다. 이 함수는 사용자가 페이지에서 자동 새로 고침 사용 버튼을 클릭하여 호출할 수 있습니다.

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.timing.setTimeout(함수 fn, 숫자 지연)

지정된 지연 후 지정된 기능을 실행합니다.

기본 JavaScript setTimeout() 메서드와 달리 이 메서드는 첫 번째 인수로 평가할 코드 문자열 전달을 지원하지 않습니다. 추가 인수는 함수 자체에 전달됩니다.

표 19. 매개변수
이름	유형	설명
에프엔(fn)	기능	실행할 함수입니다.
지연	번호	지정된 함수를 호출하기 전에 대기할 시간의 길이입니다. 단위: 밀리초

표 20. 반환
유형	설명
번호	함수 실행 작업의 고유 식별자입니다. 이 작업을 취소해야 하는 경우 메서드에서 도우미 - helpers.timing.clearTimeout(Number timeoutId) 이 값을 사용합니다.

이 코드 예제에서는 20분 타이머를 설정하는 방법을 보여 줍니다. 이 함수를 20분 후에 알림 버튼과 연결할 수 있습니다.

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(문자열 메시지, 문자열 토큰)

현재 사용자의 세션 언어에 따라 지정된 메시지를 비동기적으로 검색하고 번역합니다.

이 메서드를 번역 api - setState(String, stateParam, Any value) 된 값을 페이지의 다른 필드에 바인딩할 수 있습니다.

주:

promise 또는 async 및 await를 사용하여 이 메서드를 호출할 수 있습니다. 아래 코드 예제에서는 두 구현을 모두 보여 줍니다.

표 21. 매개변수
이름	유형	설명
메시지	문자열	번역할 메시지입니다.
토큰	문자열	옵션입니다. 문자열 변수를 바꾸는 데 사용할 매개변수 목록이며 콤마로 구분됩니다. 예: `helpers.translate('Text {0} {1}', 'to', 'translate');`

표 22. 반환
유형	설명
문자열	번역된 텍스트 문자열입니다.

다음 예제에서는 promise를 사용하여 문자열의 해당 변수에 포함하기 위해 테이블 필드 참조를 전달하는 방법을 보여 줍니다.

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

다음 예제에서는 promise 대신 함수에서 async 및 await 를 사용하는 방법을 보여 줍니다.

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