시작하기

$ yarn add karrotframe

# peer-dependencies
$ yarn add react react-dom react-router-dom

import 'karrotframe/lib/index.css'

import { ... } from 'karrotframe'

1. 네비게이터

네비게이터는 아래의 기능을 지원합니다.

• History 지원
• 각 플랫폼에 맞게 디자인된 자연스러운 화면전환
• 각 플랫폼에 맞게 디자인된 네비게이션 바
• 상황에 맞는 이전, 닫기 버튼

네비게이터의 핵심 로직은 react-router-dom에 의존하고 있습니다.

1-a. Navigator

Navigator 컴포넌트는 화면을 표현하는데 반드시 필요한 요소들이 포함됩니다. 컴포넌트 트리 상단에 포함해주세요

import { Navigator } from 'karrotframe'

const App: React.FC = () => {
  return (
    <Navigator
      theme="Cupertino"
      onClose={() => {
        console.log('닫기버튼이 눌렸습니다')
      }}
    >
      {/*...*/}
    </Navigator>
  )
}

| Props | 타입 | 역할 | 기본값 | | ------------------- | -------------------------- | ------------------------------------------------------------------- | ----------------- | | theme | Cupertino 또는 Android | UI 테마 | Android | | animationDuration | number | 애니메이션 지속시간 | theme 별로 다름 | | useCustomRouter | boolean | true인 경우 Navigator 내에 포함된 <HashRouter/> 을 제거합니다 | | | onClose | () => void | 루트의 닫기 버튼이 클릭될때 해당 함수가 호출됩니다 | | | onDepthChange | (height: number) => void | 네비게이션 깊이가 변경될때마다 해당 함수가 호출됩니다 | |

1-b. Screen

Screen 컴포넌트는 화면을 선언하는데 사용합니다. Navigator 안에 선언합니다.

import { Navigator, Screen } from 'karrotframe'

const App: React.FC = () => {
  return (
    <Navigator
      theme="Cupertino"
      onClose={() => {
        console.log('닫기버튼이 눌렸습니다')
      }}
    >
      <Screen path="/" component={MyComponent} />
      {/* 또는 */}
      <Screen path="/">
        <MyComponent />
      </Screen>
    </Navigator>
  )
}

| Props | 타입 | 역할 | 기본값 | | ----------- | ------------------------------------------- | ----------------------- | -------- | | path | string | 해당 화면을 표현할 Path | required | | component | React.ComponentType<ScreenComponentProps> | 렌더링 할 컴포넌트 | | | children | React.ReactNode | 렌더링 할 요소 | |

component 또는 children은 반드시 사용하세요 (만약 두 props가 동시에 선언되는 경우, component가 우선권을 갖습니다)

ScreenComponentProps를 통해 스크린에 대한 정보를 받아올 수 있습니다

import { ScreenComponentProps } from 'karrotframe'

const MyComponent: React.FC<ScreenComponentProps> = (props) => {
  console.log(isTop) // 현재 최상단인지 여부
  console.log(isRoot) // 현재 첫 페이지인지 여부
}

1-c. ScreenHelmet

기본적으로 Screen은 상단 네비게이션 바를 포함하고 있지 않습니다. 기본 제공되는 상단 네비게이션 바를 추가, 수정하기 위해서는 ScreenHelmet 컴포넌트를 사용하세요.

import { ScreenHelmet } from 'karrotframe'

const MyComponent: React.FC = () => {
  return (
    <div>
      <ScreenHelmet
        title="당근알바"
        appendLeft={<div>왼쪽에추가</div>}
        appendRight={<div>오른쪽에추가</div>}
        customBackButton={<div>이전</div>}
        customCloseButton={<div>닫기</div>}
      />
    </div>
  )
}

| Props | 타입 | 역할 | 기본값 | | --------------------- | ------------------- | -------------------------------------------------- | ------ | | title | React.ReactNode | 타이틀 부분에 출력할 요소 | | | appendLeft | React.ReactNode | 왼쪽에 요소를 추가 (이전 버튼 오른쪽에 표시됩니다) | | | appendRight | React.ReactNode | 오른쪽에 요소를 추가 (닫기 버튼 왼쪽에 표시됩니다) | | | closeButtonLocation | left 또는 right | 이전 버튼을 사용자화합니다 | left | | customBackButton | React.ReactNode | 이전 버튼을 사용자화합니다 | | | customCloseButton | React.ReactNode | 닫기 버튼을 사용자화합니다 | |

1-d. useLocation, useParams, useRouteMatch

react-router-dom에 존재하는 useLocation, useParams, useRouteMatch를 사용할 수 있습니다

