Keyboard Avoiding Scroll View

소프트 키보드가 활성 입력을 가리지 않도록 세로 스크롤 위치와 하단 여백을 조정하는 컴포넌트입니다.

사용 가능 버전@seed-design/[email protected]

Installation

npm install @seed-design/lynx-react

pnpm add @seed-design/lynx-react

yarn add @seed-design/lynx-react

bun add @seed-design/lynx-react

아래 예제에서 사용하는 Text Field 레지스트리 스니펫도 추가합니다.

npx @seed-design/cli add ui:text-field

pnpm dlx @seed-design/cli add ui:text-field

yarn dlx @seed-design/cli add ui:text-field

bun x @seed-design/cli add ui:text-field

Props

`KeyboardAvoidingScrollView.Root`

Prop

Type

children?ReactNode

`KeyboardAvoidingScrollView.Content`

Prop

Type

children?ReactNode

`KeyboardAvoidingScrollView.Footer`

Prop

Type

children?ReactNode

Usage

AppBar 아래 화면 본문처럼 높이가 정해진 영역에 KeyboardAvoidingScrollView.Root를 두고, 입력 화면을 KeyboardAvoidingScrollView.Content로 감쌉니다. 키보드 위에 붙여야 하는 하단 버튼은 Content 아래의 KeyboardAvoidingScrollView.Footer에 둡니다.

import { KeyboardAvoidingScrollView } from "@seed-design/lynx-react";

export function Screen() {
  return (
    <KeyboardAvoidingScrollView.Root className="screen-body">
      <KeyboardAvoidingScrollView.Content>{/* 입력 화면 */}</KeyboardAvoidingScrollView.Content>
      <KeyboardAvoidingScrollView.Footer>{/* 하단 버튼 */}</KeyboardAvoidingScrollView.Footer>
    </KeyboardAvoidingScrollView.Root>
  );
}

Root에는 높이를 지정하고 자식으로 Content와 Footer만 두세요. Footer는 Content 바로 아래에 배치합니다.
Content는 focus된 입력이 키보드나 Footer에 가리지 않도록 스크롤과 하단 여백을 조정합니다. keyboardGap과 scrollBehavior로 간격과 이동 방식을 정할 수 있습니다.
Footer는 키보드 위로 이동합니다. 하단 safe area 여백은 Root 바깥의 화면 컨테이너에 두세요.
Text Field Registry의 Input과 Textarea는 focus, blur, 높이 변경을 자동으로 전달합니다.
Android에서 이 컴포넌트가 키보드 회피를 맡으면 입력 요소에 android-set-soft-input-mode="nothing"을 지정하고 avoid-keyboard는 사용하지 마세요.

Examples

한 줄 입력

화면 아래쪽의 TextField.Input에 focus하면 입력 영역과 키보드 사이에 24px 간격이 생기도록 자동 스크롤합니다.

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { KeyboardAvoidingScrollView } from "@seed-design/lynx-react";
import { TextField, TextFieldInput } from "@/components/ui/text-field";

export default function Example() {
  return (
    <KeyboardAvoidingScrollView.Root
      className="keyboard-avoiding-scroll-view-preview"
      keyboardGap={24}
      scrollBehavior="smooth"
    >
      <KeyboardAvoidingScrollView.Content>
        <view className="keyboard-avoiding-scroll-view-preview__content">
          <text className="keyboard-avoiding-scroll-view-preview__title">한 줄 입력</text>
          <text className="keyboard-avoiding-scroll-view-preview__description">
            아래 입력 영역을 탭하면 키보드 위로 자동 스크롤됩니다.
          </text>

          <view className="keyboard-avoiding-scroll-view-preview__spacer">
            <text className="keyboard-avoiding-scroll-view-preview__spacer-label">
              입력 영역이 화면 아래에 오도록 확보한 공간
            </text>
          </view>

          <view className="keyboard-avoiding-scroll-view-preview__field">
            <TextField label="주소">
              <TextFieldInput
                accessibility-label="주소"
                android-set-soft-input-mode="nothing"
                maxlength={80}
                placeholder="동네 이름을 입력해 주세요"
              />
            </TextField>
          </view>

          <view className="keyboard-avoiding-scroll-view-preview__footer-space" />
        </view>
      </KeyboardAvoidingScrollView.Content>
    </KeyboardAvoidingScrollView.Root>
  );
}

이 예제는 네이티브 키보드 동작을 사용합니다. QR 코드 패널에서 Lynx Explorer로 실행한 뒤 화면 아래의 주소 입력 영역을 탭해 확인해 주세요.

자동 높이 조절 textarea

