add-pdf-viewer

📋 共享说明：shared-instructions.md — 请先阅读。

**工作目录：**读取任何项目文件或运行任何命令之前，请执行 native-artifact-compatibility.md Step 0。 继承 /add-native 解析出的绝对 working_dir；将每次 shell 调用和文件工具绑定到该目录，即使此辅助工具从其他目录启动。

添加 PDF 查看器

内部辅助工具。 用户应调用 /add-native pdf-viewer、/add-native pdf-control 或 /add-native @microsoft/power-apps-native-pdf-viewer；/add-native 解析功能后会路由到此处。

生成或验证原生 PDF 查看器封装，并说明如何调用其原生 React Native API。0.2.9 及更高版本支持 HTTPS PDF URL 和本地 file:// URI。请勿使用包 README 中的 HostingSDK / PCF 路径；该路径适用于其他用例。

步骤

1. 验证应用

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f app.config.js && test -f power.config.json && test -f package.json && test -d src || { echo "BLOCKED: working_dir is not an initialized app" >&2; exit 1; }

如果失败，请告知用户先运行 /create-mobile-app，然后停止。

2. 验证包是否已存在

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node -e "const p=require('./package.json'); const m='@microsoft/power-apps-native-pdf-viewer'; if (!p.dependencies?.[m]) { console.error('MISSING: ' + m + ' is not in package.json. The template/app must already ship this native extension. This skill will not install it or edit native config.'); process.exit(1); } let v; try { v=require('./node_modules/' + m + '/package.json').version; } catch { console.error('MISSING_INSTALL: cannot verify the installed ' + m + ' version. Run the project package install first.'); process.exit(1); } const [major,minor,patch]=v.split('.').map(Number); if (!(major > 0 || minor > 2 || (minor === 2 && patch >= 9))) { console.error('UNSUPPORTED_VERSION: ' + m + ' ' + v + ' does not support file:// URIs. Version 0.2.9+ is required.'); process.exit(1); } console.log('OK: native PDF viewer ' + v + ' supports https:// and file://');"

如果检查失败，请停止。不要运行 npm install、npx expo install、pod install，也不要编辑 app.config.js。0.2.9+ 必须已包含在应用的原生构建中。

2a. 协调所需工件

在写入或复用之前，阅读并执行 native-artifact-compatibility.md 中适用于 PDF 查看器行的步骤 1–3。继承 /add-native 当前的审批/模式；不要重复有效的范围限定审批。 检查 src/native/pdfViewer.ts 中的 openHttpsPdf、PdfViewerResult、所需选项/操作，以及其针对已安装的 0.2.9+ 版本实际支持的 HTTPS/本地文件行为。仅支持 HTTPS 的实现无法满足所需的本地 file:// 预览。检查无效 URI 和缺少原生模块的处理路径，而不只是导出项；审批范围之外的不兼容工件应向所有者返回 NEEDS_CONTEXT，或在独立运行时提出询问。

3. 编写或验证 src/native/pdfViewer.ts

根据步骤 2a 的决定处理 src/native/pdfViewer.ts：如果用户有此要求且文件缺失，则创建；仅当兼容时才原样复用；否则只进行已批准范围内的更新。保留自定义代码、导出项和调用方；不要用示例覆盖。

封装必须：

• 接受 https:// URL 和 file:// URI。
• 在调用原生代码前拒绝 content://、blob:、http://、空 URL 和格式错误的 URL。
• 返回可区分的联合类型，且绝不抛出异常。
• 如果扩展已安装在 JS 中，但在原生构建中不可用，则返回 NATIVE_MODULE_MISSING。
• 在可用时提供查看器操作结果（shared、printed、dismissed）。
• 对未被验证或模块检查涵盖的原生错误返回 VIEWER_FAILED。

// src/native/pdfViewer.ts
import { NativePdfViewer } from '@microsoft/power-apps-native-pdf-viewer';

export type PdfViewerResult =
  | { ok: true; action?: 'shared' | 'printed' | 'dismissed' }
  | { ok: false; reason: 'INVALID_URL' | 'NATIVE_MODULE_MISSING' | 'VIEWER_FAILED'; message?: string };