import { useLocation, useParams, useRouteMatch } from 'react-router-dom'

const Post: React.FC = () => {
  /**
   * 현재 location 정보
   */
  const location = useLocation()

  /**
   * path parameter로 들어온 값
   */
  const params = useParams()

  /**
   * 현재 위치와 특정 path regex를 비교해 파싱된 값을 반환합니다.
   * (매치하지 않는다면 null 반환)
   */
  const match = useRouteMatch({
    path: '/:post_id',
  })

  return /* ... */
}

1-e. useQueryParams, useParams

화면의 전환간 path의 변경으로 인해 의도하지 않은 화면의 변경이 발생하지 않도록 하기 위해, useQueryParam을 통해 querystring을 사용하고, useParams를 통해 path parameter를 사용할 수 있습니다.

import { useQueryParams, useParams } from 'karrotframe'

const Post: React.FC = () => {
  /**
   * querystring으로 들어온 값 (화면 전환간 불변)
   */
  const querystring = useQueryParams()

  /**
   * path parameter로 들어온 값 (화면 전환간 불변)
   */
  const params = useParams()

  return /* ... */
}

1-f. useNavigator

화면 전환을 수행합니다.

import { useNavigator } from 'karrotframe'

const Posts: React.FC = () => {
  const { push, pop, replace } = useNavigator()

  const goPost = (postId: string) => () => {
    // 특정 path로 이동합니다
    push(`/posts/${postId}`)

    // 특정 path을 스와이프 백이 불가능한 새 창으로 띄웁니다 (Cupertino Only)
    push(`/posts/${postId}`, {
      present: true,
    })
  }

  const goBack = () => {
    // 한단계 뒤로 갑니다
    pop()

    // depth argument를 통해 여러단계를 pop 할 수 있습니다
    pop(1)
  }

  useEffect(() => {
    if (!user) {
      // 특정 path로 이동합니다 (replace)
      // 애니메이션 없이 이동하므로, redirect behavior에 적절합니다
      replace('/login')
    }
  })

  return (
    <div>
      {posts.map((post) => {
        return (
          <div>
            {/* ... */}
            <button onClick={goPost(post.id)}>글 상세보기</button>
          </div>
        )
      })}
      {/* ... */}
      <button onClick={goBack}>뒤로가기</button>
    </div>
  )
}

추가적으로, useNavigator의 pop().send()과 await push()를 통해 화면간 데이터 전송을 할 수 있습니다.

pop() 함수 내 depth argument를 2 이상으로 부여할 시 여러 화면을 뛰어넘어서 전송도 가능합니다.

import { useNavigator } from 'karrotframe'

const Posts: React.FC = () => {
  const { push } = useNavigator()

  const writePost = () => {
    // 다음 화면에서 전송할 데이터를 기다립니다
    const data = await push('/posts/write')
    console.log(data)
    // {
    //   hello: 'world',
    // }
  }
  return (
    <div>
      <button onClick={writePost}>글 작성하기</button>
    </div>
  )
}

const PostWriteForm: React.FC = () => {
  const { pop } = useNavigator()

  const onSubmit = () => {
    // 이전 화면으로 데이터 전송
    pop().send({
      hello: 'world',
    })

    // 아래와 같이 여러 단계를 뛰어넘어 데이터 전송도 가능합니다
    pop(3).send({
      hello: 'world',
    })
  }

  return /* ... */
}

1-g. react-router-dom

react-router-dom의 기본 컴포넌트와 함수들을 다음과 같이 함께 사용할 수 있습니다.

라우터 교체하기

import { Navigator } from 'karrotframe'
import { HashRouter } from 'react-router-dom'

const App = () => {
  return (
    <HashRouter>
      <Navigator useCustomRouter>...</Navigator>
    </HashRouter>
  )
}

Screen 내부에서 라우팅하기

// <Screen path={ExampleScreen} />

import { Route, useHistory } from 'react-router-dom'

const ExampleScreen = () => {
  const history = useHistory()

  const moveToInside2 = () => {
    history.push('/.../inside2')
  }
  const goBack = () => {
    history.goBack()
  }
  const goBackFurther = () => {
    // 현재 내부 라우팅과 이전 Karrotframe 스크린 전환을 통합해서
    // 뒤로가기 할 수 있습니다.
    history.go(-4)
  }

  return (
    <div>
      <Route path="/.../inside1">...</Route>
      <Route path="/.../inside2">...</Route>
    </div>
  )
}

path 내에 _si 쿼리스트링이 포함되어있지 않으면 Karrotframe은 내부 라우팅으로 인식해 별도의 애니메이션 처리를 위한 작업을 하지 않습니다