PPTist项目自定义元素开发指南

PPTist项目自定义元素开发指南

PPTist 基于 Vue3.x + TypeScript 的在线演示文稿（幻灯片）应用，还原了大部分 Office PowerPoint 常用功能，实现在线PPT的编辑、演示。支持导出PPT文件。 项目地址: https://gitcode.com/gh_mirrors/pp/PPTist

前言

在PPTist项目中，开发者可以根据需求自定义各种元素类型，为演示文稿添加更多样化的内容。本文将以"网页元素"为例，详细介绍在PPTist项目中自定义一个新元素的完整流程。

元素定义阶段

1. 定义元素类型和数据结构

首先需要在类型系统中定义新元素的基本结构：

// 在元素类型枚举中添加新类型
export const enum ElementTypes {
  // ...其他类型
  FRAME = 'frame', // 新增网页元素类型
}

// 定义网页元素接口
export interface PPTFrameElement extends PPTBaseElement {
  type: 'frame'
  id: string;
  left: number;
  top: number;
  width: number;
  height: number;
  url: string; // 网页链接地址
}

// 更新联合类型
export type PPTElement = /* 其他元素类型 */ | PPTFrameElement;

2. 配置元素基础信息

在配置文件中添加元素的中文名称和最小尺寸限制：

// 元素类型中文映射
export const ELEMENT_TYPE_ZH = {
  // ...其他元素
  frame: '网页', // 新增网页元素中文名
}

// 元素最小尺寸限制
export const MIN_SIZE = {
  // ...其他元素
  frame: 200, // 网页元素最小尺寸
}

元素组件开发

1. 可编辑元素组件

开发可编辑状态的网页元素组件，包含交互功能：

<template>
  <div class="editable-element-frame" :style="positionStyle">
    <div class="rotate-wrapper" :style="rotateStyle">
      <div class="element-content" v-contextmenu="contextmenus" @mousedown="handleSelect">
        <iframe :src="elementInfo.url" :width="elementInfo.width" 
                :height="elementInfo.height" frameborder="0" allowfullscreen></iframe>
        
        <!-- 拖拽控制手柄 -->
        <div class="drag-handler top"></div>
        <div class="drag-handler bottom"></div>
        <div class="drag-handler left"></div>
        <div class="drag-handler right"></div>

        <!-- 非激活状态遮罩 -->
        <div class="mask" v-if="!isActive" @mousedown="handleSelect(false)"></div>
      </div>
    </div>
  </div>
</template>

2. 基础展示组件

开发用于预览/放映模式的基础组件：

<template>
  <div class="base-element-frame" :style="positionStyle">
    <div class="rotate-wrapper" :style="rotateStyle">
      <div class="element-content">
        <iframe :src="elementInfo.url" :width="elementInfo.width" 
                :height="elementInfo.height" frameborder="0" allowfullscreen></iframe>
        <div class="mask"></div>
      </div>
    </div>
  </div>
</template>

组件集成

1. 注册元素组件

在画布编辑器中注册新元素组件：

const currentElementComponent = computed(() => {
  const elementTypeMap = {
    // ...其他元素映射
    [ElementTypes.FRAME]: FrameElement, // 注册网页元素组件
  }
  return elementTypeMap[props.elementInfo.type] || null
})

2. 配置操作节点

为元素配置操作节点（缩放、旋转等控制点）：

const currentOperateComponent = computed(() => {
  const elementTypeMap = {
    // ...其他元素操作
    [ElementTypes.FRAME]: CommonElementOperate, // 使用通用操作节点
  }
  return elementTypeMap[props.elementInfo.type] || null
})

元素编辑面板开发

开发右侧属性编辑面板，用于配置元素属性：

<template>
  <div class="frame-style-panel">
    <div class="row">
      <div>网页链接：</div>
      <Input v-model:value="url" placeholder="请输入网页链接" />
      <Button @click="updateURL()">确定</Button>
    </div>
  </div>
</template>

<script setup>
const updateURL = () => {
  if (!activeElementId.value) return
  slidesStore.updateElement({ 
    id: activeElementId.value, 
    props: { url: url.value } 
  })
  addHistorySnapshot() // 记录操作历史
}
</script>

元素创建功能

1. 实现创建方法

const createFrameElement = (url: string) => {
  createElement({
    type: 'frame',
    id: nanoid(10),
    width: 800,
    height: 480,
    rotate: 0,
    left: (VIEWPORT_SIZE - 800) / 2,
    top: (VIEWPORT_SIZE * viewportRatio.value - 480) / 2,
    url,
  })
}

2. 添加到工具栏

<div class="add-element-handler">
  <span class="handler-item" @click="createFrameElement('https://v3.cn.vuejs.org/')">
    插入网页
  </span>
</div>

开发建议

1. 组件抽象：对于简单的元素，可考虑将可编辑版和基础版合并为一个组件，通过props控制不同状态

2. 操作节点：大多数元素可以使用通用操作节点，特殊元素(如线条)可自定义操作方式

3. 历史记录：所有修改元素的操作都应记录历史，支持撤销/重做

4. 扩展功能：考虑元素是否需要支持主题、导出等扩展功能

总结

在PPTist项目中自定义一个新元素需要完成以下关键步骤：

1. 定义元素类型和数据结构
2. 开发元素显示组件(可编辑版和基础版)
3. 集成到画布编辑器
4. 配置操作节点
5. 开发属性编辑面板
6. 实现创建功能

整个过程虽然步骤较多，但每个环节都有清晰的模式和规范可循。开发者应重点关注元素的数据结构和组件实现，这两部分决定了元素的核心能力和表现形态。

PPTist 基于 Vue3.x + TypeScript 的在线演示文稿（幻灯片）应用，还原了大部分 Office PowerPoint 常用功能，实现在线PPT的编辑、演示。支持导出PPT文件。 项目地址: https://gitcode.com/gh_mirrors/pp/PPTist