wps-facade

wps-facade 是用于封装 WPS 宿主能力的 TypeScript 门面库。 业务层只依赖 WpsApi，不直接访问 window.wps / Application / FileSystem 等底层对象。

安装

npm install wps-facade

设计目标

• 统一入口：所有 WPS 能力都从 new WpsApi() 获取
• 边界清晰：业务层仅使用语义化 API，不感知宿主实现细节
• 结果约定统一：查询接口不可用时返回 undefined，动作接口失败时抛异常
• 命名可读：能力按 runtime / environment / files / document / slides 分域

API 结构

WpsApi 暴露 5 组能力：

• runtime：获取 wps 根对象与 Application
• environment：读取 Env 与路径相关方法
• files：文件读写、删除、临时路径拼接
• document：活动文档路径、当前放映页信息
• slides：导出幻灯片为图片文件

类型速览

• SlideInfo：{ current: number; total: number }
• SlideImageFormat："png" | "jpg" | "bmp" | "tif"
• WpsPathMethod：
  • "GetTempPath"
  • "GetHomePath"
  • "GetRootPath"
  • "GetAppDataPath"
  • "GetProgramDataPath"
  • "GetProgramFilesPath"

基础用法

import { WpsApi } from 'wps-facade';

const wpsApi = new WpsApi();

const app = wpsApi.runtime.getApplication();
const docPath = wpsApi.document.getActiveDocumentPath();
const slideInfo = wpsApi.document.getActiveSlideInfo();

if (docPath) {
  console.log('active doc:', docPath);
}

Env 路径读取

import { WpsApi, type WpsPathMethod } from 'wps-facade';

const wpsApi = new WpsApi();

const method: WpsPathMethod = 'GetTempPath';
const tempDir = wpsApi.environment.getPath(method);

文件读写

import { WpsApi } from 'wps-facade';

const wpsApi = new WpsApi();
const filePath = wpsApi.files.createTempFilePath('demo.txt');

if (filePath) {
  await wpsApi.files.write(filePath, 'hello wps');
  const text = await wpsApi.files.readText(filePath);
  wpsApi.files.remove(filePath);
}

幻灯片（PPT）导出

import { WpsApi, type SlideImageFormat } from 'wps-facade';

const wpsApi = new WpsApi();

async function exportSlideToBuffer(
  slideIndex: number,
  format: SlideImageFormat = 'png',
): Promise<ArrayBuffer | undefined> {
  const path = wpsApi.files.createTempFilePath(`slide_${slideIndex + 1}.${format}`);
  if (!path) return undefined;

  try {
    wpsApi.slides.exportSlideToImageFile(slideIndex, path, format);
  } catch {
    return undefined;
  }
  const buffer = await wpsApi.files.readBuffer(path);
  wpsApi.files.remove(path);
  return buffer;
}

返回值约定

以下查询方法在能力不可用时返回 undefined：

• runtime.getRuntime()
• runtime.getApplication()
• environment.getEnvironment()
• environment.getPath()
• files.getFileSystem()
• files.createTempFilePath()
• files.readText()
• files.readBuffer()
• document.getActiveSlideInfo()
• document.getActiveDocumentPath()

以下动作方法在执行失败时抛出异常：

• files.write()
• files.remove()
• slides.exportSlideToImageFile()

构建与开发

npm run build
npm run dev
npm run lint
npm run test

Scripts

• npm run build
• npm run build:types
• npm run dev
• npm run lint
• npm run lint:fix
• npm run format
• npm run test
• npm run test:watch