export async function openHttpsPdf(
  url: string,
  options?: { title?: string; maxFileSizeMb?: number; cacheEnabled?: boolean },
): Promise<PdfViewerResult> {
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    return { ok: false, reason: 'INVALID_URL', message: 'PDF location must be a valid https:// URL or file:// URI.' };
  }

  const isHttpsUrl = parsed.protocol === 'https:';
  const isFileUri = parsed.protocol === 'file:' && url.startsWith('file://') && parsed.pathname !== '/';
  if (!isHttpsUrl && !isFileUri) {
    return { ok: false, reason: 'INVALID_URL', message: 'Native PDF viewer supports https:// and file:// inputs only.' };
  }

  if (!NativePdfViewer?.openPdf) {
    return { ok: false, reason: 'NATIVE_MODULE_MISSING', message: 'Native PDF viewer module is not available in this build.' };
  }

  try {
    const response = await NativePdfViewer.openPdf(url, {
      maxFileSizeMb: 50,
      cacheEnabled: true,
      ...options,
    });

    if (response.status === 'ok') {
      return { ok: true, action: response.result?.action };
    }

    return { ok: false, reason: 'VIEWER_FAILED', message: response.message ?? response.error };
  } catch (error: any) {
    return { ok: false, reason: 'VIEWER_FAILED', message: error?.message ?? String(error) };
  }
}

4. 使用封装

供所有者参考的集成指南；此辅助工具不要编辑屏幕。

屏幕应导入封装，而不是直接导入原生包：

import { openHttpsPdf } from '@/native/pdfViewer';

const response = await openHttpsPdf('https://example.com/report.pdf', {
  title: "Inspection report",
});

if (response.ok) {
  switch (response.action) {
    case "shared":
      // User completed native Share.
      break;
    case "printed":
      // User completed native Print.
      break;
    case "dismissed":
      // User closed the viewer.
      break;
  }
} else {
  console.warn("Failed to open PDF:", response.reason, response.message);
}

注意：

• URL 必须使用 https:// 或非空的 file:// URI。此技能不支持 content://、blob: 和 http://。
• 仅在此原生 PDF 查看用例中使用 @microsoft/power-apps-native-pdf-viewer。
• 使用 expo-document-picker 选择/导入/上传本地 PDF 或文档。
• 使用 /add-native pdf-report 生成本地 PDF。该辅助工具需要 expo-print，且仅当 expo-sharing 已存在时才会添加分享行为。
• 由 expo-print 生成的本地 PDF 可由 0.2.9+ 原生 PDF 查看器作为 file:// URI 打开。
• 分享和打印功能已内置于原生查看器；无需单独调用 JS 分享/打印方法。
• 封装返回 { ok: true } | { ok: false }；请在 UI 中处理所有非 ok 原因。

5. 类型检查

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npx --no-install tsc --noEmit

仅修复范围内的辅助工具错误，然后执行共享兼容性契约的第 4 步。重新检查请求的输入项／选项／操作、无效 URI 拒绝、原生模块缺失以及查看器故障。仅类型检查成功还不够；不要修复屏幕／生成的文件。

6. 原生重建说明

此技能不会安装原生代码。如果刚刚在技能之外添加了此软件包，则应用需要在此工作流之外进行原生重建。如果此软件包已包含在构建中，则 Metro 热重载足以应用包装器编辑。

7. 不要使用 HostingSDK / PCF

不要导入或注册：

import NativePdfViewerExtension from "@microsoft/power-apps-native-pdf-viewer";

不要接入 Companion PCF 或 NativePdfViewerExtension。在 Power Apps 原生代码应用中，请使用上述原生 React Native API。

8. 总结

在此总结之前，返回共享兼容性结果以及实际创建／更新／复用的路径。仅在成功后更新 memory-bank；如果由流程编排，则将最终更新留给负责人。

告知用户：

PDF viewer added
Package present   : @microsoft/power-apps-native-pdf-viewer
Wrapper           : src/native/pdfViewer.ts
URL support       : HTTPS and file:// (0.2.9+)
Type-check        : PASS
Native rebuild    : not performed by this skill
Usage             : openHttpsPdf(...)
HostingSDK / PCF  : not used

在 Controls 下更新 memory-bank.md：

- PDF viewer added — @microsoft/power-apps-native-pdf-viewer (<ISO date>)