# @aashu-dubey/capacitor-statusbar-safe-area 中文文档

规范地址：https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/

版本：5\.0\.0
npm 元数据更新时间：2026-08-26T21:25:18.153Z
中文译文更新时间：2026-11-06T05:20:39.474Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aashu-dubey/capacitor-statusbar-safe-area
原文对照：https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/?lang=original
项目主页：https://github.com/Aashu-Dubey/capacitor-statusbar-safe-area#readme
源码仓库：https://github.com/Aashu-Dubey/capacitor-statusbar-safe-area

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：66.4 kB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2022-03-19T20:50:48.436Z
- 最新版本发布：2026-08-26T21:25:17.824Z
- 近 30 天下载量：4854（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 1 个）

## 中文简介

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

## 安装

```sh
npm install @aashu-dubey/capacitor-statusbar-safe-area
```

也可以使用：`pnpm add @aashu-dubey/capacitor-statusbar-safe-area`、`yarn add @aashu-dubey/capacitor-statusbar-safe-area`、`bun add @aashu-dubey/capacitor-statusbar-safe-area`

## README

# 电容器状态栏安全区域

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

[![npm](https://img.shields.io/npm/v/@aashu-dubey/capacitor-statusbar-safe-area?style=flat-square)](https://www.npmjs.com/package/@aashu-dubey/capacitor-statusbar-safe-area) [![npm](https://img.shields.io/npm/dm/@aashu-dubey/capacitor-statusbar-safe-area?style=flat-square)](https://www.npmjs.com/package/@aashu-dubey/capacitor-statusbar-safe-area) [![Install Size](https://packagephobia.now.sh/badge?p=@aashu-dubey/capacitor-statusbar-safe-area)](https://www.npmjs.com/package/@aashu-dubey/capacitor-statusbar-safe-area)

## 安装

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

## 使用量

```typescript
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 可见度改变时

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

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

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

```scss
.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`,或根组件),或仅在组件内使用:

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

registerSafeAreaElement();
```

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

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

#### 属性

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

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

更多细节 [这里](https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/#readme-safeareahtmlprops)。 。 。 .

#### 框架实例

**角质**

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

##### 1\. 独立的构成部分(Angular 14+)

```ts
// 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\. 恩格穆尔

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

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

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

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

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

registerSafeAreaElement();
```

```html
<!-- your.component.html -->
<safe-area>
  <!-- Other content -->
</safe-area>
```
  
**反应**

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

registerSafeAreaElement();

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

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

```ts
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 {};
```
  
**阴道**

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

  registerSafeAreaElement();
</script>

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

确保您启用 [承认本地习惯元素](https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue) 内 `vite.config.ts`数字 :

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

还有,为了 [合适的打字支持](https://vuejs.org/guide/extras/web-components.html#non-vue-web-components-and-typescript) 内 `.vue` `<template>`创建一个 `*.d.ts` 文件并添加以下代码:

```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号](https://github.com/Aashu-Dubey/capacitor-statusbar-safe-area/issues/10) 财务报告和审定财务报表 [11号](https://github.com/Aashu-Dubey/capacitor-statusbar-safe-area/issues/11),因此始终确保只访问客户端的插件.

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

-   [纳克特Js( Vue)](https://github.com/Aashu-Dubey/capacitor-statusbar-safe-area/issues/10#issuecomment-1685089169)
-   [下一个JS( 反应)](https://github.com/Aashu-Dubey/capacitor-statusbar-safe-area/issues/11#issuecomment-1697267497)

#### 类型脚本 / DOM API

软件包自动注册 `'safe-area'` 内 `HTMLElementTagNameMap`标准DOM方法,例如 `document.querySelector('safe-area')` 财务报告和审定财务报表 `document.createElement('safe-area')` 将自动输入为 [`SafeAreaElement`](https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/src/element.ts)数字 :

```ts
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 (单位:千美元) |
| 页:1 | 2.1.0 国家 |
| v4.x (英语) | \= 1.1.0 = 2.0.0 (中文(简体) ) |
| ưμ㼯a | <= 1.0.1 |

## API 密码

-   [`getStatusBarHeight()`](https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/#readme-getstatusbarheight)
-   [`getSafeAreaInsets()`](https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/#readme-getsafeareainsets)
-   [接口](https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/#readme-interfaces)

### 获取状态BarHeight ()

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

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

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

* * *

### 获取安全区设置( C)

```typescript
getSafeAreaInsets() => Promise<SafeAreaInset>
```

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

**回返情况:** `Promise<[SafeAreaInset](https://npmcn.com/package/%40aashu-dubey/capacitor-statusbar-safe-area/#readme-safeareainset)>`

* * *

### 接口

#### 安全区设置

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`top`** | `number` | 安全区域内置值位于顶端 . |
| **`bottom`** | `number` | 安全区域在底部内置值 . |
| **`left`** | `number` | 左侧的安全区域设置值 . |
| **`right`** | `number` | 安全区域在右侧设置值 . |

#### 安全区HTMLProps

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| **`mode`** | `'padding' | 'margin'` | `'padding'` | 是否将安全区域设置为 `padding` 或者说 `margin`。 。 。 . |
| **`edges`** | `string` | 所有边缘 | 以逗号分隔的边缘列表来应用设置 .  
  
例如,只应用上,上,下和下, `edges="top,left,right"`。 。 。 . |

## 常见问题

### @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 和提交记录判断。