# ppt-imitator

**Repository Path**: zdevoin/ppt-imitator

## Basic Information

- **Project Name**: ppt-imitator
- **Description**: 基于 Vue3.x + TypeScript 的在线演示文稿（幻灯片）应用，还原了大部分 Office PowerPoint 常用功能，实现在线PPT的编辑、演示。支持导出PPT文件。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/litaosheng
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7
- **Created**: 2024-02-19
- **Last Updated**: 2024-02-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PPTImitator

> 基于 Vue3.x + TypeScript 的在线演示文稿（幻灯片）应用，还原了大部分 Office PowerPoint 常用功能，实现在线PPT的编辑、演示。支持导出PPT文件
>
> 个人的学习笔记放置在StudyNote.md中

# 项目运行

```
npm i
npm run serve
```

# 项目功能

## 基础功能

- 历史记录（撤销、重做）
- 快捷键
- 右键菜单
- 导出本地文件（PPTX、JSON、图片、PDF）
- 导入导出特有 .pptist 文件
- 打印

## 幻灯片页面编辑

- 页面添加、删除
- 页面顺序调整
- 页面复制粘贴
- 背景设置（纯色、渐变、图片）
- 设置画布尺寸
- 网格线
- 标尺
- 画布缩放、移动
- 主题设置
- 幻灯片备注
- 幻灯片模板
- 翻页动画
- 元素动画（入场、退场、强调）
- 选择面板（隐藏元素、层级排序、元素命名）

## 幻灯片元素编辑

- 元素添加、删除
- 元素复制粘贴
- 元素拖拽移动
- 元素旋转
- 元素缩放
- 元素多选（框选、点选）
- 多元素组合
- 多元素批量编辑
- 元素锁定
- 元素吸附对齐（移动和缩放）
- 元素层级调整
- 元素对齐到画布
- 元素对齐到其他元素
- 多元素均匀分布
- 元素坐标、尺寸和旋转角度设置
- 元素超链接（链接到网页、链接到其他幻灯片页面）

### 文字

- 富文本编辑（颜色、高亮、字体、字号、加粗、斜体、下划线、删除线、角标、行内代码、引用、超链接、对齐方式、序号、项目符号、缩进、清除格式）
- 行高
- 字间距
- 段间距
- 首行缩进
- 填充色
- 边框
- 阴影
- 透明度
- 竖向文本

### 图片

- 裁剪（自定义、按形状、按纵横比）
- 滤镜
- 翻转
- 边框
- 阴影
- 替换图片
- 设置为背景图

### 形状

- 替换形状
- 填充色
- 边框
- 阴影
- 透明度
- 翻转
- 编辑文字

### 线条

- 颜色
- 宽度
- 样式
- 端点样式

### 图表（柱状图、条形图、折线图、面积图、散点图、饼图、环形图）

- 图表转换
- 数据编辑
- 背景填充
- 主题色
- 坐标系与坐标文字颜色
- 其他图表设置
- 边框
- 图例

### 表格

- 行、列添加删除
- 主题设置（主题色、表头、汇总行、第一列、最后一列）
- 合并单元格
- 单元格样式（填充色、文字颜色、加粗、斜体、下划线、删除线、对齐方式）
- 边框

# 项目目录结构

```
├── assets                        // 静态资源
│   ├── fonts                     // 在线字体文件
│   └── styles                    // 样式
│       ├── antd.scss             // antd默认样式覆盖
│       ├── font.scss             // 在线字体定义
│       ├── global.scss           // 通用全局样式
│       ├── mixin.scss            // scss全局混入
│       ├── variable.scss         // scss全局变量
│       └── prosemirror.scss      // ProseMirror 富文本默认样式
├── components                    // 与业务逻辑无关的通用组件
├── configs                       // 配置文件，如：画布尺寸、字体、动画配置、快捷键配置、预置形状、预置线条等数据。
├── hooks                         // 供多个组件（模块）使用的 hooks 方法
├── mocks                         // mocks 数据
├── plugins                       // 自定义的 Vue 插件
├── types                         // 类型定义文件
├── store                         // Pinia store，参考：https://pinia.vuejs.org/
├── utils                         // 通用的工具方法
└── views                         // 业务组件目录，分为 `编辑器` 和 `播放器` 两个部分。
    ├── components                // 公用的业务组件
    ├── Editor                    // 编辑器模块
    └── Screen                    // 播放器模块
```

