@hecom/react-native-foldable

React Native 多折叠屏幕自适应布局库 三折叠 / 双折叠 / iPad / 平板 / 鸿蒙 (HarmonyOS) 全支持

---

特性

能力	说明
📱 自动识别设备类型	手机 / iPad / 双折叠 / 三折叠 / 鸿蒙
🔄 实时监听折叠变化	FOLDED → TRI_HALF → TRI_FULL 毫秒级响应
📐 响应式断点系统	xs/sm/md/lg/xl/xxl（全部可自定义）
🧭 导航布局建议	自动切换「底部 Tab」↔「左侧永久侧边栏」
🧩 即插即用组件	AdaptiveLayout / SidebarLayout / FoldAwareView
💡 纯 JS，无原生模块	无需 pod install / gradle 改动
🔧 完整 TypeScript	全类型定义导出

---

安装

npm install @hecom/react-native-foldable
# 或
yarn add @hecom/react-native-foldable

无额外原生依赖，开箱即用。

---

快速集成

Step 1：根组件包裹 Provider

// App.tsx
import { FoldableProvider } from '@hecom/react-native-foldable'

export default function App() {
  return (
    <FoldableProvider config={{ debug: __DEV__ }}>
      <RootNavigator />
    </FoldableProvider>
  )
}

Step 2：页面中使用 Hook

import { useFoldableScreen } from '@hecom/react-native-foldable'

function HomeScreen() {
  const { foldState, layoutMode, showSidebar, isTriFold, width } = useFoldableScreen()

  return (
    <View style={{ padding: width > 840 ? 24 : 16 }}>
      <Text>折叠状态：{foldState}</Text>
      <Text>布局模式：{layoutMode}</Text>
    </View>
  )
}

导航与组件的完整适配方案，请参阅 NAVIGATION.md。

---

Class 组件用法

Hooks 只能在函数组件中使用。如果项目中存在 class 组件，可通过以下三种方式接入。

方式一：withFoldableScreen HOC（推荐，适合叶节点组件）

通过高阶组件将折叠屏状态以 props.foldable 注入 class 组件。注意：HOC 返回的是函数组件，无法被继承，请勿对父类/基类使用此方式。

import { withFoldableScreen } from '@hecom/react-native-foldable'
import type { FoldableScreenInfo } from '@hecom/react-native-foldable'

interface Props {
  foldable: FoldableScreenInfo  // 由 HOC 自动注入
  title: string                 // 业务自有 props
}

class DetailScreen extends React.Component<Props> {
  render() {
    const { foldable, title } = this.props
    return (
      <View style={{ padding: foldable.showSidebar ? 24 : 16 }}>
        <Text>{title}</Text>
        <Text>{foldable.foldState} / {foldable.layoutMode}</Text>
      </View>
    )
  }
}

export default withFoldableScreen(DetailScreen)
// 使用时不需要传入 foldable prop：<DetailScreen title="详情" />

方式二：static contextType（推荐用于继承场景）

static contextType 会被子类自动继承，适合存在基类/子类继承关系的组件树。

import { FoldableContext } from '@hecom/react-native-foldable'
import type { FoldableContextValue } from '@hecom/react-native-foldable'

// 基类：声明一次，所有子类自动继承
class BaseScreen extends React.Component {
  static contextType = FoldableContext
  declare context: FoldableContextValue

  // 可封装 getter 方便子类访问
  get foldable() { return this.context.screenInfo }
}

// 子类：直接继承，无需额外声明
class HomeScreen extends BaseScreen {
  render() {
    const { foldState, width, showSidebar } = this.foldable
    return (
      <View style={{ flexDirection: showSidebar ? 'row' : 'column' }}>
        <Text>宽度：{width}dp，折叠态：{foldState}</Text>
      </View>
    )
  }
}

class DetailScreen extends BaseScreen {
  render() {
    const { columns } = this.foldable  // ✅ 直接可用
    return <Text>推荐列数：{columns}</Text>
  }
}

方式三：FoldableContext.Consumer（Render Props）

适合需要在 JSX 局部区域响应折叠状态，无需改造整个组件。

import { FoldableContext } from '@hecom/react-native-foldable'

class ProfileScreen extends React.Component {
  render() {
    return (
      <FoldableContext.Consumer>
        {({ screenInfo }) => (
          <View style={{ padding: screenInfo.isWideScreen ? 32 : 16 }}>
            <Text>列数：{screenInfo.columns}</Text>
          </View>
        )}
      </FoldableContext.Consumer>
    )
  }
}

---

Hooks API

useFoldableScreen() — 完整状态

const {
  width, height,            // 窗口尺寸(dp)
  screenWidth, screenHeight,// 物理屏尺寸(dp)
  foldState,   // FOLDED | HALF_FOLDED | UNFOLDED | TRI_HALF | TRI_FULL | UNKNOWN
  deviceType,  // PHONE | TABLET | FOLDABLE | TRI_FOLDABLE | IPAD | DESKTOP
  layoutMode,  // SINGLE | DUAL | TRI | SIDEBAR | SIDEBAR_DUAL
  breakpoint,  // 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'
  orientation, // PORTRAIT | LANDSCAPE
  columns,     // 推荐列数
  isTablet, isFoldable, isTriFold, isPad, isHarmony,
  showSidebar, isWideScreen,
} = useFoldableScreen()

