본문으로 건너뛰기
가이드

화면 SDK 사용하기

화면 SDK 사용하기

화면 SDK 사용하기

생성된 화면을 수정하세요

목록은 ListSurface.tsx, 조회·생성·수정 폼은 RecordSurface.tsx에서 시작합니다. 리소스별 타입과 조회 함수는 같은 리소스 폴더에 있습니다.

필요한 요소SDK 컴포넌트
화면 제목과 동작NxPageFrame
폼 구역과 필드NxFormSection, NxFormField
문자열 입력NxTextInput
상세 값 표시NxDetailRow

생성된 파일의 import와 상태 처리 방식을 유지하고 필요한 입력을 추가하세요. 칼럼 추가 예제는 입력·저장·상세·목록을 함께 수정하는 방법을 보여 줍니다.

필드를 추가할 때

  1. 요청·응답 타입을 수정합니다.
  2. 폼의 입력 상태, 초기값, 검증 오류를 연결합니다.
  3. 저장 요청에 값을 포함합니다.
  4. 상세와 목록에도 값을 표시합니다.
  5. 저장 후 다시 열거나 새로고침해서 값이 유지되는지 확인합니다.

기존 동작을 유지하세요

  • API 요청은 생성된 SDK 클라이언트와 조회 함수를 사용하세요.
  • 저장 중 중복 제출, 잘못된 입력, 권한 거부를 처리하세요.
  • 다른 화면으로 이동할 때 미저장 입력 확인을 유지하세요.
  • 비밀값은 화면 번들·조회 응답·폼 초안에 넣지 마세요.
  • 공통 컴포넌트를 썼더라도 좁은 화면과 실제 데이터로 확인하세요.

앱 화면 수정하기 · 앱 테스트

변경한 화면 확인

코드 예시
Shell
npm run build

그다음 샌드박스에서 앱을 여세요. 값을 변경해 저장하고 레코드를 다시 열어 저장 결과를 확인합니다. 잘못된 입력, 접근 거부, 미저장 입력이 있는 상태에서의 이동도 확인하세요. 빌드 성공만으로 이러한 동작이 검증되지는 않습니다.

앱 CSS와 호스트 스타일

생성된 nexiaAppConfig(import.meta.url)은 지연 로딩 화면을 포함해 앱 resources/의 Tailwind 유틸리티 클래스를 수집하고, 생성한 CSS 파일을 nexia-host.json에 기록합니다. 초기화 스타일, 테마 값과 공통 컴포넌트 스타일은 호스트가 제공합니다. 공개된 @nexia/sdk/theme.css 별칭은 유틸리티 이름을 호스트 변수에 연결합니다. 예를 들어 bg-surface, text-text-primary, border-border-subtle, rounded-control, p-inset을 사용할 수 있습니다. 앱에 설치된 버전이 기준입니다. 실제 값은 호스트 테마에 따라 달라지므로 현재 색상을 고정하거나 호스트 토큰을 재정의하지 마세요.

코드 예시
TSX
<section className="rounded-control border border-border-subtle bg-surface p-inset text-text-primary">
  앱에서 관리하는 내용
</section>

앱 CSS는 지원되는 호스트 포털을 포함한 해당 앱의 영역으로 제한되며 Shadow DOM은 아닙니다. 그 영역 안에서는 CSS 우선순위에 따라 공통 컴포넌트까지 선택자가 적용될 수 있습니다. 호스트 스타일도 별도의 적용 순서가 있습니다. 오버라이드가 불가능하거나 항상 보장된다고 가정하지 말고, 공통 컴포넌트의 공개 props와 배치 슬롯을 우선 사용하세요. 사용자 정의 선택자는 앱이 소유한 요소로 한정하고 공통 컴포넌트 내부 구조, 전역 초기화 스타일, 호스트 테마 변수를 변경하지 마세요. 앱 선택자가 다른 앱이나 Shell을 꾸미면 안 됩니다.

호스트는 전역 @import, @font-face, 호환되지 않는 @property 등록, 지원하지 않는 CSS 규칙과 스타일시트 출처 밖의 리소스(지원되는 이미지 data URL 제외)를 거부합니다. 브라우저는 CSS @scope를 지원해야 합니다. 호환되지 않는 CSS는 앱 로딩을 막을 수 있으므로 대상 호스트와 브라우저에서 확인하세요. 변경 후 npm run build를 실행하고 샌드박스에서 포털과 밝은·어두운 테마를 포함해 확인합니다. 로컬 빌드 성공만으로 배포 호스트와의 호환성이 증명되지는 않습니다.

