کتابخانه منبع باز JavaScript برای PowerPoint

شروع کار با pptx

پکیج @office-kit/pptx را از طریق npm، pnpm یا yarn نصب کنید. این کتابخانه به صورت یک بسته ESM توزیع می‌شود و از درخت‌کاهش (tree-shaking) برای داشتن ردپای کمینه پشتیبانی می‌کند. پس از نصب، توابعی مانند `loadPresentation`، `savePresentation` یا `createPresentation` را وارد کنید تا شروع به نوشتن یا ویرایش فایل‌های PPTX کنید. API در محیط‌های Node.js و مرورگر یکسان است و مخزن رسمی [pptx GitHub](https://github.com/office-kit/pptx) شامل مثال‌های کاربردی دقیق، ابزارهای اعتبارسنجی و راهنمای مهارتی برای توسعه‌ی مبتنی بر هوش مصنوعی می‌باشد.

# npm
npm install @office-kit/pptx

# pnpm
pnpm add @office-kit/pptx

# yarn
yarn add @office-kit/pptx

ویرایش قالب‌های پاورپوینت

ویرایش قالب یکی از نقاط قوت اصلی @office-kit/pptx است. می‌توانید یک فایل PPTX موجود را بارگذاری کنید، مکان‌گیرها (مثلاً عنوان، بدنه) را پیدا کنید و متن را به‌صورت برنامه‌نویسی شده جایگزین کنید — ایده‌آل برای تولید گزارش‌های پویا. این کتابخانه از جایگزینی مبتنی بر توکن در تمام اسلایدها پشتیبانی می‌کند و به‌روزرسانی‌های دسته‌ای را به‌سادگی انجام می‌دهد. یکپارچگی طرح حفظ می‌شود و خروجی با PowerPoint، Keynote و Google Slides سازگار باقی می‌ماند. این جریان کاری به‌ویژه برای ارائه‌های قالب‌بندی‌شده مفید است که فقط محتوا بین اجراها تغییر می‌کند.

import {
  findSlidePlaceholder,
  getSlides,
  loadPresentation,
  savePresentation,
  setShapeText,
} from '@office-kit/pptx';

const pres = await loadPresentation(existingPptxBytes);
const cover = getSlides(pres)[0]!;
const title = findSlidePlaceholder(cover, 'title');
if (title) setShapeText(title, 'Q3 Review');
const body = findSlidePlaceholder(cover, 'body');
if (body) setShapeText(body, 'Numbers up and to the right.');
const out: Uint8Array = await savePresentation(pres);

ساخت دک‌ها از ابتدا

با `createPresentation()` می‌توانید یک دک پاورپوینت کامل را از صفر بسازید—بدون نیاز به قالب. این تابع یک دک کاملاً ساختار یافته را با یک مستر، تم، و طرح‌های پیش‌فرض (`Blank`, `Title Slide`, `Title and Content`) برمی‌گرداند. سپس می‌توانید اسلایدها را اضافه کنید، جعبه‌های متن، تصاویر، جدول‌ها و نمودارها را با استفاده از APIهای تایپ‌شده وارد کنید. این رویکرد کنترل کامل بر طراحی و محتوا را فراهم می‌کند و امکان تولید برنامه‌نویسی ارائه‌ها برای داشبوردها، گزارش‌ها یا دک‌های اسلایدی مبتنی بر هوش مصنوعی را در حالی که سازگاری با ECMA-376 حفظ می‌شود، می‌دهد.

import {
  addTitleSlide,
  createPresentation,
  savePresentation,
} from '@office-kit/pptx';

const pres = createPresentation();
addTitleSlide(pres, 'Q3 Business Review');
const out: Uint8Array = await savePresentation(pres);

نمودارها، انیمیشن‌ها و نظرات

`@office-kit/pptx` عناصر اسلاید غنی از جمله نمودارها (ستونی, خطی, دایره‌ای, مساحتی), انیمیشن‌ها (fadeIn, fadeOut, appear) و نظرات را پشتیبانی می‌کند. نمودارها داده‌های زنده اکسل را برای ویرایش در پاورپوینت جاسازی می‌کنند، در حالی که انیمیشن‌ها از افکت‌های پیش‌تنظیم‌شده با مدت زمان قابل تنظیم استفاده می‌کنند. نظرات به شما امکان می‌دهند یادداشت‌های مرورگر را با متادیتای نویسنده و موقعیت‌گذاری اختیاری اضافه کنید. این ویژگی‌ها کتابخانه را برای ایجاد ارائه‌های تعاملی و داده‌محور که استانداردهای حرفه‌ای را برآورده می‌کنند و اعتبارسنجی طرح‌واره را پاس می‌کنند، مناسب می‌سازند.

import {
  addSlideChart,
  getSlides,
  loadPresentation,
  setShapeAnimation,
  savePresentation,
  inches,
} from '@office-kit/pptx';

const pres = await loadPresentation(templateBytes);
const slide = getSlides(pres)[0]!;
addSlideChart(slide!, {
  x: inches(0.5),
  y: inches(0.5),
  w: inches(8),
  h: inches(4.5),
  spec: {
    kind: 'column',
    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
    series: [
      { name: 'Revenue', values: [120, 180, 240, 300] },
      { name: 'Cost', values: [80, 90, 130, 160] },
    ],
    title: 'FY26 plan',
  },
});
const shape = getSlideShapes(slide)[0]!;
setShapeAnimation(shape, { effect: 'fadeIn', durationMs: 800 });
await savePresentation(pres);

اعتبارسنجی و سازگاری با طرحواره

اطمینان از اینکه فایل‌های PPTX با استاندارد ECMA-376 سازگار هستند، برای سازگاری بین ابزارها حیاتی است. @office-kit/pptx شامل `validatePresentation()` است تا مشکلاتی مانند روابط گمشده، شناسه‌های اسلاید نامعتبر یا ارجاعات خراب به طرح‌بندی را شناسایی کند. همچنین در CI از `xmllint` استفاده می‌کند (در صورت موجود بودن) تا XML تولید شده را نسبت به طرح‌نامه‌های رسمی اعتبارسنجی کند. این لایه اعتبارسنجی به شناسایی خطاهای جزئی قبل از توزیع کمک می‌کند و اطمینان می‌دهد ارائه‌ها به‌طور قابل اعتماد در PowerPoint، Keynote، Google Slides و LibreOffice باز می‌شوند—بدون تکیه بر رفتار "باز کن و دعا کن".

import { validatePresentation } from '@office-kit/pptx';

const issues = validatePresentation(pres);
for (const i of issues) console.error(i.severity, i.message);
// Catches missing rels, dangling slide ids, layouts without masters, etc.