앱인토스 개발자센터 로고
이 내용이 도움이 되었나요?

인터랙션 ​

이 문서에서는 사용자 인터랙션과 직접적으로 연결되는 UI/UX 기능을 다뤄요.
스크롤, 키보드, 오디오 포커스, 햅틱 진동처럼 사용자의 행동에 즉각 반응해야 하는 기능들을 한 곳에 모아 설명해요.

스크롤 바운스 영역 배경 처리 (ScrollViewInertialBackground) ​

지원환경: React NativeReact Native SDKv1.0.3
실행환경: Toss AppSandbox App

iOS ScrollView에서 스크롤이 끝에 도달했을 때 발생하는 **바운스 효과 영역(위/아래)**에
배경색을 채워 보다 자연스러운 시각 효과를 제공하는 컴포넌트예요.

시그니처 ​

ts
function ScrollViewInertialBackground({
  topColor,
  bottomColor,
  spacer: _spacer,
}: ScrollViewInertialBackgroundProps): JSX.Element;

파라미터 ​

  • propsobject

    컴포넌트에 전달되는 props 객체예요.

    • props.topColorstring

      스크롤 위쪽 영역에 적용할 배경색이에요. 기본값은 시스템 테마에 맞춰 자동으로 적용되는 adaptive.background에요.

    • props.bottomColorstring

      스크롤 아래쪽 영역에 적용할 배경색이에요. 기본값은 시스템 테마에 맞춰 자동으로 적용되는 adaptive.background에요.

    • props.spacernumber

      배경색이 적용될 콘텐츠 위, 아래 공간 사이의 공간 크기를 지정해요. 기본값은 `useWindowDimensions`로 가져온 화면 높이를 사용해요.

예제 : 스크롤 뷰 위, 아래에 배경색을 추가하기 ​

스크롤 뷰 위에 빨간색, 아래에 파란색 배경색을 추가해요. 스크롤을 벗어난 영역에 배경색이 적용돼요.

tsx
import { ScrollView, View, Text } from 'react-native';
import { ScrollViewInertialBackground } from '@granite-js/react-native';

const dummies = Array.from({ length: 20 }, (_, i) => i);

function InertialBackgroundExample() {
  return (
    <ScrollView>
      <ScrollViewInertialBackground topColor="red" bottomColor="blue" />
      {dummies.map((i) => (
        <View
          key={`dummy-${i}`}
          style={{ width: '100%', height: 100, borderBottomColor: 'black', borderBottomWidth: 1 }}
        >
          <Text>스크롤을 해보세요.</Text>
        </View>
      ))}
    </ScrollView>
  );
}

색상 모드 타입 (ColorPreference) ​

지원환경: React NativeReact Native SDKv1.0.3
실행환경: Toss AppSandbox App

현재 기기의 색상 모드(라이트 / 다크) 를 나타내는 타입이에요. 테마 분기나 스타일 조건 처리에 사용해요.

시그니처 ​

typescript
type ColorPreference = 'light' | 'dark';

키보드 위로 요소 올리기 (KeyboardAboveView) ​

지원환경: React NativeReact Native SDKv1.0.3
실행환경: Toss AppSandbox App

키보드가 나타날 때 자식 컴포넌트를 자동으로 키보드 위로 올려주는 레이아웃 컴포넌트예요.
입력 중에도 버튼이나 액션 영역을 항상 노출하고 싶을 때 유용해요.

시그니처 ​

typescript
function KeyboardAboveView({ style, children, ...props }: ComponentProps<typeof View>): ReactElement;

파라미터 ​

  • props.styleStyleProp<ViewStyle>

    추가적인 스타일을 적용할 수 있어요. 예를 들어, 배경색이나 크기 등을 설정할 수 있어요.

  • props.childrenReactNode

    키보드가 나타날 때 키보드 위로 표시할 컴포넌트예요. 예를 들어, 버튼, 텍스트 입력창 등을 넣을 수 있어요.

반환 값 ​

  • ReactElement

    키보드가 나타났을 때 키보드 위로 조정된 `Animated.View`를 반환해요.

예제 : 키보드 위로 요소를 올리기 ​

