# @facilitronworks/react-native-windows-modal 中文文档

规范地址：https://npmcn.com/package/%40facilitronworks/react-native-windows-modal/

版本：0\.1\.0-pre\.1
npm 元数据更新时间：2026-07-21T13:42:55.010Z
中文译文更新时间：2026-11-14T08:17:24.496Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40facilitronworks/react-native-windows-modal
原文对照：https://npmcn.com/package/%40facilitronworks/react-native-windows-modal/?lang=original
项目主页：https://github.com/FacilitronWorks/react-native-windows-modal#readme
源码仓库：https://github.com/FacilitronWorks/react-native-windows-modal

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

- 包体积（解压后）：16.6 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0，react-native \>=0\.76\.0，react-native-paper \>=5\.0\.0
- 首次发布：2026-07-18T15:06:35.809Z
- 最新版本发布：2026-07-21T13:42:54.847Z
- 近 30 天下载量：4248（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

反应-native'的倒置取而代之的是实际上在反应-native-windows新架构上起作用,其中原生的WindowsModalHostView使透明的弹性内容成为一空而不可关闭的外壳. 代表到真实的每层楼

## 安装

```sh
npm install @facilitronworks/react-native-windows-modal
```

也可以使用：`pnpm add @facilitronworks/react-native-windows-modal`、`yarn add @facilitronworks/react-native-windows-modal`、`bun add @facilitronworks/react-native-windows-modal`

## README

# @facilitronworks/ react-native-windows-models (英语)

A 类 **反应内置物的倒入替换 `<Modal>`** 帮助 **反应原生窗口** 新架构(结构/组成),核心 `<Modal>` 没有.

JS/TSX只——没有本土代码,没有自动连接,没有重建.

> **状况:释放前`0.1.0-pre.1`) (中文(简体) ).** 取自一款航运出品的Windows app (RNW 0.83.2),其中它取代了应用程序中每一个被破坏的模式.
> 
> **这里所证实的是:** 见 [核查状况](https://npmcn.com/package/%40facilitronworks/react-native-windows-modal/#readme-verification-status)。 。 。 .

## 为什么会这样

关于RNW新阵容, `<Modal>` 由当地人支持 `WindowsModalHostView` (单位:千美元)`Microsoft.ReactNative/Fabric/Composition/Modal`) (中文(简体) ). 这个部分确实 **没有** 使应用程序覆盖iOS和Android的方式。 它旋转起一个 **单独的顶级操作系统窗口** —— 说 `DesktopPopupSiteBridge` + 键 `OverlappedPresenter.IsModal(true)` ——拥有自有的原生标题栏,边框和收紧(X)按钮,以及从孩子的布局框起的窗口大小(`ContentSizePolicy::None` → `AdjustWindowSize`) (中文(简体) ).

两种后果打破了现实世界的模式:

**1\. 联合国. `transparent` + 弹性内容使外壳为空而不可关闭.** 绝大多数常见的模式是透明的宿主,上面有满血的孩子:

```tsx
<Modal transparent visible={open} onRequestClose={close}>
  <View style={{ flex: 1 }}>…</View>
</Modal>
```

内部a _内容大小_ 弹出没有限制大小 `flex: 1` 要填充,所以框架措施 `{0, 0}`, (中文(简体) ), `AdjustWindowSize` 保释金,你得到一个空的窗口。 更糟糕的是,这是 **粘贴**:内置的关闭按钮从未挂起, 因为内容从未列出, 而本地标题栏 X **发射 `onRequestClose`** 它没有关闭窗口本身。 如果你的处理器在内容上 从来没有提供, 没有出路的方式.

**2\. 不透明的全屏内容成为第二个桌面窗口.** 与标题栏和铬完全相同——在iOS和Android上生成的同一种代码与申请表一样.

### 修补

`react-native-paper`是因为 `<Modal>` 工作在RNW 正是因为它使 在树上 `<Portal>` 覆盖在 **同一个窗口/岛屿** ——不涉及本土模式主机. 此软件包反映了标准背后的处理方式 `<Modal>` API : (英语)

