Skip to Content
Lynx

Host Integration

호스트 앱이 주는 색상 스킴·모션 설정·Safe Area를 SeedProvider로 SEED에 전달하는 방법을 알아봅니다.

개요

Lynx의 global props는 Lynx가 정의하지 않는 값이고, 어떤 키가 들어오는지는 호스트 앱마다 다릅니다. SEED는 특정 호스트의 global props 키를 직접 읽지 않고, 앱이 SeedProvider로 넘긴 값만 사용합니다. 어떤 키를 읽어 어떻게 바꿀지는 앱이 정합니다.

prop타입사용하는 곳생략했을 때
colorMode"system" | "light-only" | "dark-only"useSeedClassName의 기본 colorMode, Liquid Glass tint바깥 값, 없으면 "system"
preferredColorScheme"light" | "dark"useSeedClassName의 colorMode: "system", 아이콘 색상 동기화, Liquid Glass tint"light"
preferredMotion"default" | "reduced"Scale Feedback. "reduced"이면 눌림 축소를 끕니다"default"
safeAreaInsets{ top, right, bottom, left } (논리 px)useSafeArea, Box의 "safeArea", AppBar, Dialog, MenuSheet, floating 레이어 경계env(safe-area-inset-*)

화면 크기는 넘기지 않습니다. SEED는 useViewport로 현재 LynxView 크기를 직접 측정합니다.

preferredColorScheme은 호스트가 선호하는 값이며, 앱의 colorMode를 적용한 결과가 아닙니다. colorMode="dark-only"인 앱에서도 호스트 설정을 그대로 넘기세요. 앱의 colorMode는 SeedProvider의 colorMode로 따로 넘깁니다. SEED는 두 값으로 적용할 테마를 정합니다. useSeedClassName은 colorMode 옵션을 생략하면 이 테마를 쓰고, CSS 변수를 읽지 못하는 Liquid Glass tint도 이 테마를 따릅니다.

적용하기

앱 root에 SeedProvider를 하나 두고, 호스트의 global props를 SEED 값으로 바꿔 넘깁니다. global props는 pluginReactLynx의 globalPropsMode에 맞게 읽습니다. 기본값 "reactive"에서는 호스트가 값을 바꾸면 페이지 전체가 다시 렌더되므로 lynx.__globalProps를 바로 읽고, "event"에서는 useGlobalProps()로 읽어 변경을 구독합니다.

src/index.tsx
import { root } from "@lynx-js/react";
import { SeedProvider, useSeedClassName, type SafeAreaInsets } from "@seed-design/lynx-react";

// 호스트 계약은 앱이 선언합니다.
interface HostGlobalProps {
  theme?: string;
  motion?: string;
  safeAreaInsetTop?: number;
  safeAreaInsetRight?: number;
  safeAreaInsetBottom?: number;
  safeAreaInsetLeft?: number;
}

function Page() {
  // 옵션을 생략하면 `SeedProvider`의 `colorMode`를 씁니다.
  const seedClassName = useSeedClassName();
  return (
    <page className={seedClassName}>
      <App />
    </page>
  );
}

const isValidInset = (value: unknown): value is number =>
  typeof value === "number" && Number.isFinite(value) && value >= 0;

function toSafeAreaInsets(g: HostGlobalProps): SafeAreaInsets | undefined {
  const { safeAreaInsetTop: top, safeAreaInsetRight: right } = g;
  const { safeAreaInsetBottom: bottom, safeAreaInsetLeft: left } = g;
  // 4방향 모두 0 이상의 유한한 숫자일 때만 넘깁니다.
  if (!isValidInset(top) || !isValidInset(right) || !isValidInset(bottom) || !isValidInset(left)) {
    return undefined;
  }
  return { top, right, bottom, left };
}

function Root() {
  // globalPropsMode: "event"이면 `useGlobalProps() as HostGlobalProps`로 읽습니다.
  const g = lynx.__globalProps as HostGlobalProps;
  return (
    <SeedProvider
      preferredColorScheme={g.theme === "dark" ? "dark" : "light"}
      preferredMotion={g.motion === "reduced" ? "reduced" : "default"}
      safeAreaInsets={toSafeAreaInsets(g)}
    >
      <Page />
    </SeedProvider>
  );
}

root.render(<Root />);

useSeedClassName은 SeedProvider 안에서 호출해야 colorMode와 preferredColorScheme을 읽습니다. 위 예제처럼 <page>를 그리는 컴포넌트를 Provider 안쪽에 둡니다.

SeedProvider가 없어도 오류는 나지 않습니다. 호스트 값이 없는 환경에서는 위 표의 "생략했을 때" 값으로 동작합니다.

Safe Area 값

safeAreaInsets는 4방향을 모두 넘깁니다. SEED는 받은 값을 보정하지 않고 그대로 px로 쓰므로, 음수나 NaN 같은 값은 위 예제처럼 앱에서 걸러 주세요. 0도 유효한 값이므로, 네이티브가 이미 여백을 확보했다면 0을 넘기세요.

