본문으로 건너뛰기

시작하기

이 페이지에서는 앱 루트에 Provider를 연결하고, ZS-ui 컴포넌트와 오버레이를 사용하는 첫 화면까지 구성합니다.

완료하면 할 수 있는 것​

  • 테마가 적용된 ZSContainer와 ZSText로 화면을 구성합니다.
  • ZSBlockButton에서 useOverlay().showAlert()를 호출합니다.
  • Theme, UI 컴포넌트, Overlay 상세 문서로 이어서 탐색합니다.

1. 설치​

ZS-ui와 필수 peer 의존성을 함께 설치합니다. 버전 범위는 패키지 package.json의 peerDependencies를 따릅니다(Expo SDK 57, React Native 0.86 이상).

npx expo install @0610studio/zs-ui \
  @react-native-async-storage/async-storage @shopify/react-native-skia \
  expo-navigation-bar expo-router react-native-gesture-handler \
  react-native-reanimated react-native-worklets \
  react-native-safe-area-context react-native-svg

react-native-gesture-handler는 ZSCalendar를 쓰지 않아도 필요합니다. 배포물이 CommonJS 번들이라 tree-shaking이 없어, 라이브러리를 import하는 순간 모든 모듈이 평가되기 때문입니다. 앱 루트는 GestureHandlerRootView로 감쌉니다. react-navigation 같은 제스처 기반 라이브러리를 이미 쓰고 있다면 대부분 충족되어 있습니다.

Android 폴더블 설정​

폴더블 기기를 접고 펼 때 Android가 Activity를 다시 만들지 않도록 패키지의 config plugin을 등록하고 네이티브 프로젝트를 다시 생성합니다(npx expo prebuild). 플러그인은 MainActivity의 configChanges에 screenSize·smallestScreenSize·screenLayout 등을 더하고 launchMode를 singleTask로 설정합니다.

{
  "expo": {
    "plugins": ["@0610studio/zs-ui"]
  }
}

2. Provider 설정​

앱 최상위에 ThemeProvider와 OverlayProvider를 추가합니다. ThemeProvider가 바깥쪽이어야 합니다.

import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { ThemeProvider, OverlayProvider } from '@0610studio/zs-ui';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <ThemeProvider>
        <OverlayProvider>
          {/* 앱 내용 */}
        </OverlayProvider>
      </ThemeProvider>
    </GestureHandlerRootView>
  );
}

3. 커스텀 테마 적용 (선택)​

브랜드 색상과 폰트를 지정하려면 themeFactory와 themeFonts를 전달합니다.

import { ThemeProvider, OverlayProvider, themeFactory } from '@0610studio/zs-ui';

const themeFonts = {
  400: 'Pretendard-Regular',
  700: 'Pretendard-Bold',
};

const customPalette = themeFactory({
  light: { primary: { main: '#007AFF' } },
});

export default function App() {
  return (
    <ThemeProvider themeFonts={themeFonts} customPalette={customPalette}>
      <OverlayProvider>
        {/* 앱 내용 */}
      </OverlayProvider>
    </ThemeProvider>
  );
}

4. 컴포넌트 사용​

useOverlay로 오버레이를 제어하고, ZSContainer로 스크린을 구성합니다.

import { ZSContainer, ZSText, ZSBlockButton, useOverlay } from '@0610studio/zs-ui';

export default function HomeScreen() {
  const { showAlert } = useOverlay();

  return (
    <ZSContainer edges={['bottom']}>
      <ZSText typo="heading.2" color="base">
        ZS-ui
      </ZSText>
      <ZSBlockButton
        title="저장"
        typo="body.2"
        intent="primary"
        variant="solid"
        onPress={() =>
          showAlert({
            title: '확인',
            informative: '저장되었습니다.',
          })
        }
      />
    </ZSContainer>
  );
}

다음 단계​

참고: useAlert, useSnackbar 같은 개별 context hook은 내부 구현용입니다. 오버레이 제어는 useOverlay 하나만 사용하세요.