tsx
import { ScrollView, TextInput, View, Text } from 'react-native';
import { KeyboardAboveView } from '@granite-js/react-native';

function KeyboardAboveViewExample() {
  return (
    <>
      <ScrollView>
        <TextInput placeholder="placeholder" />
      </ScrollView>

      <KeyboardAboveView>
        <View style={{ width: '100%', height: 50, backgroundColor: 'yellow' }}>
          <Text>Keyboard 위에 있어요.</Text>
        </View>
      </KeyboardAboveView>
    </>
  );
}

오디오 포커스 변경 콜백 (OnAudioFocusChanged) ​

지원환경: React NativeReact Native SDKv1.0.3
실행환경: Toss AppSandbox App

비디오나 오디오 컴포넌트의 오디오 포커스가 변경될 때 호출되는 콜백 타입이에요.
다른 앱이나 시스템 이벤트로 소리가 중단될 때의 처리를 제어할 수 있어요.

시그니처 ​

typescript
type OnAudioFocusChanged = NonNullable<VideoProperties['onAudioFocusChanged']>;

파라미터 ​

  • event필수 · Object

    오디오 포커스 정보를 담고 있는 이벤트 객체예요.

    • event.hasAudioFocus필수 · boolean

      비디오 컴포넌트가 오디오 포커스를 가지고 있는지 여부를 나타내요.

햅틱 진동 실행하기 (generateHapticFeedback) ​

지원환경: React NativeReact Native SDKv1.0.3WebViewWebView SDKv1.0.3
실행환경: Toss AppSandbox App

디바이스에서 햅틱 진동을 발생시키는 함수예요.
버튼 클릭, 완료 알림, 성공/실패 피드백 등 촉각 반응이 필요한 순간에 사용해요.

시그니처 ​

typescript
function generateHapticFeedback(options: HapticFeedbackOptions): Promise<void>;

반환 값 ​

  • void

예제 : 버튼을 눌러 햅틱 일으키기 ​

js
import { generateHapticFeedback } from '@apps-in-toss/web-framework';

generateHapticFeedback({ type: 'tickWeak' });
tsx
import React from 'react';
import { generateHapticFeedback } from '@apps-in-toss/web-framework';

function GenerateHapticFeedbackWeb() {
  return (
    <button
      onClick={() => {
        generateHapticFeedback({ type: 'tickWeak' });
      }}
      style={{
        padding: '10px 20px',
        borderRadius: '8px',
        border: 'none',
        backgroundColor: '#3182f6',
        color: 'white',
        cursor: 'pointer',
        fontSize: '16px',
      }}
    >
      햅틱
    </button>
  );
}

export default GenerateHapticFeedbackWeb;
tsx
import { Button } from 'react-native';
import { generateHapticFeedback } from '@apps-in-toss/framework';

function GenerateHapticFeedback() {
  return (
    <Button
      title="햅틱"
      onPress={() => {
        generateHapticFeedback({ type: 'tickWeak' });
      }}
    />
  );
}

예제 앱 체험하기 ​

apps-in-toss-examples 저장소에서 with-haptic-feedback 코드를 내려받거나,
아래 QR 코드를 스캔해 직접 체험해 보세요.

햅틱 진동 옵션 및 타입 (HapticFeedbackOptions, HapticFeedbackType) ​

generateHapticFeedback에 전달할 진동 타입 옵션을 정의해요.

시그니처 ​

tsx
interface HapticFeedbackOptions {
  type: HapticFeedbackType;
}

type HapticFeedbackType =
  | 'tickWeak'
  | 'tap'
  | 'tickMedium'
  | 'softMedium'
  | 'basicWeak'
  | 'basicMedium'
  | 'success'
  | 'error'
  | 'wiggle'
  | 'confetti';

참고사항 ​

  • 인터랙션 관련 기능은 사용자 경험에 직접적인 영향을 줘요.
    과도한 사용은 피하고, 의미 있는 순간에만 사용하세요.
  • 키보드 / 오디오 / 햅틱 기능은 플랫폼별 동작 차이가 있을 수 있어요.
  • 이벤트나 콜백 기반 기능은 반드시 정리(cleanup) 로직을 함께 구현하세요.