# 数据

幻灯片的数据主要由 `slides` 和 `theme` 两部分组成。

> 换句话说，在实际的生产环境中，一般只需要存储这两项数据即可。

- `slides` 表示幻灯片页面数据，包括每一页的ID、元素内容、备注、背景、动画、切页方式等信息
- `theme` 表示幻灯片主题数据，包括背景色、主题色、字体颜色、字体等信息

> slides 和 theme 的具体数据类型定义可以查看 scr/types/slides.ts 文件

# 画布与元素

## 编辑器的基本结构

```
└──编辑器
    ├── 顶部菜单里
    ├── 左侧导航栏
    ├── 右侧导航栏
    ├── 中上部插入/工具栏
    ├── 底部输入栏
    └── 画布
         ├── 可视区域
         │    ├── 可编辑元素
         │    └── 鼠标选框
         └── 画布工具
              ├── 参考线
              ├── 标尺
              ├── 元素操作节点层（如拖拽缩放点）
              ├── 吸附对齐线
              └── 可视区域背景
```

## 画布的基本原理

画布中的每一个元素都由一组数据来描述，例如：

```ts
interface PPTBaseElement {
  id: string;
  left: number;
  top: number;
  width: number;
  height: number;
}
```

`left` 表示元素距离画布左边线的位置，`width` 表示元素的宽度，以此类推。 重点需要知道的是：可视区域默认以 宽1000像素 、高562.5像素为基础比例。即无论画布和可视区域实际大小是多少，一个 `{ width: 1000px, height: 562.5px, left: 0, top: 0 }` 的元素一定会正好铺满整个可视区域。 具体实现的方法很简单：假设可视区域的实际宽度为 1200px ，计算出此时的缩放比为 1200 / 1000 = 1.2 ，然后将可视区域内的元素全部缩放到 1.2 倍即可。 同理【缩略图】 和 【放映页面】 其实上就是一个实际大小更小或更大的可视区域。

## 画布内的元素

除了上述中的位置和尺寸信息，还可以携带更多的数据，以一个形状元素为例：

```ts
interface PPTShapeElement {
  type: 'shape';
  id: string;
  left: number;
  top: number;
  lock?: boolean;
  groupId?: string;
  width: number;
  height: number;
  link?: string;
  content: string;
  rotate: number;
  defaultFontName: string;
  defaultColor: string;
  outline?: PPTElementOutline;
  fill?: string;
  lineHeight?: number;
  wordSpace?: number;
  opacity?: number;
  shadow?: PPTElementShadow;
}
```

你可以定义一个 `width`来表示文本框的宽度、定义一个 `opacity` 来表示文本框的透明度等。在实现时只需要按照你所定义的数据来渲染元素组件即可，而编辑元素的本质就是在修改这些数据。 以上就是一个画布最基本的组成了。

# 自定义一个元素（核心）

## 编写新元素的结构与配置

首先需要定义这个元素的结构，并添加该元素类型

```ts
// types/slides.ts
export const enum ElementTypes {
  TEXT = 'text',
  IMAGE = 'image',
  SHAPE = 'shape',
  LINE = 'line',
  CHART = 'chart',
  TABLE = 'table',
  LATEX = 'latex',
  VIDEO = 'video',
  AUDIO = 'audio',
  FRAME = 'frame', // add
}

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

// 修改 PPTElement Type
export type PPTElement = PPTTextElement | PPTImageElement | PPTShapeElement | PPTLineElement | PPTChartElement | PPTTableElement | PPTLatexElement | PPTVideoElement | PPTAudioElement | PPTFrameElement
```

在配置文件中添加新元素的中文名，以及最小尺寸：

