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()로 읽어 변경을 구독합니다.
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가 함께 바뀝니다.
SeedProvider를 중첩하면 생략한 prop은 바깥 Provider의 값을 이어받습니다.
Liquid Glass (iOS)
Chip과 FloatingActionButton은 iOS Liquid Glass로 그릴 수 있습니다. 호스트 flag와 glassEffect가 모두 켜져야 glass로 그립니다.
| prop | 타입 | 넘기는 곳 | 생략했을 때 |
|---|---|---|---|
supportsLiquidGlass | boolean | SeedProvider(앱 root). 호스트가 Liquid Glass를 그릴 수 있을 때 true | 바깥 값, 없으면 false |
glassEffect | boolean | { 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를 지원하는 XElementblur-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-onlyclass를 줬다면 그 트리를 같은 값의ColorModeProvider로 감싸세요(Theming).
넘긴 값 읽기
useSeedContext()는 SeedProvider가 받은 값을 그대로 돌려줍니다. px 문자열 변환이나 env() fallback은 하지 않습니다. 화면에 적용할 Safe Area 값이 필요하면 useSafeArea를 사용하세요.
Global Props 직접 읽기
이전 버전의 SEED는 특정 호스트 앱의 global props 키(theme, motion, safeAreaInset*)를 직접 읽었습니다.
기존 앱이 바로 깨지지 않도록 다음 메이저 버전 전까지는 SeedProvider에 넘기지 않은 값만 이 키에서 채웁니다.
- 키가 실제로 있어 사용되면 개발 빌드에서 키마다 한 번 경고합니다. 키가 없는 호스트에서는 경고하지 않습니다.
safeAreaInsets를 생략하면useSafeArea가safeAreaInset*global props를 읽고, 값이 없으면env(safe-area-inset-*)를 씁니다.- 이 경로는 다음 메이저 버전에서 제거될 예정입니다. 위 적용하기처럼
SeedProvider로 옮기세요.
Last updated on