安全区域

在移动浏览器中，内容有时会因为状态栏或主页指示器等系统 UI 而被遮挡。Apps in Toss SDK 为了防止这种情况，提供了一个以像素为单位计算屏幕安全区域（Safe Area）间距值的函数。

尤其是在 iPhone X 及以上设备或部分 Android 设备上，使用全屏的网页应用时，系统 UI 经常会遮挡内容。使用下面的函数，就能轻松调整间距，让内容安全显示。

SafeAreaInsets

当屏幕模式改变时 safearea 可以确认值。切换屏幕时也可以获取安全区域信息，或者订阅变更。使用此功能，即使在各种设备环境中也能实现稳定的 UI。

• SafeAreaInsets.get() : 当前屏幕模式的 safearea 值。
• SafeAreaInsets.subscribe() : 每当屏幕模式改变时 safearea 订阅值变化。

游戏内 X 按钮坐标

X 按钮默认包含在框架中提供。屏幕的 右上角固定在这里，位置可以按如下方式计算。

• X轴: safeAreaInsetsValue.right + 10
• Y轴: safeAreaInsetsValue.top + 5 (iOS) / safeAreaInsetsValue.top +10 (Android)

如果游戏内按钮与框架的 X 按钮重叠，可能会在审核过程中被退回。

示例

import { SafeAreaInsets } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

interface SafeAreaInsets {
  top: number;
  bottom: number;
  left: number;
  right: number;
}

function Page() {
  const [safeAreaInsetsValue, setSafeAreaInsetsValue] = useState<SafeAreaInsets>(() => SafeAreaInsets.get());
  // 导航栏顶部留白：safeAreaInsetsValue.top
  // 导航栏右侧留白：safeAreaInsetsValue.right + 10

  useEffect(() => {
    const cleanup = SafeAreaInsets.subscribe({
      onEvent: (insets) => {
        setSafeAreaInsetsValue(insets);
      },
    });
    return () => cleanup();
  }, []);

  // ...
}

getSafeAreaInsets

此函数仅可在 SDK 1.4.6 版本之前使用

从 1.4.7 版本起已被弃用 了

import { getSafeAreaInsets } from '@apps-in-toss/web-framework';

const insets = getSafeAreaInsets();
// 示例返回值：{ top: 44, bottom: 34 }

返回的对象包含以下属性。

• top: 为了不被顶部状态栏遮挡而需要预留的边距。
• bottom: 为了不被底部 Home 指示条遮挡而需要预留的边距。

这个值在制作适配整个屏幕(视口)时经常使用。例如，可以给底部固定按钮留出间距，或让顶部标题栏不与状态栏重叠。

应用底部留白示例

这是给底部固定按钮留出间距，以免与 Home 指示条重叠的示例。

import { getSafeAreaInsets } from '@apps-in-toss/web-framework';

const insets = getSafeAreaInsets();

const Button = () => {
  return (
    <div style={{ paddingBottom: `${insets.bottom}px` }}>
      <button>确认</button>

  );
};

应用顶部留白示例

这是给顶部固定标题栏留出间距，以免与状态栏重叠的示例。

import { getSafeAreaInsets } from '@apps-in-toss/web-framework';

const insets = getSafeAreaInsets();

const Header = () => {
  return (
    <div style={{ paddingTop: `${insets.top}px` }}>
      <h1>标题</h1>

  );
};

useSafeAreaInsets

为了防止在移动浏览器中内容被状态栏或主页指示器等系统 UI 遮挡的问题，它会以像素单位计算屏幕安全区域（Safe Area）的间距值。 useSafeAreaInsets 可在使用 ReactNative 开发时使用。

import { useSafeAreaInsets } from '@granite-js/native/react-native-safe-area-context';
const { top: safeAreaTop, right: safeAreaRight } = useSafeAreaInsets();
// 导航栏顶部间距：safeAreaTop
// 导航栏右侧间距：safeAreaRight + 10