press-pix/common/utils/SAFE_AREA_GUIDE.md

基于 PixUI 的 Press 组件库

# Safe Area 工具使用指南

## 📦 提供的工具

### 1. React Hooks（推荐）

#### `useSafeAreaStyle()` - 获取样式对象
最简单的使用方式，适合大多数场景。

```tsx
import { useSafeAreaStyle } from 'src/local-logic/utils/use-safe-area';

function MyComponent() {
  // ✨ 只需一行代码！自动处理异步、状态更新
  const safeAreaStyle = useSafeAreaStyle();
  
  return (
    <div style={safeAreaStyle}>
      内容会自动应用安全区域的 padding
    </div>
  );
}
```

**可选参数：**
```tsx
// 只设置左边距
const leftOnly = useSafeAreaStyle({ right: false });

// 只设置右边距
const rightOnly = useSafeAreaStyle({ left: false });

// 与其他样式合并
<div style={{ ...safeAreaStyle, backgroundColor: 'red' }}>
```

#### `useSafeArea()` - 获取详细信息
如果需要显示具体数值或做更复杂的处理。

```tsx
import { useSafeArea } from 'src/local-logic/utils/use-safe-area';

function MyComponent() {
  const safeArea = useSafeArea();
  
  return (
    <div>
      <div>Left: {safeArea.left}px</div>
      <div>Right: {safeArea.right}px</div>
      <div>Padding Left: {safeArea.paddingLeft}px</div>
      <div>Padding Right: {safeArea.paddingRight}px</div>
    </div>
  );
}
```

### 2. 工具函数（Class 组件或特殊场景）

#### `getSafeAreaStyle()` - 获取样式对象
```tsx
import { getSafeAreaStyle } from 'src/local-logic/utils/safe-area';

class MyComponent extends Component {
  state = {
    safeAreaStyle: { paddingLeft: '0px', paddingRight: '0px' }
  };

  async componentDidMount() {
    // ⚠️ 需要等待数据准备完成
    const { tryGetSafeAreaInfo } = await import('src/local-logic/utils/safe-area');
    await tryGetSafeAreaInfo();
    
    // 然后更新状态
    this.setState({ 
      safeAreaStyle: getSafeAreaStyle() 
    });
  }

  render() {
    return (
      <div style={this.state.safeAreaStyle}>
        内容
      </div>
    );
  }
}
```

#### `getSafeAreaInfo()` - 获取详细信息
```tsx
import { getSafeAreaInfo } from 'src/local-logic/utils/safe-area';

const safeArea = getSafeAreaInfo();
// 返回：{ left, top, right, bottom, paddingLeft, paddingTop, paddingRight, paddingBottom }
```

## 🎯 使用建议

### ✅ 推荐做法

1. **函数组件 → 使用 Hooks**
   ```tsx
   function MyPage() {
     const safeAreaStyle = useSafeAreaStyle();
     return <div style={safeAreaStyle}>...</div>;
   }
   ```

2. **Class 组件 → 使用 Hooks（通过包装）**
   ```tsx
   // 创建一个 HOC
   function withSafeArea(Component) {
     return function(props) {
       const safeAreaStyle = useSafeAreaStyle();
       return <Component {...props} safeAreaStyle={safeAreaStyle} />;
     };
   }
   
   @withSafeArea
   class MyPage extends Component {
     render() {
       return <div style={this.props.safeAreaStyle}>...</div>;
     }
   }
   ```

3. **Class 组件 → 直接使用工具函数**
   ```tsx
   class MyPage extends Component {
     state = { safeAreaStyle: {} };
     
     async componentDidMount() {
       const { tryGetSafeAreaInfo, getSafeAreaStyle } = await import('src/local-logic/utils/safe-area');
       await tryGetSafeAreaInfo();
       this.setState({ safeAreaStyle: getSafeAreaStyle() });
     }
     
     render() {
       return <div style={this.state.safeAreaStyle}>...</div>;
     }
   }
   ```

### ❌ 不推荐做法

```tsx
// ❌ 不要在 render 中直接调用（会使用旧数据）
render() {
  return <div style={getSafeAreaStyle()}>...</div>;
}

// ❌ 不要忘记等待数据准备
componentDidMount() {
  // 缺少 await tryGetSafeAreaInfo()
  this.setState({ safeAreaStyle: getSafeAreaStyle() }); // 可能获取到旧数据
}
```

## 📝 完整示例

查看 [test.tsx](../app/views/test.tsx) 中的 `SafeAreaDemo` 组件，了解完整的使用示例。

## 🔧 技术细节

- **最小 padding**: 44px（即使设备返回 0，也会使用 44px）
- **数据获取**: 模块加载时自动初始化，通常在页面渲染前完成
- **超时时间**: 最多等待 3 秒获取数据
- **状态管理**: Hooks 自动管理状态，无需手动处理