정확한 컴포넌트 props·hook 찾기

설치된 패키지가 해당 버전의 기준입니다. Core 저장소 없이 편집기의 정의로 이동을 사용하거나 npm install 후 node_modules/@nexia/sdk/dist/index.d.ts·host.d.ts와 그 상대 경로 선언을 읽을 수 있습니다. Core 내부 컴포넌트 경로를 앱 import에 복사하지 마세요.

작업공개 host API·타입
페이지 소유 조직 필터useOrganizationListScope, NxPageFrame.organizationScope
생성 대상·저장 소유자생성된 select/stored 모드의 NxResourceFormLegalEntityField
목록·레코드 화면생성된 ResourceTable·resource contract·ListSurface·RecordSurface 연결 유지
보드·캘린더·스케줄러·일정ResourceBoard, NxCalendar, NxResourceScheduler, ResourceSchedule; projection 가이드
프로필 위젯ProfileSlotPropsV2; 슬롯 가이드
결재 폼ApprovalBusinessFormSlotPropsV2, approvalComposerBusinessFormRegistry; 결재 가이드
projection 이벤트 후 갱신useResourceProjectionChange; 동일하게 인가된 API로 재조회

타입·독립 계약은 @nexia/sdk, 호스트 연결 렌더러·hook은 @nexia/sdk/host에서 가져옵니다. 생성된 앱 범위 client·host 등록을 따르고 별도 React root나 무관한 router를 추가하지 않습니다.

mutation에서는 생성된 query key·조직 문맥을 유지하고 중복 제출 방지·서버 필드 오류 표시·성공 후 관련 레코드 갱신을 연결합니다. 거절되면 오류 배너 아래에 이전 보호 데이터를 남기지 말고 지우세요. 빈 상태는 성공했지만 데이터가 없는 결과이며 로딩·권한 거절·네트워크 실패와 구분합니다.

앱 통신과 호스트 경로

SDK의 api는 호출한 앱에 연결됩니다. 개발 프레임과 설치된 앱에는 같은 경로 정책이 적용됩니다. 범위가 있는 선택 목록에는 조직 대상 및 Resource Reference 훅을 우선 사용하세요. 지원하는 Core 호스트 경로도 기존 권한을 검사합니다. 테넌트 전체 조직 조회·생성, 중복 인물 조회, 사용자 생성·초대, 본인 프로필이 해당하며 임의의 Core API 접근을 허용하지 않습니다. 메일 전송 제한도 유지됩니다.

sendUserInvitation과 useDataMigrationBackgroundOperation도 앱에 연결된 통신을 사용합니다. 백그라운드 작업은 생성한 앱과 사용자 모두 일치해야 조회할 수 있습니다. APP_HOST_ROUTE_UNAVAILABLE은 지원하지 않는 경로라는 뜻이며 서버의 업무 권한 거부와 구분해야 합니다. 전역 HTTP 클라이언트로 우회하지 마세요. 실제 앱 프레임이나 설치 화면을 통해 검증하세요. 모의 응답이나 직접 HTTP 요청만으로 이 경계를 검증할 수는 없습니다. 해당 Core 호스트 수정이 적용되어야 하며 SDK 업데이트만으로 서버 기능이 추가되지는 않습니다.

공통 문서 필드 선택창

@nexia/sdk/host의 NxDocumentDataFieldPicker는 전자서명·업무프로세스와 같은 열 방식 탐색기를 사용합니다. open, onClose, title, loadPage(filters), onSelect(item)를 전달합니다. 앱의 인가된 백엔드가 고정된 용도·대상 유형으로 DocumentDataHost::catalog를 호출해야 합니다. 브라우저 입력으로 더 넓은 권한의 용도를 선택하게 하지 않습니다.

loadPage에는 stage: apps|sources|fields, 선택적인 app_key, source_key, source_version, q, offset, limit이 전달됩니다. {data, next_offset}을 반환하고, 직접 입력처럼 앱이 소유하는 요청 값은 local_fields: [{source, label_key}]로 추가할 수 있습니다. 메타데이터 항목은 앱·소스 이름, 필드 정의, 가상 예시와 정확한 필드 binding을 포함합니다. 선택 결과는 그 항목 또는 직접 입력의 {local_source, label}입니다. isDisabled(item)으로 문서 배치 제약을 표시하고 저장 시 서버에서도 재검사합니다.