```ts
// configs/element

export const ELEMENT_TYPE_ZH = {
  text: '文本',
  image: '图片',
  shape: '形状',
  line: '线条',
  chart: '图表',
  table: '表格',
  video: '视频',
  audio: '音频',
  frame: '网页', // add
}
export const MIN_SIZE = {
  text: 20,
  image: 20,
  shape: 15,
  chart: 200,
  table: 20,
  video: 250,
  audio: 20,
  frame: 200, // add
}
```

## 编写新元素组件

1. 编写该元素组件（以形状元素为例），具体参考`src/views/components/element/ShapeElement/index.vue`

2. 此外我们需要另一个不带编辑功能的基础版组件，用于缩略图/放映模式下显示，具体可以参考`src/views/components/element/ShapeElement/BaseShapeElement.vue`

3. 在这里你可能会发现，这两个组件非常相似，确实如此，对于比较简单的元素组件来说，可编辑版和不可编辑版是高度一致的，不可编辑版可能仅仅是少了一些方法而已。但是对于比较复杂的元素组件，两者的差异就会比较大了（具体可以比较文本元素和图片元素的两版）
4. 编写完元素组件，我们需要把它用在需要的地方，具体可能包括：
   - 缩略图元素组件 `src/views/components/ThumbnailSlide/ThumbnailElement.vue`
   - 放映元素组件 `src/views/Screen/ScreenElement.vue`
   - 可编辑元素组件 `src/views/Editor/Canvas/EditableElement.vue`

一般来说，前两者使用不可编辑版，后者使用可编辑版。 这里仅以画布中的可编辑元素组件为例：

具体查看`src/views/Editor/Canvas/EditableElement.vue`

在画布的可编辑元素中，还需要为元素添加操作节点 `Operate`（一般包括八个缩放点、四条边线、一个旋转点），对于特殊的元素（如线条的操作节点明显与其他不同）你可以自己编写该组件，但是一般情况下可以直接使用已经编写好的通用操作节点：

具体查看`src/views/Editor/Canvas/Operate/index.vue`

## 编写右侧元素编辑面板

接下来需要为元素添加一个样式面板。当选中元素时，右侧工具栏会自动聚焦到该面板，你需要在这里添加一些你认为需要的设置项来操作元素本身，只需要记住一点：修改元素实际是修改元素的数据，也就是最开始定义的结构中的各个字段。 另外，修改元素后不要忘了将操作添加到历史记录。

具体可以参考`src/views/Editor/Toolbar/ElementStylePanel/ShapeStylePanel.vue`

## 创建元素

这是自定义一个新元素的最后一步。首先编写一个创建元素的方法：

```ts
// src\hooks\useCreateElement.ts
const createShapeElement = (position: CommonElementPosition, data: ShapePoolItem) => {
  createElement({
    type: 'shape',
    id: nanoid(10),
    width: 800,
    height: 480,
    rotate: 0,
    left: (VIEWPORT_SIZE - 800) / 2,
    top: (VIEWPORT_SIZE * viewportRatio.value - 480) / 2,
    url,
  })
}
```

然后在插入工具栏中使用：

```vue
<!-- src\views\Editor\CanvasTool\index.vue -->

<template>
  <div class="canvas-tool">
    <div class="add-element-handler">
      <!-- add -->
      <span class="handler-item" @click="createShapeElement(shape)">插入形状</span>
    </div>
  </div>
</template>

<script lang="ts" setup>
const {
  createImageElement,
  createChartElement,
  createTableElement,
  createLatexElement,
  createVideoElement,
  createAudioElement,
} = useCreateElement()
</script>
```

点击【插入形状】按钮，你就会看到一个形状元素被添加到画布中了。

## 总结

至此就是自定义一个元素的基本流程了。整个过程比较繁琐，但并不复杂，重点在于元素结构的定义与元素组件的编写，这决定了新元素将具备怎样的能力与外表。而其他的部分仅依葫芦画瓢即可。 除此之外，还有一些非必须的调整：比如你希望导出能够支持新元素，则需要在导出相关的方法中进行扩展；比如你希望主题功能能够应用在新元素上，则需要在主题相关的方法中进行扩展，以此类推。