@aashu-dubey/capacitor-statusbar-safe-area

中文文档
5.0.0发布于 2026/08/27MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 4854

在Android & iOS上获取状态栏高度和安全区域设置.

中文使用文档
文档目录9 节
  1. 安装
  2. 使用量
  3. CSS 变量
  4. HTML 标记
  5. 电容版本支持
  6. API 密码
  7. 获取状态BarHeight ()
  8. 获取安全区设置( C)
  9. 接口

电容器状态栏安全区域

在Android & iOS上获取状态栏高度和安全区域设置.

npm npm Install Size

安装

npm install @aashu-dubey/capacitor-statusbar-safe-area
npx cap sync

使用量

import { SafeArea } from '@aashu-dubey/capacitor-statusbar-safe-area';

const getStatusBarHeight = async () => {
  const { height } = await SafeArea.getStatusBarHeight();
  return height; // Ex. 29.090909957885742
};

const getSafeAreaInsets = async () => {
  const insets = await SafeArea.getSafeAreaInsets();
  return insets; // Ex. { "bottom":34, "top":47, "right":0, "left":0 }
};

CSS 变量

软件包还显示 CSS 变量,因为您需要调用 injectCSSVariables 方法在您的 platform.ready() 函数或当应用程序系统 UI 可见度改变时

import { SafeAreaController } from '@aashu-dubey/capacitor-statusbar-safe-area';

const injectSafeAreaVariables = () => {
  SafeAreaController.injectCSSVariables();
};

然后可以在您的 CSS 文件中使用

.myContainer {
  // '--status-bar-height' & '--safe-area-inset-top' would most probably be same
  margin-top: var(--status-bar-height);
}

.myElement {
  padding-top: var(--safe-area-inset-top);
  padding-left: var(--safe-area-inset-left);
  padding-right: var(--safe-area-inset-right);
  padding-bottom: var(--safe-area-inset-bottom);
}

HTML 标记

除上述选项外,该插件还导出 a <safe-area> 自定义网络组件.

登记和使用

在您的应用程序初始化中注册自定义元素( 例如) . main.ts, (中文(简体) ), app.component.ts,或根组件),或仅在组件内使用:

import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

然后将您想要应用的安全区域间距的内容与 <safe-area> 标签 :

<safe-area>
  <!-- Content here -->
</safe-area>

属性

有两个属性,可以和 safe-area 网络组件控制它的行为, mode 打开 edges。 。 。 .

<safe-area mode="margin" edges="top,left,right"></safe-area>

更多细节 这里。 。 。 .

框架实例

角质

你会得到一个错误 <safe-area> 是Angular 编译器的未知元素。 通过添加 CUSTOM_ELEMENTS_SCHEMA 到您的独立组件或模块计划.

1. 独立的构成部分(Angular 14+)
// your.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