safeAreaInsets를 생략하면 env(safe-area-inset-*)를 씁니다. Android에서는 이 CSS 함수가 동작하지 않아 Safe Area가 0처럼 보일 수 있으니, 호스트가 값을 주지 않는 경우의 보정도 앱에서 정하세요.

Overlay 안에서 다른 Safe Area 쓰기

같은 LynxView의 <overlay>는 global props를 공유합니다. fullscreen과 overlay에 다른 Safe Area가 필요하면 overlay 콘텐츠 안에 SafeAreaProvider를 중첩합니다. 그 영역의 useSafeArea()와 useSeedContext().safeAreaInsets가 함께 바뀝니다.

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

<SafeAreaProvider insets={{ top: 0, right: 0, bottom: 0, left: 0 }}>
  <OverlayContent />
</SafeAreaProvider>;

SeedProvider를 중첩하면 생략한 prop은 바깥 Provider의 값을 이어받습니다.

Liquid Glass (iOS)

Chip과 FloatingActionButton은 iOS Liquid Glass로 그릴 수 있습니다. 호스트 flag와 glassEffect가 모두 켜져야 glass로 그립니다.

prop타입넘기는 곳생략했을 때
supportsLiquidGlassbooleanSeedProvider(앱 root). 호스트가 Liquid Glass를 그릴 수 있을 때 true바깥 값, 없으면 false
glassEffectboolean | { style?: "regular" | "clear"; interactive?: boolean }SeedProvider(화면이나 영역 전체) 또는 Chip·FloatingActionButton(컴포넌트 하나)바깥 값
  • 컴포넌트의 glassEffect는 SeedProvider에서 이어받은 값을 덮어씁니다. 영역 전체에 켜 두고 특정 컴포넌트만 glassEffect={false}로 끄거나, 반대로 컴포넌트 하나만 켤 수 있습니다. 지금은 iOS에서만 그립니다.
  • supportsLiquidGlass는 호스트가 판단해 넘깁니다. SEED는 플랫폼이나 OS 버전을 따로 확인하지 않습니다. Lynx <blur-view>의 blur-effect="glass"를 그릴 수 있는 호스트(iOS 26 이상, glass를 지원하는 XElement blur-view 등록)에서만 true를 넘기세요. 그릴 수 없는 호스트에서 켜면 배경이 투명해질 수 있습니다.
  • glassEffect의 true는 {}와 같습니다(style: "regular", interactive: false). false는 바깥에서 이어받은 효과를 끕니다.
  • glass일 때 배경 대신 현재 상태의 배경색이 glass tint가 되고, Chip의 테두리와 FloatingActionButton의 그림자는 그리지 않습니다. 눌림 축소(Scale Feedback)도 쓰지 않으며, interactive: true이면 눌림 배경 대신 glass가 터치에 반응합니다.
  • tint는 SeedProvider의 colorMode와 preferredColorScheme으로 정한 테마의 Recipe 배경색입니다. className으로 배경을 바꿔도 tint는 바뀌지 않습니다. 하위 트리에 seed-color-mode-light-only·seed-color-mode-dark-only class를 줬다면 그 트리를 같은 값의 ColorModeProvider로 감싸세요(Theming).
<SeedProvider supportsLiquidGlass={g.liquidGlass === true}>
  {/* 영역 전체 */}
  <SeedProvider glassEffect>
    <FloatingActionButton icon={<IconPlusLine />} label="글쓰기" />
    <Chip.Button glassEffect={false}>{/* 이 Chip만 끔 */}</Chip.Button>
  </SeedProvider>
  {/* 컴포넌트 하나 */}
  <Chip.Toggle glassEffect={{ interactive: true }}>{/* ... */}</Chip.Toggle>
</SeedProvider>

넘긴 값 읽기

useSeedContext()는 SeedProvider가 받은 값을 그대로 돌려줍니다. px 문자열 변환이나 env() fallback은 하지 않습니다. 화면에 적용할 Safe Area 값이 필요하면 useSafeArea를 사용하세요.

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

const { preferredColorScheme, preferredMotion, safeAreaInsets } = useSeedContext();

Global Props 직접 읽기

이전 버전의 SEED는 특정 호스트 앱의 global props 키(theme, motion, safeAreaInset*)를 직접 읽었습니다. 기존 앱이 바로 깨지지 않도록 다음 메이저 버전 전까지는 SeedProvider에 넘기지 않은 값만 이 키에서 채웁니다.

  • 키가 실제로 있어 사용되면 개발 빌드에서 키마다 한 번 경고합니다. 키가 없는 호스트에서는 경고하지 않습니다.
  • safeAreaInsets를 생략하면 useSafeArea가 safeAreaInset* global props를 읽고, 값이 없으면 env(safe-area-inset-*)를 씁니다.
  • 이 경로는 다음 메이저 버전에서 제거될 예정입니다. 위 적용하기처럼 SeedProvider로 옮기세요.

Last updated on

목차