각 단계에 필요한 목록만 읽고 서버 검색·더 보기·재시도를 지원하며, 뒤늦게 도착한 이전 요청은 무시합니다. 일반 값·날짜·리소스 표시명 필드를 지원하고 복합 값에는 별도 문서 렌더러가 필요합니다. 이름이나 목록 위치 대신 반환된 binding을 저장하세요. React SDK 0.8.13·Core 0.8.152 이상을 함께 적용해야 합니다. 이미 인가된 메모리 내 목록에는 @nexia/sdk의 buildAppCatalogTree로 앱 분류 → 앱 → 항목 구조를 공유할 수 있습니다. 이 함수는 데이터 조회나 권한 부여를 수행하지 않습니다.

독립 조회 필드

레코드 조회 팝업을 여는 필드는 @nexia/sdk/host의 NxLookupField를 사용합니다. NxCombobox는 팝오버 목록 선택만 담당합니다. 이전 초안의 NxCombobox presentation="dialog"와 조회 전용 속성을 제거합니다. React SDK 0.8.13·Core 0.8.152 이상에서 사용할 수 있습니다. 두 버전을 함께 적용하고 이전 대화상자 전용 콤보박스 속성은 아래 표에 따라 옮기세요.

NxLookupField는 적용된 값을 표시하고 공통 NxLookupDialog를 엽니다. 문자열·숫자 값, 단일·다중 선택, 등록 후 복귀, 새로고침과 선택 항목 칩을 지원합니다. 단일 선택은 즉시 적용하고 닫습니다. 다중 선택은 적용 전까지 임시 상태로 유지하며 onChange(values, options)가 선택된 값과 전체 선택 옵션을 반환합니다. 모두 해제하면 ([], [])를 반환하고, 취소하면 기존 적용값을 유지합니다.

리소스가 권한이 적용된 options, columns, 선택적 getCells(또는 옵션의 cells), filters, advancedFilters, activeFilterCount, actions를 제공합니다. 추가 버튼은 actions에 넣으며 적용·취소는 공통 컴포넌트가 담당합니다. API·권한·필터 상태·입력 지연·서버 정렬은 리소스가 담당합니다. sort/onSortChange는 정렬 가능한 헤더를 연결하며 현재 페이지를 자체적으로 정렬하지 않습니다. createAction과 resourceCreateContinuation은 기존 등록 후 복귀 계약을 유지합니다.

서버 페이지에는 pagination={{ page, pageSize, total, onPageChange }}를 전달합니다. 생략하면 전달받은 전체 목록만 검색하고 25개씩 표시하며 누락된 서버 데이터를 추가 조회하지 않습니다. 제어 검색은 searchValue/onSearchChange를 사용하고 범위·필터·검색어가 바뀌면 리소스에서 서버 페이지를 초기화합니다. 제어 검색은 닫을 때 유지하고 내부 검색은 초기화합니다. open/onOpenChange로 열려 있는 동안만 조회를 활성화할 수 있습니다. loading, error, onRetry로 조회 중 상태와 복구를 연결합니다. 초기 페이지에 없는 적용값은 selectedOptions로 전달합니다. 이후 페이지가 바뀌어도 적용된 이름을 보존하며 값은 외부 상태를 따릅니다. 범위가 바뀌어 권한이 사라진 선택은 리소스에서 해제해야 합니다.

페이지 범위 선택기가 mode="legal-entity-operating-unit-list"이면 NxOrganizationTargetSelector에 operatingUnitPicker="lookup"을 지정해 운영조직 부분만 조회 팝업으로 표시할 수 있습니다. 법인 선택은 유지되며, 조회 건수에 따라 전환하지 않고 페이지에서 UI를 고정합니다. 정확한 법인·조직 쌍, 권한 검사와 URL 쿼리 처리는 유지합니다. 이 속성을 사용하려면 대응하는 SDK와 Core 호스트가 필요하며, 생략하면 기존 선택기를 사용합니다.

이전 초안 속성NxLookupField 속성
presentation="dialog"제거; 항상 조회 팝업 사용
lookupColumns / lookupCellscolumns / getCells
lookupFilters / lookupAdvancedFiltersfilters / advancedFilters
lookupActiveFilterCount / lookupErroractiveFilterCount / error
다중 onChange(values, changedOption)onChange(values, selectedOptions)

트리거를 직접 구성하는 경우에는 NxLookupDialog를 사용할 수 있습니다. 현재 페이지 전체 선택은 서버 검색 결과 전체 선택과 다릅니다.