@Component({
  selector: 'app-your-component',
  standalone: true,
  template: `
    <safe-area>
      <!-- Other content -->
    </safe-area>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class YourComponent {}
2. 恩格穆尔

修改宣布您组件的模块以允许自定义元素 :

// your-component.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class YourComponentModule {}

然后在组件中注册自定义元素 :

// app.component.ts or your-component.ts
import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();
<!-- your.component.html -->
<safe-area>
  <!-- Other content -->
</safe-area>

反应
import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

const MyComponent = () => {
  return <safe-area>{/* Other content */}</safe-area>;
};

您可能需要创建一个 *.d.ts react 中自定义元素的文件 :

import type { SafeAreaHTMLProps } from '@aashu-dubey/capacitor-statusbar-safe-area';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'safe-area': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & SafeAreaHTMLProps;
    }
  }
}

export {};

阴道
<script setup lang="ts">
  import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

  registerSafeAreaElement();
</script>

<template>
  <safe-area>
    <!-- Other content -->
  </safe-area>
</template>

确保您启用 承认本地习惯元素 内 vite.config.ts数字 :

// vite.config.ts > plugins
vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === 'safe-area',
    },
  },
}),

还有,为了 合适的打字支持 内 .vue <template>创建一个 *.d.ts 文件并添加以下代码:

import type { HTMLAttributes, PublicProps } from 'vue';
import type { SafeAreaHTMLProps } from '@aashu-dubey/capacitor-statusbar-safe-area';

type DefineCustomElement<
  ElementType extends HTMLElement,
  SelectedAttributes extends keyof ElementType = keyof ElementType,
> = new () => ElementType & {
  $props: HTMLAttributes & Partial<Pick<ElementType, SelectedAttributes>> & PublicProps;
};

type SafeAreaAttributes = 'mode' | 'edges';

declare module 'vue' {
  interface GlobalComponents {
    'safe-area': DefineCustomElement<SafeAreaHTMLProps, SafeAreaAttributes>;
  }
}

export {};
与安全部门改革

插件及其功能是针对客户端的,在服务器一侧使用时可能会出错 10号 财务报告和审定财务报表 11号,因此始终确保只访问客户端的插件.

以下是一些可能使用插件的解决方案的例子 :

类型脚本 / DOM API

软件包自动注册 'safe-area' 内 HTMLElementTagNameMap标准DOM方法,例如 document.querySelector('safe-area') 财务报告和审定财务报表 document.createElement('safe-area') 将自动输入为 SafeAreaElement数字 :

const el = document.querySelector('safe-area'); // typed as SafeAreaElement | null
if (el) {
  el.mode = 'margin';
  el.edges = 'top,bottom';
}

电容版本支持

电容器插件版本
v8.x (中文(简体) )5.0.0 (单位:千美元)
v7.x (中文(简体) )4.0.0 (单位:千美元)
v6.x (中文(简体) )3.0.0 (单位:千美元)
页:12.1.0 国家
v4.x (英语)= 1.1.0 = 2.0.0 (中文(简体) )
ưμ㼯a<= 1.0.1

API 密码

获取状态BarHeight ()

getStatusBarHeight() => Promise<{ height: number; }>

在Android和iOS上获取状态栏高度,并在Web上返回0.

回返情况: Promise<{ height: number; }>


获取安全区设置( C)

getSafeAreaInsets() => Promise<SafeAreaInset>

获取Android和iOS的安全区域设置,并在Web上返回0所有.

回返情况: Promise<SafeAreaInset>


接口

安全区设置

Prop类型说明
topnumber安全区域内置值位于顶端 .
bottomnumber安全区域在底部内置值 .
leftnumber左侧的安全区域设置值 .
rightnumber安全区域在右侧设置值 .

安全区HTMLProps

Prop类型默认说明
mode'padding' | 'margin''padding'是否将安全区域设置为 padding 或者说 margin。 。 。 .
edgesstring所有边缘以逗号分隔的边缘列表来应用设置 .

例如,只应用上,上,下和下, edges="top,left,right"。 。 。 .

版本与发布记录

@aashu-dubey/capacitor-statusbar-safe-area 共发布 10 个版本,首次发布于 2022/03/20;过去 12 个月发布了 1 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/08/272 个月前
4.0.02025/02/271.7 年前
3.0.02024/06/032 年前
2.1.22024/06/022 年前
2.1.12023/06/183 年前
2.1.02023/05/143 年前

关于 @aashu-dubey/capacitor-statusbar-safe-area 的常见问题

@aashu-dubey/capacitor-statusbar-safe-area 是什么?

在Android & iOS上获取状态栏高度和安全区域设置.

如何安装 @aashu-dubey/capacitor-statusbar-safe-area?

在项目目录运行 npm install @aashu-dubey/capacitor-statusbar-safe-area,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@capacitor/core(>=8.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@aashu-dubey/capacitor-statusbar-safe-area 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@aashu-dubey/capacitor-statusbar-safe-area 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@aashu-dubey/capacitor-statusbar-safe-area 可以商用吗?

@aashu-dubey/capacitor-statusbar-safe-area 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@aashu-dubey/capacitor-statusbar-safe-area 的下载量有多少?

根据 npm 官方下载统计,@aashu-dubey/capacitor-statusbar-safe-area 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,854 次,日均约 162 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@aashu-dubey/capacitor-statusbar-safe-area 还在维护吗?

最新版本 5.0.0 发布于 2026/08/27(2 个月前);至今共发布 10 个版本,其中过去 12 个月发布了 1 个;首次发布于 2022/03/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。