# @facilitronworks/react-native-windows-image-picker 中文文档

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

版本：0\.1\.0-pre\.0
npm 元数据更新时间：2026-07-18T14:22:01.991Z
中文译文更新时间：2026-11-14T08:18:03.148Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：66.1 kB，20 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react-native \>=0\.76\.0，react-native-windows \>=0\.76\.0
- 首次发布：2026-07-18T14:22:01.352Z
- 最新版本发布：2026-07-18T14:22:01.750Z
- 近 30 天下载量：4245（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

一个本地图像和文档取取取器 TurboModule for React Endern Windows (新架构),由Windows支持. 存储。 拾取者. 文件打开选择器 .

## 安装

```sh
npm install @facilitronworks/react-native-windows-image-picker
```

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

## README

# @facilitronworks/ react-native-windows-image-采取器

一个本地人 **图像和文档拾取器** 涡轮模块用于 **反应原生窗口** 编辑 **新结构** (配置/组成),由 `Windows.Storage.Pickers.FileOpenPicker`。 。 。 .

> **状况:释放前`0.1.0-pre.0`),尚未发布至npm.** C++的实现取自于一种航运出品的Windows应用(RNW 0.83.2,Windows-on-ARM和x64),它可以回溯到真实的图像和文件后附上传流.
> 
> **建设-核查.** 被包装的窗体编译:自动链接到一个耗尽的 RNW 0.83.2 新存档应用中,并为ARM64调试而建立干净,生产 `RNWImagePicker.dll`, (中文(简体) ), `.winmd`, (中文(简体) ), `.lib` 财务报告和审定财务报表 `.pri`。 。 。 . `autolink-windows` 正确释放两者 `#include <winrt/RNWImagePicker.h>` 财务报告和审定财务报表 `packageProviders.Append(winrt::RNWImagePicker::ReactPackageProvider())`。 。 。 .
> 
> **尚未核实 :** 运行时间行为 _这个_ project的 DLL 在设备上的(来源是生产证明,但这个项目所建的二进制尚未被执行),x64和放行配置,还没有实例应用或CI构建. 等着 `0.1.0` 在生产中取决于它.
> 
> **自己盖起:** 首先运行 NuGet 恢复(`msbuild -restore`) (中文(简体) ). 没有它,CppWinRT目标 从来没有加载, `.idl` 文件流经经典 `midl.exe` 改为 `midlrt`和每个 `namespace` 声明失败 `MIDL2025`。 。 。 .

## 为什么会这样

React Industrial Windows 没有维护的文件/图像拾取器. 这不是一个疏忽——每一个上游门都尝试并关闭:

-   **`@react-native-documents/picker`** 已丢弃 Windows 和维护者 [拒绝收回](https://github.com/react-native-documents/document-picker/issues/759)数字 : _"数年无人加紧维持. 我觉得加入到这个回放中是不明智的(因为它会再次被维持下去)"_
-   **反应原生窗口核心** [没有计划运送一个](https://github.com/microsoft/react-native-windows/issues/14488)数字 : _"AFAIK没有计划 暴露一个内置的方法 进入窗口文件拾取器 为RNW... 你可能需要 暴露API自己,就像你说的, 用自己的涡轮模块。"_
-   **`expo-image-picker`** 没有 Windows 执行,以及 Expo 的 [增加平台支持](https://docs.expo.dev/modules/additional-platform-support/) 只覆盖了macOS和tvOS.
-   **`react-native-image-picker`** 自此已打开 Windows 请求 [2021 (英语)](https://github.com/react-native-image-picker/react-native-image-picker/issues/1835) 财务报告和审定财务报表 [2023 (英语)](https://github.com/react-native-image-picker/react-native-image-picker/issues/2136)都没有得到答复.

RNW的亲身经历 [本地模块文件](https://github.com/microsoft/react-native-windows-samples/blob/main/docs/native-modules-setup.md) 指向准确的这个结果: 发布您的自己的库 _"一个现存的图书馆并不存在(或者你没有修改它的权限)"_

### 相关的前款艺术

如果你需要的话 **文档/文件夹** 选取,看 [`@hbannro/rn-documents-picker-windows`](https://github.com/ClaudiuHBann/document-picker-windows) 首先,这是麻省理工学院,新建筑, 镜像 `@react-native-documents/picker` API,并正确解决了HWND问题. 它针对的是RNW 0.77,并且没有图像特有的表面(没有尺寸,基数64,或者图像受限制的过滤),这就是为什么这个包单独存在而不是作为它的PR存在的原因.

## 困难的部分是: `IInitializeWithWindow`

这是捕捉每个人的陷阱, 而这个代码值得分享的主要原因.

在一个 **WinAppSDK / Win32 桌面** 应用没有 `CoreWindow`A级 `FileOpenPicker` 试着亲亲一个, 找不到它 **掷出** 通常表面为不透明 `E_FAIL` 或绞刑,没有指向真正的原因。 采取者必须明确与应用软件的顶级相关联 `HWND` 通过经典的COM接口 `IInitializeWithWindow`数字 :

```cpp
#include <shobjidl_core.h>

auto initWithWindow = picker.as<::IInitializeWithWindow>();
initWithWindow->Initialize(ResolveHostWindow());
```

容易出错的另外两个制约因素:

1.  **选取必须运行在UI线上.** 对话框为模式并归应用程序窗口所有 。 这个模块以小的 `ResumeOnDispatcher` 在创建或显示拾取者之前, 使用 coroutine 等待器 .
2.  **这个 `HWND` 必须是真正的顶级窗口.** 此模块更喜欢从 `WinMain`,然后回到 `GetActiveWindow()` 财务报告和审定财务报表 `GetForegroundWindow()` ——两个有效的倒计时精确地 _因为_ 选择已经运行在拥有应用程序窗口的线条上.

## 安装

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

然后自动连接和重建:

```sh
npx react-native autolink-windows
npx react-native run-windows
```

这就是所有的建筑线。 货真价实 `windows/RNWImagePicker/RNWImagePicker.vcxproj` 加一个 `react-native.config.js` 宣布它为Windows的直接依赖,所以 `autolink-windows` 添加 `ProjectReference` 向您的应用项目发送服务商注册信息 您的生成 `AutolinkedNativeModules.g.cpp`。没有什么可以复制的,和 没什么可补充的 `.vcxproj`。 。 。 .

要求 **新结构** —— 说 `<RnwNewArch>true</RnwNewArch>` 在你的应用软件 `windows/ExperimentalFeatures.props`. 针对RNW 0.83.x.

## 一体化

自动链接注册 **模块** - 责任 `REACT_MODULE` 被捡起来 由这个图书馆自己 `ReactPackageProvider`,该调用 `AddAttributedModules(packageBuilder, true)` 代表你们 然后可以到达 来文人: `NativeModules.RNWImagePicker`,或者通过输入的包装 `src/index.ts` (见 [使用量](https://npmcn.com/package/%40facilitronworks/react-native-windows-image-picker/#readme-usage)) (中文(简体) ).

**手动一步还剩:主机窗口.** 自动链接无法注册您的 `HWND`所以这个钩子是你的 打过一次电话 `WinMain`在应用程序之后 窗口创建 :

```cpp
// <winrt/RNWImagePicker.h> is already pulled in for you by AutolinkedNativeModules.g.h
winrt::RNWImagePicker::ImagePicker::SetHostWindow(reinterpret_cast<uint64_t>(hwnd));
```

`SetHostWindow` 预测为静态 `ImagePicker` 运行时级相当 因为自动将您的应用程序连接起来 图书馆 **WinMD 投影** (单位:千美元)`<winrt/RNWImagePicker.h>`)但并非其生来 信头 — 和库链接作为自己的 DLL, 其导出只是 WinRT 启动入口 内部自由职能 `RNWImagePicker::SetHostWindow(void*)` 任何卖家仍然可以 直接来源.

为什么它很重要: 就是这个 _全数_ 取取器窗口的可靠来源 父母必须直接从 `AppWindow` rNW 主机 创建,而不是推断。 如果你跳过它 `GetActiveWindow` 编号 : `GetForegroundWindow` 倒计时通常有效 但"通常"不是你想要的 在模式对话框后.

> 未来的版本更可取 `ReactCoreInjection::GetTopLevelWindowId(context.Properties().Handle())` 这么说 `WinMain` 钩入可选. 目前的倒转链是实际已运出的版本,所以它是这里所发表的.

## 使用量

```ts
import {
  launchImageLibraryAsync,
  launchDocumentPickerAsync,
  isAvailable,
} from '@facilitronworks/react-native-windows-image-picker';

// Pick a single image
const result = await launchImageLibraryAsync({ base64: false });
if (!result.canceled) {
  const [asset] = result.assets!;
  console.log(asset.uri, asset.width, asset.height, asset.mimeType);
}

// Pick one or more arbitrary documents
const docs = await launchDocumentPickerAsync();
if (!docs.canceled) {
  for (const doc of docs.assets!) {
    console.log(doc.fileName, doc.fileSize, doc.mimeType);
  }
}
```

### 结果形状

```ts
{
  canceled: false,
  assets: [
    {
      uri: 'file:///.../LocalState/PickedFiles/<name>',
      fileName: 'photo.jpg',
      mimeType: 'image/jpeg',
      fileSize: 1048576,
      type: 'image',   // 'file' for documents
      width: 4032,     // images only
      height: 3024,
      base64: undefined,  // only when requested
      exif: null
    }
  ]
}
```

取消解决 `{ canceled: true, assets: null }` - 确实 **没有** 拒绝。 拒绝只针对真正的失败.

### 为什么要复制文件

每个选中的文件都被复制到 `LocalFolder\PickedFiles` 返回时 `uri` 点在该副本。 A 类 `StorageFile` 由拾取者交回的由经纪人调解的接入方式无法可靠地通过传递到其他子系统作为平坦路径;复制会给您一个稳定的位置,您可以读取,上传,反转. 模块在每个进程上扫描一次已过时的拷贝,因为没有其他东西可以删除它们.

## API 密码

| 函数 | 说明 |
| --- | --- |
| `launchImageLibraryAsync(options?)` | 选择单个图像( 仅图像文件类型) . |
| `launchDocumentPickerAsync(options?)` | 选择一个或多个任何类型的文件 . |
| `requestMediaLibraryPermissionsAsync(writeOnly?)` | 总是在桌面上授予; 对于 API 对称性 . |
| `getMediaLibraryPermissionsAsync(writeOnly?)` | 如上说. |
| `isAvailable()` | `true` 当在Windows上运行并注册了本地模块时. |

`options.base64` 这是今天唯一可以选择的. `quality` 财务报告和审定财务报表 `selectionLimit` 被接受和忽略 `launchImageLibraryAsync` (单选).

## 路线图

-   [x] 独立 `.vcxproj` + 键 `ReactPackageProvider` + 键 `react-native.config.js` 因此这个安装和自动链接为普通软件包
-   [ ] 校验工程实际编译,并自动连接到真实的应用程序
-   [ ] `ReactCoreInjection::GetTopLevelWindowId` 来制作 `WinMain` 钩子可选
-   [ ] 示例应用程序 + CI 构建
-   [ ] 相机捕获( 目前是一个单独的模块)
-   [ ] 文件夹选择/ 保存选择器
-   [ ] 发布到 npm 并注册到 [反应-原生-社区/指导](https://github.com/react-native-community/directory)

## 捐款

问题和PR是值得欢迎的,特别是构建网络和RNW版本兼容报告。 这被维持为生产应用的副产品,所以诚实的维护承诺是:它将继续研究应用船只的RNW版本.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40facilitronworks/react-native-windows-image-picker/LICENSE)。 。 。 .

## 常见问题

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

一个本地图像和文档取取取器 TurboModule for React Endern Windows \(新架构\),由Windows支持\. 存储。 拾取者\. 文件打开选择器 \.

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

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

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

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

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

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

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

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

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

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

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

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