권한이 있는 검색 결과 전체 선택

React SDK 0.8.18·Core 0.8.182부터 다중 선택에 전체 결과 로더를 지정할 수 있습니다. 페이지 분할과 제어형 검색을 사용하지 않는 완전한 로컬 NxLookupField 목록은 자동으로 지원합니다. 서버 페이지를 사용하면 NxLookupField에 selectAllOptions: { scopeKey, load }를 전달하고, NxLookupDialog를 직접 구성하면 selectAllRows: { scopeKey, load }를 전달하세요.

  • scopeKey는 현재 검색·필터·접근 가능한 조직 범위를 식별하는 문자열입니다. 범위가 달라지면 값을 변경해 이전 조회를 취소하세요. 더 이상 권한이 없는 기존 선택은 소유 화면에서도 해제해야 합니다.
  • load(signal: AbortSignal)은 모든 서버 페이지에 걸쳐 권한이 있는 검색 결과 전체를 옵션 또는 행으로 반환합니다. 요청에 취소 신호를 전달하고 실패하거나 결과가 불완전하면 오류를 반환하세요. 현재 페이지만 반환하면 나머지 결과가 누락됩니다.
  • 호스트는 선택 가능한 결과를 임시 선택에 합칩니다. 적용하면 선택을 확정하고, 취소하면 기존 적용값을 유지합니다. 조회 실패·취소 시 임시 선택을 유지합니다. 합친 결과가 maxSelection을 넘으면 일부만 선택하지 않고 한도를 안내합니다.

표의 실제 표시 열 확인

React SDK 0.8.18·Core 0.8.182에서 ResourceTable에 onVisibleColumnsChange(keys: string[])를 전달합니다. 저장된 표시 설정을 반영한 데이터 열 키를 받으며, 호스트가 추가한 생성일·수정일 열도 포함합니다. 작업 열은 제외합니다. 불필요한 반복 호출을 피하도록 콜백 참조를 유지하세요.

앱은 이 키를 표시 열에 대한 서버 검색에 활용할 수 있습니다. 서버에서 열 키를 검증하고 행·필드 권한을 검사한 뒤 페이지를 나누기 전에 검색을 적용하세요. 열을 숨겼다는 사실이 접근 권한을 결정하지는 않습니다.

여러 페이지의 전체 선택, 적용·취소, 검색 조건 변경, 조회 실패와 선택 한도를 확인하세요. 저장된 표시 열 설정을 바꾸고, 권한이 있는 필드를 대상으로 페이지 분할 전에 검색하는지도 확인합니다.

버전별 변경과 타입은 React SDK 0.8.18 변경 내역과 해당 버전 패키지를 참고하세요.

표에서 시작하는 내보내기

React SDK 0.8.14·Core 0.8.159 이상에서 지원합니다.

ResourceTable에 transferMeta를 전달하면 표시 중인 데이터 열이 공통 내보내기 화면에 전달됩니다. ResourceTableColumn.exportKey는 기존 UI 열 키를 내보내기 스키마 키에 연결하며, 생략하면 key를 사용합니다. 작업 열은 제외하고 선택 순서를 유지합니다. React SDK 0.8.17·Core 0.8.170에서는 권한으로 제외된 열을 안내하고 스키마에 없는 열에는 경고를 표시합니다. 사용 가능한 허용 열 중 선택한 열만 내보내며, 한 개 이상이 선택돼 있어야 합니다.

검증한 필터 조건을 내보내기 작업 URL에 포함하세요. 호스트는 search, sort, filter[...], table_filter[...]를 전달하고 페이지 번호는 제외합니다. 앱의 내보내기 소스는 필터를 다시 검증하고 표와 같은 권한·조건을 모든 페이지에 적용해야 합니다. 이 선택적 열 매핑에는 대응하는 Core 호스트 구현이 필요합니다.

표 메뉴 작업과 제외된 필드

React SDK 0.8.17의 선택 항목 ResourceListToolbarConfig.moreItems (NxDropdownMenuItem[])로 기본 메뉴에 앱 작업을 추가합니다. 내보내기·인쇄·열 설정을 유지하려면 대응하는 Core 0.8.170 호스트를 사용하세요. 기존 more 슬롯도 계속 지원합니다.