TextField.Textarea에 여러 줄을 입력해 높이가 달라지면 활성 입력 영역의 위치를 다시 계산합니다.

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { KeyboardAvoidingScrollView } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

export default function Example() {
  return (
    <KeyboardAvoidingScrollView.Root
      className="keyboard-avoiding-scroll-view-preview"
      keyboardGap={24}
      scrollBehavior="smooth"
    >
      <KeyboardAvoidingScrollView.Content>
        <view className="keyboard-avoiding-scroll-view-preview__content">
          <text className="keyboard-avoiding-scroll-view-preview__title">여러 줄 입력</text>
          <text className="keyboard-avoiding-scroll-view-preview__description">
            줄을 추가해 입력 영역이 커져도 키보드 위의 안전한 위치를 다시 계산합니다.
          </text>

          <view className="keyboard-avoiding-scroll-view-preview__spacer">
            <text className="keyboard-avoiding-scroll-view-preview__spacer-label">
              입력 영역이 화면 아래에 오도록 확보한 공간
            </text>
          </view>

          <view className="keyboard-avoiding-scroll-view-preview__field">
            <TextField label="자기소개">
              <TextFieldTextarea
                accessibility-label="자기소개"
                android-set-soft-input-mode="nothing"
                maxlength={300}
                placeholder="여러 줄을 입력해 보세요"
              />
            </TextField>
          </view>

          <view className="keyboard-avoiding-scroll-view-preview__footer-space" />
        </view>
      </KeyboardAvoidingScrollView.Content>
    </KeyboardAvoidingScrollView.Root>
  );
}

이 예제는 네이티브 입력 요소의 자동 높이 조절과 키보드 회피 동작을 사용합니다. QR 코드 패널에서 Lynx Explorer로 실행한 뒤 여러 줄을 입력해 확인해 주세요.

하단 버튼

KeyboardAvoidingScrollView.Footer에 둔 버튼은 키보드가 열리면 키보드 바로 위로 올라갑니다. focus된 입력 영역은 올라간 버튼과 16px 간격을 두도록 자동 스크롤합니다.

Lynx 예제를 불러오는 중입니다.

import "./styles";

import { ActionButton, KeyboardAvoidingScrollView } from "@seed-design/lynx-react";
import { TextField, TextFieldInput } from "@/components/ui/text-field";

export default function Example() {
  return (
    <KeyboardAvoidingScrollView.Root
      className="keyboard-avoiding-scroll-view-preview"
      keyboardGap={16}
      scrollBehavior="smooth"
    >
      <KeyboardAvoidingScrollView.Content>
        <view className="keyboard-avoiding-scroll-view-preview__content">
          <text className="keyboard-avoiding-scroll-view-preview__title">하단 버튼</text>
          <text className="keyboard-avoiding-scroll-view-preview__description">
            입력 영역을 탭하면 하단 버튼이 키보드 위로 올라오고, 입력 영역은 버튼 위에 보이도록
            스크롤됩니다.
          </text>

          <view className="keyboard-avoiding-scroll-view-preview__spacer">
            <text className="keyboard-avoiding-scroll-view-preview__spacer-label">
              입력 영역이 화면 아래에 오도록 확보한 공간
            </text>
          </view>

          <view className="keyboard-avoiding-scroll-view-preview__field">
            <TextField label="닉네임">
              <TextFieldInput
                accessibility-label="닉네임"
                android-set-soft-input-mode="nothing"
                maxlength={20}
                placeholder="닉네임을 입력해 주세요"
              />
            </TextField>
          </view>
        </view>
      </KeyboardAvoidingScrollView.Content>

      <KeyboardAvoidingScrollView.Footer className="keyboard-avoiding-scroll-view-preview__bottom-bar">
        <ActionButton variant="brandSolid" size="large">
          완료
        </ActionButton>
      </KeyboardAvoidingScrollView.Footer>
    </KeyboardAvoidingScrollView.Root>
  );
}

이 예제는 네이티브 키보드 동작을 사용합니다. QR 코드 패널에서 Lynx Explorer로 실행한 뒤 닉네임 입력 영역을 탭해 확인해 주세요.

웹 버전과의 차이

Lynx keyboard event와 native node 위치를 기준으로 세로 스크롤을 조정합니다.
브라우저의 form 제출과 자동 focus 이동은 제공하지 않습니다.

Lynx 미지원 기능

가로 또는 중첩 scroll view
키보드 toolbar 높이와 큰 textarea의 caret 단위 회피
키보드 애니메이션과 정확히 같은 Footer 이동. 닫는 동안 잠시 간격이 생길 수 있습니다.

Keyboard Avoiding Scroll View

목차