KeyboardAvoidingScrollView

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

사용 가능 버전@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

Props

Prop

Type

id?string | undefined

hidden?boolean | undefined

focusable?boolean | undefined

bounces?boolean | undefined

enable-scroll?boolean | undefined

scroll-bar-enable?boolean | undefined

upper-threshold?number | undefined

lower-threshold?number | undefined

initial-scroll-offset?number | undefined

initial-scroll-to-index?number | undefined

bindlayoutchange?EventHandler<LayoutChangeDetailEvent<Target>> | undefined

bindscrolltoupper?((e: ScrollToUpperEvent) => void) | undefined

bindscrolltolower?((e: ScrollToLowerEvent) => void) | undefined

bindscroll?((e: ScrollEvent) => void) | undefined

bindscrollend?((e: ScrollEndEvent) => void) | undefined

bindcontentsizechanged?((e: ContentSizeChangedEvent) => void) | undefined

style?CSSProperties | undefined

children?ReactNode

className?string | undefined

bindtap?EventHandler<BaseTouchEvent<Target>> | undefined

bindtouchstart?EventHandler<BaseTouchEvent<Target>> | undefined

bindtouchend?EventHandler<BaseTouchEvent<Target>> | undefined

bindtouchcancel?EventHandler<BaseTouchEvent<Target>> | undefined

main-thread:bindtap?EventHandler<BaseTouchEvent<Element>> | undefined

Usage

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

export function Form() {
  return (
    <KeyboardAvoidingScrollView keyboardGap={24} scrollBehavior="smooth">
      <TextField.Root>
        <TextField.Input accessibility-label="제목" />
      </TextField.Root>
      <TextField.Root>
        <TextField.Textarea accessibility-label="내용" />
      </TextField.Root>
    </KeyboardAvoidingScrollView>
  );
}

TextField.Input과 TextField.Textarea가 focus·blur·layout 변경을 자동으로 전달하므로 별도 등록 prop은 필요하지 않습니다.

Web Version Differences

브라우저의 visualViewport나 CSS viewport unit 대신 Lynx keyboard global event와 native node 측정을 사용합니다.
키보드가 열릴 때 필요한 하단 spacer만 추가하고, 사용자 스크롤 중에는 자동 이동을 잠시 중단합니다.

Unsupported Lynx Features

가로·중첩 scroll view는 지원하지 않습니다.
키보드 toolbar 높이와 큰 textarea의 caret 단위 회피는 아직 반영하지 않습니다.