전송 메타데이터의 export_restricted_columns: [{ key, label }]로 필드 권한에 따른 제외 사유를 안내할 수 있습니다. 호스트는 해당 필드를 제외하고 지원되지 않는 스키마 필드를 경고하며 허용된 열 선택을 유지합니다. 내보내기 조회는 모든 페이지에서 필터와 행·필드 권한을 다시 확인해야 합니다. 실제 사용자로 허용·제외·미지원 열과 메뉴 작업을 검증하세요. React SDK 산출물과 가져오기·내보내기 가이드를 확인하세요.

날짜 필터와 레코드별 인쇄

React SDK 0.8.14·Core 0.8.159부터 meta.list_schema.filterable 항목에 kind: "dateRange", multiple: false, options: []를 선언할 수 있습니다. 값은 YYYY-MM-DD..YYYY-MM-DD 문자열 하나이며 양쪽 날짜를 각각 생략할 수 있습니다. URL 상태를 유지하고 날짜 순서를 검증하며 페이지 처리·내보내기 전에 같은 권한·날짜 조건을 적용하세요. kind를 생략하면 기존 범주 선택을 유지합니다. 일반 범주 필터는 multiple: true를 명시하세요.

React SDK 0.8.15는 리소스 표·전송 속성에 recordPrint: { label, title, columnKeys }를 추가합니다. 허용된 열의 안정적인 키와 호환 Core 호스트를 사용하세요. Core 0.8.173에서 지원합니다. 목록 인쇄와 별도의 레코드 구성이며 숨긴 필드를 인쇄할 권한을 부여하지는 않습니다. 실제 사용자로 인쇄·내보내기 결과와 빈 결과·실패 상태를 확인합니다.

React SDK 0.8.14 변경 내역, 0.8.15 변경 내역, 리소스 데이터 가져오기·내보내기를 참고하세요.

읽기 전용 POST 조회

React SDK 0.8.16·Core 0.8.167부터 @nexia/sdk 또는 @nexia/sdk/host의 NEXIA_READ_ONLY_HEADER를 사용할 수 있습니다. 상태를 변경하지 않는 POST에만 선언하세요. 다음 설정을 기존 앱 미리보기 api.post 호출의 세 번째 인자로 전달하세요. 원래 호출의 경로와 입력은 유지합니다.

코드 예시
TSX
import { NEXIA_READ_ONLY_HEADER } from '@nexia/sdk/host';

const previewRequestConfig = {
    headers: { [NEXIA_READ_ONLY_HEADER]: 'true' },
    timeout: 30_000,
};

호스트는 읽기 요청으로 처리하며 통신 실패를 미확정 저장 대기 대신 호출자에게 전달합니다. 이 선언이 변경 핸들러를 읽기 전용으로 바꾸거나 권한 거부를 해제하지는 않습니다. 서버 검증·권한 검사를 유지하고 저장 요청에는 사용하지 마세요. 업무 데이터를 바꾸지 않는 조건에서 정상 응답, 요청 차단 후 오류 표시, 차단 해제 후 재조회를 확인합니다. React SDK 선언과 Core 읽기 처리를 참고하세요.

발행된 React 패키지 · 공통 문서 데이터

순서가 있는 단계 편집기 (미출시)

@nexia/sdk/host에서 NxStageBuilder를 가져옵니다. 고정된 고유 stageIds, renderStage(index), onAdd(), onRemove(index), onMove(from, to)를 전달합니다. 호출 화면이 배열을 변경하며 두 인덱스는 현재 순서 기준이고 to는 최종 위치입니다. 배열 인덱스를 ID로 쓰지 마세요. 호스트는 번호, 포인터 정렬, 키보드 정렬 (Space/Enter로 잡기, 방향키 이동, Space/Enter로 놓기, Escape 취소), 추가·삭제를 제공합니다.

minCount 기본값은 0이고 maxCount로 추가 개수를 제한합니다. disabled는 편집을 막고 readOnly는 편집 버튼을 숨깁니다. 포털을 사용하는 입력을 포함해 단계 본문의 읽기 전용 표현은 호출 화면에서 구성하세요. labels로 add, empty, stage(position), drag(stage), remove(stage), dragInstructions를 바꿀 수 있습니다. 제목·설명·카드는 바깥에서 조합합니다. 검증·저장·권한·업무 규칙은 앱이 담당합니다. 이 미출시 API를 사용하려면 대응하는 Core 호스트와 React SDK를 함께 적용해야 합니다. 기존 출시 버전 제약만으로 이 API가 제공되지는 않습니다.

원본 위치: docs/developers/content/ko/app-sdk/frontend-host-contracts.md