useBreakpoint() — 响应式断点

const { breakpoint, up, down, between, is } = useBreakpoint()

up('md')              // 当前宽度 ≥ 600dp
down('lg')            // 当前宽度 < 840dp
between('md', 'xl')   // 600dp ≤ 当前宽度 < 1200dp
is('lg')              // 精确等于 lg 断点

useAdaptiveStyle() — 响应式样式（mobile-first 叠加）

const style = useAdaptiveStyle({
  base: { padding: 12, borderRadius: 8 },
  md:   { padding: 16 },
  lg:   { padding: 24, borderRadius: 12 },
  xl:   { padding: 32 },
})

useAdaptiveValue() — 响应式值

const fontSize   = useAdaptiveValue({ base: 14, md: 16, lg: 18, xl: 20 })
const numColumns = useAdaptiveValue({ base: 1, md: 2, lg: 3, xl: 4 })

useFoldStateChange() — 折叠变化事件

useFoldStateChange((nextState, prevState, info) => {
  LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut)
})

useLayoutModeChange((next, prev) => {
  console.log(`布局模式: ${prev} → ${next}`)
})

---

折叠状态说明

FoldState	触发条件	典型场景
FOLDED	完全折叠	Z Fold 折叠 (~374dp) / Mate XT 折叠 (~499dp)
HALF_FOLDED	帐篷/桌面模式（宽高相近）	Z Fold 半折
UNFOLDED	双折叠完全展开	Z Fold 全开 (~882dp)
TRI_HALF	三折叠展开一屏	Mate XT 半展 (~800dp)
TRI_FULL	三折叠三屏全开	Mate XT 全展 (~1008dp)
UNKNOWN	无折叠状态	iPad / 安卓平板

断点说明

断点	最小宽度	场景
xs	0	超小屏
sm	360dp	手机、折叠态
md	600dp	大屏手机、折叠半开
lg	840dp	平板、iPad、折叠全开
xl	1200dp	三折叠全开、大平板
xxl	1600dp	超大屏/桌面

---

三折叠识别原理

1. 初始化记录当前宽度（归桶精度 40dp）
2. 每次 Dimensions 变化（防抖 150ms）记录新宽度桶
3. 历史出现 ≥ 3 个宽度桶 → 标记为 TRI_FOLDABLE
4. 最大宽度 ≥ triFoldThreshold(900dp) → 也视为 TRI_FOLDABLE
5. 折叠状态：≥900dp=TRI_FULL | ≥600dp=TRI_HALF | <600dp=FOLDED

冷启动识别准确度：

冷启动状态	宽度	首帧识别结果
TRI_FULL 全展开	~1008dp	✅ 直接识别（≥ 900dp 阈值命中）
TRI_HALF 半展开	~800dp	⚠️ 被识别为 TABLET，会话内展开至 TRI_FULL 后自动修正
FOLDED 折叠态	~499dp	⚠️ 被识别为 PHONE，展开至 TRI_FULL（≥900dp）后自动修正

原因：纯 JS 方案无法访问系统级折叠 API（Android WindowManager.FoldingFeature），TRI_HALF（~800dp）与普通 Android 平板宽度重叠，仅凭单次尺寸快照无法区分。

如需首帧精确识别（如 Mate XT 专属应用），可通过 deviceTypeHint 手动指定：

import DeviceInfo from 'react-native-device-info'
import { DeviceType } from '@hecom/react-native-foldable'

const model = await DeviceInfo.getModel()  // e.g. "HUAWEI Mate XT"

<FoldableProvider config={{
  deviceTypeHint: model.includes('Mate XT') ? DeviceType.TRI_FOLDABLE : undefined,
}}>

---

鸿蒙 (HarmonyOS) 支持

自动检测以下情况：

• Platform.OS === 'harmony' 或 'ohos'（react-native-harmony）
• Platform.constants 中包含 harmonyos 关键字

折叠检测逻辑与 Android 完全一致，无需额外配置。

---

目录结构

src/
├── types/index.ts              全部 TypeScript 类型
├── core/
│   ├── constants.ts            默认常量与阈值
│   ├── DimensionManager.ts     屏幕尺寸单例（防抖+历史追踪）
│   ├── PlatformDetector.ts     平台/设备识别 + 断点计算
│   └── FoldStateDetector.ts    折叠状态推断引擎（核心算法）
├── context/
│   ├── FoldableContext.ts      React Context 定义
│   └── FoldableProvider.tsx    全局 Provider
├── hooks/
│   ├── useFoldableScreen.ts    完整屏幕信息
│   ├── useScreenLayout.ts      布局模式快捷访问
│   ├── useBreakpoint.ts        断点工具
│   ├── useAdaptiveStyle.ts     响应式样式/值
│   └── useFoldStateChange.ts   状态变化监听
├── components/
│   ├── FoldAwareView.tsx       render-prop 感知容器
│   ├── AdaptiveLayout.tsx      多栏自适应布局
│   └── SidebarLayout.tsx       侧边导航骨架
├── navigation/
│   ├── useFoldableNavigation.ts         导航建议 Hook
│   └── FoldableNavigationContainer.tsx  一体化适配容器
└── index.ts                    公共 API 导出

---

License

MIT