快速开始

本页介绍四种常见的完整操作流程。每个示例都独立使用项目的公共 API。更详细的参考文档见下一步。

1. 从零创建演示文稿

使用 PptxHandler.create() 创建演示文稿，通过链式幻灯片构建器添加内容，再调用 save() 保存为字节数据。

import { PptxHandler } from 'pptx-viewer-core';
import { writeFile } from 'node:fs/promises';

const { handler, data, createSlide } = await PptxHandler.create({
	title: 'My Presentation',
	creator: 'Author Name',
	theme: {
		name: 'Custom Theme',
		colors: { accent1: '4472C4', accent2: 'ED7D31' },
		fonts: { majorFont: 'Calibri Light', minorFont: 'Calibri' },
	},
});

// Build a slide with the fluent API
const slide = createSlide()
	.addText('Hello World', { x: 100, y: 100, width: 600, height: 80, fontSize: 36 })
	.addShape('rect', { x: 100, y: 250, width: 300, height: 200 })
	.addImage('https://example.com/photo.jpg', { x: 450, y: 250, width: 300, height: 200 })
	.build();

data.slides.push(slide);

// Save to .pptx (returns a Uint8Array)
const output = await handler.save(data.slides);
await writeFile('presentation.pptx', output);

2. 解析并编辑已有演示文稿

创建 PptxHandler，调用 load() 加载 ArrayBuffer，遍历并修改数据模型，最后调用 save()。

import { PptxHandler } from 'pptx-viewer-core';
import { readFile, writeFile } from 'node:fs/promises';

const handler = new PptxHandler();
const buffer = await readFile('presentation.pptx');
const data = await handler.load(
	buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
);

console.log(`Loaded ${data.slides.length} slides`);
console.log(`Theme: ${data.theme?.name}`);

// Access slide content - narrow on the `type` discriminant
for (const slide of data.slides) {
	for (const element of slide.elements) {
		if (element.type === 'text') {
			console.log(`Text: ${element.text}`);
		}
	}
}

// Modify and save
data.slides[0].elements[0].text = 'Updated Title';
const output = await handler.save(data.slides);
await writeFile('output.pptx', output);

缩小元素类型范围

slide.elements 是由 PptxElement 可辨识联合类型组成的数组。访问特定元素类型的字段前，始终先检查 element.type。

3. 转换为 Markdown

PptxMarkdownConverter 将解析后的 PptxData 转换为 Markdown，也可以按需将媒体文件提取到指定目录。

import { PptxHandler, PptxMarkdownConverter } from 'pptx-viewer-core';
import { readFile } from 'node:fs/promises';

const handler = new PptxHandler();
const buffer = await readFile('presentation.pptx');
const data = await handler.load(
	buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
);

const converter = new PptxMarkdownConverter('./output', {
	sourceName: 'presentation.pptx',
	includeSpeakerNotes: true,
	mediaFolderName: 'media',
	includeMetadata: true,
	semanticMode: true, // Clean markdown vs positioned HTML
});

const markdown = await converter.convert(data);
console.log(markdown);

4. 使用 React 组件显示幻灯片

PowerPointViewer 从 Uint8Array 读取演示文稿，支持启用编辑模式。演示文稿发生编辑时，onContentChange 回调会接收重新序列化后的 .pptx 字节数据。

import { useState } from 'react';
import { PowerPointViewer } from 'pptx-react-viewer/viewer';

function App() {
	const [content, setContent] = useState<Uint8Array>();

	if (!content) return null;

	return (
		<PowerPointViewer
			content={content}
			canEdit
			onContentChange={(bytes) => {
				// `bytes` is the updated .pptx as a Uint8Array
				setContent(bytes);
			}}
		/>
	);
}

提示

完整的属性说明见组件属性，该参考文档与源码接口对应。组件接收 Uint8Array 类型的内容（不是 ArrayBuffer），onContentChange 返回序列化后的字节数据，而不是表示未保存修改的布尔值。

如果你使用 Vue、Angular、Svelte 或原生 JavaScript，可以查看 Vue、Angular、Svelte 或原生 JavaScript 的接入指南。

下一步

• 核心引擎概览：完整的处理器、构建器和转换器 API。
• React 组件概览：组件属性、编辑、放映和导出。
• PptxData 数据模型：解析后的演示文稿结构。
• 数据模型中的单位：EMU 单位、元素模型和主题解析。