-   **在视窗上 :** 调制 `children` 进入绝对位置的根层 `<Portal>` 重叠. `StyleSheet.absoluteFill` 给上面一个 _确定大小_,这正是内容大小的本地弹出无法提供的——所以 `flex: 1` 孩子们排好队.
-   **在其他平台上:** 代表们,请各位 `react-native` `<Modal>`,道具的传播没有改变。 iOS /Android / 网络行为是同义字节.

这意味着你可以在全球互换导入,只改变Windows的行为.

## 安装

```sh
npm install @facilitronworks/react-native-windows-modal
# or: yarn add @facilitronworks/react-native-windows-modal
```

**同伴依赖性 :** `react`, (中文(简体) ), `react-native`,以及 **`react-native-paper` 页:1** - 纸张 `Portal` 是覆盖主机,和纸 `useTheme()` 提供不透明模式的背景颜色.

**你一定有一个 `<PaperProvider>` (或赤裸地) `<Portal.Host>`安装在您的应用根.** 这就是"门户"带来的。 没有它,模式 使Windows上什么也没有.

```tsx
// app root
<PaperProvider>
  <App />
</PaperProvider>
```

## 使用量

```tsx
import WindowsModal from '@facilitronworks/react-native-windows-modal';

<WindowsModal transparent visible={open} onRequestClose={close}>
  <View style={{ flex: 1, justifyContent: 'center' }}>
    …
  </View>
</WindowsModal>
```

最简单的是全项目的进口互换:

```diff
- import { Modal } from 'react-native';
+ import WindowsModal as Modal from '@facilitronworks/react-native-windows-modal';
```

两者都有一个命名的导出( T)`WindowsModal`)和默认导出.

## 支持的道具, 以及Windows上忽略的内容

每个 `ModalProps` 在非窗口平台上逐字转发。 打开 **窗口**只有对树上覆盖有意义的道具才会被尊重:

| Prop | 窗口行为 |
| --- | --- |
| `visible` | 荣誉—— `false` 调制 `null`。 。 。 . |
| `transparent` | 被尊贵的——当虚伪的时候 `backdropColor ?? theme.colors.background`。 。 。 . |
| `backdropColor` | 荣誉( 仅当不是时) `transparent`) (中文(简体) ). |
| `onRequestClose` | 荣誉——也 **所需经费** 完全可以呈现出一团一团的背景. |
| `onShow` | 手动调用 `visible` 翻转真实,以维护RN合同. |
| `unmask` | 荣誉——何时 `true`前进 `fsClass="fs-unmask"` 上到上方以在 FullStory 会话中重放它。 默认为 `false` (口罩声). 见 [会话重播/ 完整的故事](https://npmcn.com/package/%40facilitronworks/react-native-windows-modal/#readme-session-replay--fullstory)。 。 。 . |
| `animationType` | **忽见.** 没有动画——翻版立即出现. |
| `onDismiss`, (中文(简体) ), `statusBarTranslucent`, (中文(简体) ), `hardwareAccelerated`, (中文(简体) ), `supportedOrientations`, (中文(简体) ), `presentationStyle`, (中文(简体) ), `navigationBarTranslucent` | **已忽略** (移动/本地窗口概念). |

## 会话重播/ 完整的故事

Full Story (反应原生) **默认情况下所有内容** 并揭示一个元素,当它携带 `fs-unmask` 标记。 在 Windows 上,此组件使其覆盖为平面 `react-native` `View`和内部应用不同 `View` 把它取出 硬码 `fsClass="fs-unmask"` ——模式为: **蒙上面具** 在会话重播.

解开它,通过 `unmask`数字 :

```tsx
<WindowsModal transparent visible={open} onRequestClose={close} unmask>
  …
</WindowsModal>
```

这个向前 `fsClass="fs-unmask"` 输入覆盖 `View`默认 `false` (masked)——安全的FullStory默认——所以只有在模式内容在重放中安全显示时才选择. 只用Windows(覆盖为只用Windows);它是其他平台的惰性.

## 你会撞上陷阱

-   **没有 `<Portal.Host>` 意味着没有模式.** 最有可能的失败 如果你的应用根没有 `PaperProvider`, Windows 路径默默地使无所事事.
-   **这不是一种真正的模式——它不限制焦点.** 这是同一窗口的上盖。 键盘焦点和屏幕阅读器转接仍然可以到达下方的应用树. 不要依赖它 任何安全或正确的关键.
-   **逃不关.** 原生标题栏-X已去掉(这就是重点),但没有任何东西可以取而代之——如果需要的话,可以自己接通钥匙处理.
-   **只有在你经过的时候背景才存在 `onRequestClose`。 。 。 .** 没有那个道具就没有 `Pressable` scrim,所以敲门什么也没有。 这是蓄意的——不能关闭任何东西的圈套.
-   **`animationType` 默默地在Windows上无所作为.** Modals 立即出现并消失;一个依赖于滑入的设计会看起来突然.
-   **亲兄弟Z令.** 套装 `zIndex`编号 :`elevation` 9999,但其中两个在Portal顺序中同时打开堆栈,而不是以任何明确的优先级.
-   **`transparent` 行为和你可能读的不一样.** 它是否控制着 _本构成部分_ 绘制一个背景填充,而不是OS窗口是否透明(没有OS窗口).

## 核查状况

**已验证**,在这个精确的包装来源上:

-   **类型检查干净** 严格模式下TypeScript 5.9,按实值解决 `react`, (中文(简体) ), `react-native`, (中文(简体) ), `react-native-paper` 财务报告和审定财务报表 `@types/react` 设施(RN 0.83.2,第5.14.5页).
-   `npm pack` 生产含有实际TSX源的柏油球.

**未核实** - 不假定其中任何一项:

-   **运行时间行为 _此软件包_。 。 。 .** 逻辑是生产-在从它提取的应用程序中被证明,但这里所打包的代码并没有被渲染出——不是在Windows上,也不是在任何平台上.
    
-   **两个取出变化是新而未被执行的.** 最初使用的应用程序本地模块;这两个模块都用于此软件包:
    
    1.  上面的容器是一个应用程序内部 `View` 包装( 只添加一个完整的故事) `fsClass` 丙子)-现在平地上 `react-native` `View` 重新应用 `fsClass="fs-unmask"` 仅在 [`unmask`](https://npmcn.com/package/%40facilitronworks/react-native-windows-modal/#readme-session-replay--fullstory) 设置了道具;
    2.  背景颜色来自一个 app- local 主题背景 ~ 现在 `useTheme()` 从反应-内生纸.
    
    这些编译和打字检查;没有在屏幕上看到它们。 论文 `useTheme()` 特别是假设您的纸质主题 `colors.background` 是非透明模式后面的颜色.
    
-   没有实例应用,没有自动化测试,没有CI.
    
-   行为 **筑巢** 模式以及与其他门户网站用户的互动未经测试.
    

## 许可证

麻省理工学院

## 常见问题

### @facilitronworks/react-native-windows-modal 是什么？

反应-native'的倒置取而代之的是实际上在反应-native-windows新架构上起作用,其中原生的WindowsModalHostView使透明的弹性内容成为一空而不可关闭的外壳\. 代表到真实的每层楼

### 如何安装 @facilitronworks/react-native-windows-modal？

在项目目录运行 npm install @facilitronworks/react-native-windows-modal，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-native（\>=0\.76\.0）、react-native-paper（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @facilitronworks/react-native-windows-modal 支持 TypeScript 吗？

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

### @facilitronworks/react-native-windows-modal 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @facilitronworks/react-native-windows-modal 可以商用吗？

@facilitronworks/react-native-windows-modal 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @facilitronworks/react-native-windows-modal 的下载量有多少？

根据 npm 官方下载统计，@facilitronworks/react-native-windows-modal 在 2026/10/14 – 2026/11/12 这 30 天内被下载 4,248 次，日均约 142 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @facilitronworks/react-native-windows-modal 还在维护吗？

最新版本 0\.1\.0-pre\.1 发布于 2026/07/21（3 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。