mirror of
https://github.com/pipipi-pikachu/PPTist.git
synced 2025-04-15 02:20:00 +08:00
doc: add docs
This commit is contained in:
pipipi-pikachu
parent
73f9957fbd
commit
985be943ca
3
.github/ISSUE_TEMPLATE/bug_report.md
vendored
3
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@ -19,4 +19,5 @@ assignees: ''
|
||||
**环境信息**
|
||||
如有必要，可包含以下部分：
|
||||
1. 系统环境(Mac or Windows)
|
||||
2. 浏览器环境(如：Chrome v89.0.4389.114)
|
||||
2. 浏览器环境(如：Chrome v89.0.4389.114)
|
||||
3. 如拉取后无法运行，请提供相关异常指向的依赖及其版本信息
|
||||
105
README.md
105
README.md
@ -11,6 +11,7 @@
|
||||
2. 本项目的目标受众是<b>有【Web 幻灯片】开发需求的开发者</b>，提供的链接只是一个演示地址，并不能作为工具使用，也不提供任何在线服务。
|
||||
如果你只是需要一个服务或工具，可以选择更优秀和成熟的产品，例如：[石墨文档](https://shimo.im/)、[金山文档](https://www.kdocs.cn/)、[Slidev](https://sli.dev/)、[revealjs](https://revealjs.com/) 等。
|
||||
3. 本项目是基于 DOM 的渲染方案，好处是简单。但是相比 Canvas 渲染的方案，在复杂场景下性能会存在一定的差距，所以如果你对性能有较高的要求，本项目可能不是一个好的参考方向。
|
||||
4. 这里总结了一些[常见问题](https://github.com/pipipi-pikachu/PPTist/blob/master/doc/Q&A.md)，第一次提 Issues 和 PR 时，务必提前阅读此文档。
|
||||
|
||||
|
||||
# 🚀 项目运行
|
||||
@ -133,113 +134,19 @@ npm run serve
|
||||
- 播放预览
|
||||
|
||||
|
||||
# 💡 常见问题
|
||||
**Q. 为什么xxx快捷键没有作用？**
|
||||
|
||||
A. 部分快捷键需要聚焦到指定区域才会生效，例如焦点在左边缩略图列表才能使用操作页面的快捷键，焦点在画布区域才能使用操作元素的快捷键。
|
||||
|
||||
**Q. 为什么粘贴没有作用？**
|
||||
|
||||
A. 请注意允许浏览器访问系统剪贴板。
|
||||
|
||||
**Q. 为什么浏览器刷新或重新打开后，之前做的PPT没有了？**
|
||||
|
||||
A. 该演示项目是纯前端部署的，不会保存数据。
|
||||
|
||||
**Q. 如何调整幻灯片页面的顺序？**
|
||||
|
||||
A. 按住左侧缩略图可进行拖拽调整顺序。
|
||||
|
||||
**Q. 为什么插入图片后会出现操作卡顿的情况？**
|
||||
|
||||
A. 由于本演示项目不依赖后端，插入本地图片实际引用的是Base64，导致数据体积非常大，在真正的生产环境中应该上传图片后引用图片地址，就不会出现这样的情况了。
|
||||
|
||||
**Q. 为什么应用预置主题后没有效果？**
|
||||
|
||||
A. 设置预置主题的作用是使新添加的元素和页面应用主题样式，不会对已有的元素和页面生效，您可以使用“应用主题到全部”功能，将当前主题应用到全部页面中。
|
||||
|
||||
**Q. 设置在线字体不生效？**
|
||||
|
||||
A. 设置在线字体时会下载对应的字体文件，该文件较大，需要等待下载完成后才会应用新的字体。
|
||||
|
||||
**Q. 关于导入导出PPTX文件**
|
||||
|
||||
A. 作为一个在线幻灯片应用，导出、导入 PPTX 文件是非常重要的功能，但是经过调研发现，该功能实现起来的复杂度远超过了预期。由于个人能力和时间有限，这部分功能只能借助第三方的轮子来完成。
|
||||
|
||||
目前导出功能主要基于 [PptxGenJS](https://github.com/gitbrent/PptxGenJS/) 完成，能够实现大多数基本元素的导出，但还有非常多的缺陷需要一点点完善。同时需要知晓的是：1、该功能依赖 PptxGenJS，对于该库本身无法实现的部分（如动画），本项目也无能为力；2、导出功能的目标只是【导出样式尽可能一致的元素】，而不是一比一将网页还原到PPT，一些样式差异是必然存在的。
|
||||
|
||||
导入功能目前暂时没有合适的解决方案，还在调研和观望中。如果有感兴趣或做过相关内容的朋友，欢迎来 issues 中讨论。
|
||||
|
||||
> PS. 我做了一个 [pptx转json](https://github.com/pipipi-pikachu/pptx2json) 的实验，可做参考。
|
||||
|
||||
同时补充一点，本项目不是 office PPT 的专属在线编辑器，本质上与 office PPT 没有任何关系。【导入/导出 ppt 文件】只是项目的一个功能而非目的。
|
||||
|
||||
**Q. 视频元素支持哪些格式？**
|
||||
|
||||
A. 本项目只提供最基础的视频能力，正常状态下可以播放video标签本身支持的格式。
|
||||
|
||||
此外，可以额外引入 [hls.js](https://github.com/video-dev/hls.js) 或 [flv.js](https://github.com/Bilibili/flv.js) 来支持对应的格式（.m3u8 .flv），你只需要在项目中引入对应的文件（如cdn）即可，无需其他配置。
|
||||
|
||||
**Q. 关于导入JSON文件**
|
||||
|
||||
A. 首先，出于安全等原因，个人并不建议将这种功能在前端直接暴露给用户，或者说用户根本就不应该接触到JSON这种格式（甚至导出JSON功能的初衷也只是为了方便开发）。如果真的有相关的需求，请自行在服务端实现，核心在于做好进行数据的校验，前端实现也是一样。
|
||||
|
||||
**Q. 打印 / 导出 PDF 样式与实际有出入**
|
||||
|
||||
A. 请注意在浏览器弹出的打印窗口调整相关的设置。建议：设置边距为【默认】、取消勾选【页眉和页脚】、勾选【背景图形】
|
||||
|
||||
**Q. 为什么移动端不支持 xxx 功能？**
|
||||
|
||||
A. 首先需要明确的一点，就是移动端无论怎么做，体验上都是必然大不如 PC 端的。因此个人将移动端定位为：简单进行一些临时处理的应急使用。真正的设计/制作幻灯片应在电脑上使用完整的功能。如实在有移动端的特殊需求，可尝试在移动端使用电脑模式打开（当然，体验会更槽糕），或者开发者自己进行二次开发。
|
||||
|
||||
|
||||
# 📅 后续规划
|
||||
## 重要功能规划
|
||||
- 组合元素重构：能够支持组合元素进行旋转、缩放、整体执行动画等；
|
||||
- 添加强化版基础形状：支持调整圆角矩形弧度、调整三角形顶点位置等操作；
|
||||
- 移动端简单编辑支持；
|
||||
- 导入本地PPTX文件；
|
||||
|
||||
## 项目规划
|
||||
- 将 Vue CLI 更换到 Vite 生态；
|
||||
- 开发文档；
|
||||
|
||||
|
||||
# 📁 项目目录结构
|
||||
```
|
||||
├── 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 // 播放器模块
|
||||
└── Mobile // 移动端模块
|
||||
```
|
||||
|
||||
|
||||
# 💿 数据
|
||||
幻灯片的数据主要由 `slides` 和 `theme` 两部分组成。
|
||||
> 换句话说，在实际的生产环境中，一般只需要存储这两项数据即可。
|
||||
|
||||
- `slides` 表示幻灯片页面数据，包括每一页的ID、元素内容、备注、背景、动画、切页方式等信息
|
||||
- `theme` 表示幻灯片主题数据，包括背景色、主题色、字体颜色、字体等信息
|
||||
|
||||
具体类型的定义可见：[https://github.com/pipipi-pikachu/PPTist/blob/master/src/types/slides.ts](https://github.com/pipipi-pikachu/PPTist/blob/master/src/types/slides.ts)
|
||||
# 🎯 开发
|
||||
目前没有完整的开发文档，但下面这些文档可能会对你有一些帮助：
|
||||
- [项目目录与数据结构](https://github.com/pipipi-pikachu/PPTist/blob/master/doc/DirectoryAndData.md)
|
||||
- [画布与元素的基本原理](https://github.com/pipipi-pikachu/PPTist/blob/master/doc/Canvas.md)
|
||||
- [如何自定义一个元素](https://github.com/pipipi-pikachu/PPTist/blob/master/doc/CustomElement.md)
|
||||
|
||||
|
||||
# 💻 贡献代码
|
||||
|
||||
66
doc/Canvas.md
Normal file
66
doc/Canvas.md
Normal file
@ -0,0 +1,66 @@
|
||||
## 画布与元素
|
||||
|
||||
#### 编辑器的基本结构
|
||||
```
|
||||
└──编辑器
|
||||
├── 顶部菜单里
|
||||
├── 左侧导航栏
|
||||
├── 右侧导航栏
|
||||
├── 中上部插入/工具栏
|
||||
├── 底部输入栏
|
||||
└── 画布
|
||||
├── 可视区域
|
||||
│ ├── 可编辑元素
|
||||
│ └── 鼠标选框
|
||||
│
|
||||
└── 画布工具
|
||||
├── 参考线
|
||||
├── 标尺
|
||||
├── 元素操作节点层（如拖拽缩放点）
|
||||
├── 吸附对齐线
|
||||
└── 可视区域背景
|
||||
```
|
||||
|
||||
#### 画布的基本原理
|
||||
我们把关注点放在相对复杂的【画布】部分。画布中的每一个元素都由一组数据来描述，例如：
|
||||
```typescript
|
||||
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 倍即可。
|
||||
同理【缩略图】 和 【放映页面】 其实上就是一个实际大小更小或更大的可视区域。
|
||||
|
||||
#### 画布内的元素
|
||||
除了上述中的位置和尺寸信息，还可以携带更多的数据，以一个文本元素为例：
|
||||
```typescript
|
||||
interface PPTTextElement {
|
||||
type: 'text';
|
||||
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;
|
||||
}
|
||||
```
|
||||
你可以定义一个 `rotate` 来表示文本框旋转的角度、定义一个 `opacity` 来表示文本框的透明度 等。在实现时只需要按照你所定义的数据来渲染元素组件即可，而编辑元素的本质就是在修改这些数据。
|
||||
以上就是一个画布最基本的组成了。
|
||||
412
doc/CustomElement.md
Normal file
412
doc/CustomElement.md
Normal file
@ -0,0 +1,412 @@
|
||||
## 如何自定义一个元素
|
||||
|
||||
我们以【网页元素】为例，来梳理下自定义一个元素的过程。
|
||||
> 完整代码在 https://github.com/pipipi-pikachu/PPTist/tree/document-demo
|
||||
|
||||
### 编写新元素的结构与配置
|
||||
首先需要定义这个元素的结构，并添加该元素类型
|
||||
```typescript
|
||||
// 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
|
||||
```
|
||||
|
||||
在配置文件中添加新元素的中文名，以及最小尺寸：
|
||||
```typescript
|
||||
// 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
|
||||
}
|
||||
```
|
||||
|
||||
### 编写新元素组件
|
||||
然后开始编写该元素的组件：
|
||||
```html
|
||||
<!-- views/components/element/FrameElement/index.vue -->
|
||||
|
||||
<template>
|
||||
<div class="editable-element-frame"
|
||||
:style="{
|
||||
top: elementInfo.top + 'px',
|
||||
left: elementInfo.left + 'px',
|
||||
width: elementInfo.width + 'px',
|
||||
height: elementInfo.height + 'px',
|
||||
}"
|
||||
>
|
||||
<div
|
||||
class="rotate-wrapper"
|
||||
:style="{ transform: `rotate(${elementInfo.rotate}deg)` }"
|
||||
>
|
||||
<div
|
||||
class="element-content"
|
||||
v-contextmenu="contextmenus"
|
||||
@mousedown="$event => handleSelectElement($event)"
|
||||
@touchstart="$event => handleSelectElement($event)"
|
||||
>
|
||||
<iframe
|
||||
:src="elementInfo.url"
|
||||
:width="elementInfo.width"
|
||||
:height="elementInfo.height"
|
||||
:frameborder="0"
|
||||
:allowfullscreen="true"
|
||||
></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="handleElementId !== elementInfo.id"
|
||||
@mousedown="$event => handleSelectElement($event, false)"
|
||||
@touchstart="$event => handleSelectElement($event, false)"
|
||||
></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
import { PropType } from 'vue'
|
||||
import { storeToRefs } from 'pinia'
|
||||
import { useMainStore } from '@/store'
|
||||
import { PPTFrameElement } from '@/types/slides'
|
||||
import { ContextmenuItem } from '@/components/Contextmenu/types'
|
||||
|
||||
const props = defineProps({
|
||||
elementInfo: {
|
||||
type: Object as PropType<PPTFrameElement>,
|
||||
required: true,
|
||||
},
|
||||
selectElement: {
|
||||
type: Function as PropType<(e: MouseEvent | TouchEvent, element: PPTFrameElement, canMove?: boolean) => void>,
|
||||
required: true,
|
||||
},
|
||||
contextmenus: {
|
||||
type: Function as PropType<() => ContextmenuItem[] | null>,
|
||||
},
|
||||
})
|
||||
|
||||
const { handleElementId } = storeToRefs(useMainStore())
|
||||
|
||||
const handleSelectElement = (e: MouseEvent | TouchEvent, canMove = true) => {
|
||||
e.stopPropagation()
|
||||
props.selectElement(e, props.elementInfo, canMove)
|
||||
}
|
||||
</script>
|
||||
|
||||
<style lang="scss" scoped>
|
||||
.editable-element-frame {
|
||||
position: absolute;
|
||||
}
|
||||
.element-content {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
cursor: move;
|
||||
}
|
||||
.drag-handler {
|
||||
position: absolute;
|
||||
|
||||
&.top {
|
||||
height: 20px;
|
||||
left: 0;
|
||||
right: 0;
|
||||
top: 0;
|
||||
}
|
||||
&.bottom {
|
||||
height: 20px;
|
||||
left: 0;
|
||||
right: 0;
|
||||
bottom: 0;
|
||||
}
|
||||
&.left {
|
||||
width: 20px;
|
||||
top: 0;
|
||||
bottom: 0;
|
||||
left: 0;
|
||||
}
|
||||
&.right {
|
||||
width: 20px;
|
||||
top: 0;
|
||||
bottom: 0;
|
||||
right: 0;
|
||||
}
|
||||
}
|
||||
.mask {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
bottom: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
此外我们需要另一个不带编辑功能的基础版组件，用于缩略图/放映模式下显示：
|
||||
```html
|
||||
<!-- views/components/element/FrameElement/BaseFrameElement.vue -->
|
||||
|
||||
<template>
|
||||
<div class="base-element-frame"
|
||||
:style="{
|
||||
top: elementInfo.top + 'px',
|
||||
left: elementInfo.left + 'px',
|
||||
width: elementInfo.width + 'px',
|
||||
height: elementInfo.height + 'px',
|
||||
}"
|
||||
>
|
||||
<div
|
||||
class="rotate-wrapper"
|
||||
:style="{ transform: `rotate(${elementInfo.rotate}deg)` }"
|
||||
>
|
||||
<div class="element-content">
|
||||
<iframe
|
||||
:src="elementInfo.url"
|
||||
:width="elementInfo.width"
|
||||
:height="elementInfo.height"
|
||||
:frameborder="0"
|
||||
:allowfullscreen="true"
|
||||
></iframe>
|
||||
|
||||
<div class="mask"></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
import { PropType } from 'vue'
|
||||
import { PPTFrameElement } from '@/types/slides'
|
||||
|
||||
const props = defineProps({
|
||||
elementInfo: {
|
||||
type: Object as PropType<PPTFrameElement>,
|
||||
required: true,
|
||||
},
|
||||
})
|
||||
</script>
|
||||
|
||||
<style lang="scss" scoped>
|
||||
.base-element-frame {
|
||||
position: absolute;
|
||||
}
|
||||
.element-content {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
}
|
||||
.mask {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
bottom: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
在这里你可能会发现，这两个组件非常相似，确实如此，对于比较简单的元素组件来说，可编辑版和不可编辑版是高度一致的，不可编辑版可能仅仅是少了一些方法而已。但是对于比较复杂的元素组件，两者的差异就会比较大了（具体可以比较文本元素和图片元素的两版），因此，你可以自行判断是否将二者合并抽象为一个组件，这里不过多展开。
|
||||
|
||||
编写完元素组件，我们需要把它用在需要的地方，具体可能包括：
|
||||
|
||||
- 缩略图元素组件 `views/components/ThumbnailSlide/ThumbnailElement.vue`
|
||||
- 放映元素组件 `views/Screen/ScreenElement.vue`
|
||||
- 可编辑元素组件 `views/Editor/Canvas/EditableElement.vue`
|
||||
- 移动端可编辑元素组件 `views/Mobile/MobileEditor/MobileEditableElement.vue`
|
||||
|
||||
一般来说，前两者使用不可编辑版，后两者使用可编辑版。
|
||||
这里仅以画布中的可编辑元素组件为例：
|
||||
```html
|
||||
<!-- views/Editor/Canvas/EditableElement.vue -->
|
||||
|
||||
<script lang="ts" setup>
|
||||
import FrameElement from '@/views/components/element/FrameElement/index.vue'
|
||||
|
||||
const currentElementComponent = computed(() => {
|
||||
const elementTypeMap = {
|
||||
[ElementTypes.IMAGE]: ImageElement,
|
||||
[ElementTypes.TEXT]: TextElement,
|
||||
[ElementTypes.SHAPE]: ShapeElement,
|
||||
[ElementTypes.LINE]: LineElement,
|
||||
[ElementTypes.CHART]: ChartElement,
|
||||
[ElementTypes.TABLE]: TableElement,
|
||||
[ElementTypes.LATEX]: LatexElement,
|
||||
[ElementTypes.VIDEO]: VideoElement,
|
||||
[ElementTypes.AUDIO]: AudioElement,
|
||||
[ElementTypes.FRAME]: FrameElement, // add
|
||||
}
|
||||
return elementTypeMap[props.elementInfo.type] || null
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
在画布的可编辑元素中，还需要为元素添加操作节点 `Operate`（一般包括八个缩放点、四条边线、一个旋转点），对于特殊的元素（如线条的操作节点明显与其他不同）你可以自己编写该组件，但是一般情况下可以直接使用已经编写好的通用操作节点：
|
||||
```html
|
||||
<!-- src\views\Editor\Canvas\Operate\index.vue -->
|
||||
|
||||
<script lang="ts" setup>
|
||||
const currentOperateComponent = computed(() => {
|
||||
const elementTypeMap = {
|
||||
[ElementTypes.IMAGE]: ImageElementOperate,
|
||||
[ElementTypes.TEXT]: TextElementOperate,
|
||||
[ElementTypes.SHAPE]: ShapeElementOperate,
|
||||
[ElementTypes.LINE]: LineElementOperate,
|
||||
[ElementTypes.TABLE]: TableElementOperate,
|
||||
[ElementTypes.CHART]: CommonElementOperate,
|
||||
[ElementTypes.LATEX]: CommonElementOperate,
|
||||
[ElementTypes.VIDEO]: CommonElementOperate,
|
||||
[ElementTypes.AUDIO]: CommonElementOperate,
|
||||
[ElementTypes.FRAME]: CommonElementOperate, // add
|
||||
}
|
||||
return elementTypeMap[props.elementInfo.type] || null
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
### 编写右侧元素编辑面板
|
||||
接下来需要为元素添加一个样式面板。当选中元素时，右侧工具栏会自动聚焦到该面板，你需要在这里添加一些你认为需要的设置项来操作元素本身，只需要记住一点：修改元素实际是修改元素的数据，也就是最开始定义的结构中的各个字段。
|
||||
另外，修改元素后不要忘了将操作添加到历史记录。
|
||||
```html
|
||||
<!-- src\views\Editor\Toolbar\ElementStylePanel\FrameStylePanel.vue -->
|
||||
|
||||
<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 lang="ts" setup>
|
||||
import { ref } from 'vue'
|
||||
import { storeToRefs } from 'pinia'
|
||||
import { useMainStore, useSlidesStore } from '@/store'
|
||||
import useHistorySnapshot from '@/hooks/useHistorySnapshot'
|
||||
|
||||
const slidesStore = useSlidesStore()
|
||||
const { handleElementId } = storeToRefs(useMainStore())
|
||||
|
||||
const { addHistorySnapshot } = useHistorySnapshot()
|
||||
|
||||
const url = ref('')
|
||||
|
||||
const updateURL = () => {
|
||||
if (!handleElementId.value) return
|
||||
slidesStore.updateElement({ id: handleElementId.value, props: { url: url.value } })
|
||||
addHistorySnapshot()
|
||||
}
|
||||
</script>
|
||||
```
|
||||
```html
|
||||
<script lang="ts" setup>
|
||||
import FrameStylePanel from './FrameStylePanel.vue'
|
||||
|
||||
const panelMap = {
|
||||
[ElementTypes.TEXT]: TextStylePanel,
|
||||
[ElementTypes.IMAGE]: ImageStylePanel,
|
||||
[ElementTypes.SHAPE]: ShapeStylePanel,
|
||||
[ElementTypes.LINE]: LineStylePanel,
|
||||
[ElementTypes.CHART]: ChartStylePanel,
|
||||
[ElementTypes.TABLE]: TableStylePanel,
|
||||
[ElementTypes.LATEX]: LatexStylePanel,
|
||||
[ElementTypes.VIDEO]: VideoStylePanel,
|
||||
[ElementTypes.AUDIO]: AudioStylePanel,
|
||||
[ElementTypes.FRAME]: FrameStylePanel, // add
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### 创建元素
|
||||
这是自定义一个新元素的最后一步。首先编写一个创建元素的方法：
|
||||
```typescript
|
||||
// src\hooks\useCreateElement.ts
|
||||
|
||||
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,
|
||||
})
|
||||
}
|
||||
```
|
||||
然后在插入工具栏中使用：
|
||||
```html
|
||||
<!-- src\views\Editor\CanvasTool\index.vue -->
|
||||
|
||||
<template>
|
||||
<div class="canvas-tool">
|
||||
<div class="add-element-handler">
|
||||
<!-- add -->
|
||||
<span class="handler-item" @click="createFrameElement('https://v3.cn.vuejs.org/')">插入网页</span>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts" setup>
|
||||
const {
|
||||
createImageElement,
|
||||
createChartElement,
|
||||
createTableElement,
|
||||
createLatexElement,
|
||||
createVideoElement,
|
||||
createAudioElement,
|
||||
createFrameElement, // add
|
||||
} = useCreateElement()
|
||||
</script>
|
||||
```
|
||||
点击【插入网页】按钮，你就会看到一个网页元素被添加到画布中了。
|
||||
|
||||
### 总结
|
||||
至此就是自定义一个元素的基本流程了。整个过程比较繁琐，但并不复杂，重点在于元素结构的定义与元素组件的编写，这决定了新元素将具备怎样的能力与外表。而其他的部分仅依葫芦画瓢即可。
|
||||
除此之外，还有一些非必须的调整：比如你希望导出能够支持新元素，则需要在导出相关的方法中进行扩展；比如你希望主题功能能够应用在新元素上，则需要在主题相关的方法中进行扩展，以此类推。
|
||||
37
doc/DirectoryAndData.md
Normal file
37
doc/DirectoryAndData.md
Normal file
@ -0,0 +1,37 @@
|
||||
## 项目目录与数据结构
|
||||
|
||||
### 项目目录结构
|
||||
```
|
||||
├── 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 // 播放器模块
|
||||
└── Mobile // 移动端模块
|
||||
```
|
||||
|
||||
|
||||
### 数据
|
||||
幻灯片的数据主要由 `slides` 和 `theme` 两部分组成。
|
||||
> 换句话说，在实际的生产环境中，一般只需要存储这两项数据即可。
|
||||
|
||||
- `slides` 表示幻灯片页面数据，包括每一页的ID、元素内容、备注、背景、动画、切页方式等信息
|
||||
- `theme` 表示幻灯片主题数据，包括背景色、主题色、字体颜色、字体等信息
|
||||
|
||||
具体类型的定义可见：[https://github.com/pipipi-pikachu/PPTist/blob/master/src/types/slides.ts](https://github.com/pipipi-pikachu/PPTist/blob/master/src/types/slides.ts)
|
||||
59
doc/Q&A.md
Normal file
59
doc/Q&A.md
Normal file
@ -0,0 +1,59 @@
|
||||
## 常见问题
|
||||
|
||||
**Q. 为什么xxx快捷键没有作用？**
|
||||
|
||||
A. 部分快捷键需要聚焦到指定区域才会生效，例如焦点在左边缩略图列表才能使用操作页面的快捷键，焦点在画布区域才能使用操作元素的快捷键。
|
||||
|
||||
**Q. 为什么粘贴没有作用？**
|
||||
|
||||
A. 请注意允许浏览器访问系统剪贴板。
|
||||
|
||||
**Q. 为什么浏览器刷新或重新打开后，之前做的PPT没有了？**
|
||||
|
||||
A. 该演示项目是纯前端部署的，不会保存数据。
|
||||
|
||||
**Q. 如何调整幻灯片页面的顺序？**
|
||||
|
||||
A. 按住左侧缩略图可进行拖拽调整顺序。
|
||||
|
||||
**Q. 为什么插入图片后会出现操作卡顿的情况？**
|
||||
|
||||
A. 由于本演示项目不依赖后端，插入本地图片实际引用的是Base64，导致数据体积非常大，在真正的生产环境中应该上传图片后引用图片地址，就不会出现这样的情况了。
|
||||
|
||||
**Q. 为什么应用预置主题后没有效果？**
|
||||
|
||||
A. 设置预置主题的作用是使新添加的元素和页面应用主题样式，不会对已有的元素和页面生效，您可以使用“应用主题到全部”功能，将当前主题应用到全部页面中。
|
||||
|
||||
**Q. 设置在线字体不生效？**
|
||||
|
||||
A. 设置在线字体时会下载对应的字体文件，该文件较大，需要等待下载完成后才会应用新的字体。
|
||||
|
||||
**Q. 关于导入导出PPTX文件**
|
||||
|
||||
A. 作为一个在线幻灯片应用，导出、导入 PPTX 文件是非常重要的功能，但是经过调研发现，该功能实现起来的复杂度远超过了预期。由于个人能力和时间有限，这部分功能只能借助第三方的轮子来完成。
|
||||
|
||||
目前导出功能主要基于 [PptxGenJS](https://github.com/gitbrent/PptxGenJS/) 完成，能够实现大多数基本元素的导出，但还有非常多的缺陷需要一点点完善。同时需要知晓的是：1、该功能依赖 PptxGenJS，对于该库本身无法实现的部分（如动画），本项目也无能为力；2、导出功能的目标只是【导出样式尽可能一致的元素】，而不是一比一将网页还原到PPT，一些样式差异是必然存在的。
|
||||
|
||||
导入功能目前暂时没有合适的解决方案，还在调研和观望中。如果有感兴趣或做过相关内容的朋友，欢迎来 issues 中讨论。
|
||||
|
||||
> PS. 我做了一个 [pptx转json](https://github.com/pipipi-pikachu/pptx2json) 的实验，可做参考。
|
||||
|
||||
同时补充一点，本项目不是 office PPT 的专属在线编辑器，本质上与 office PPT 没有任何关系。【导入/导出 ppt 文件】只是项目的一个功能而非目的。
|
||||
|
||||
**Q. 视频元素支持哪些格式？**
|
||||
|
||||
A. 本项目只提供最基础的视频能力，正常状态下可以播放video标签本身支持的格式。
|
||||
|
||||
此外，可以额外引入 [hls.js](https://github.com/video-dev/hls.js) 或 [flv.js](https://github.com/Bilibili/flv.js) 来支持对应的格式（.m3u8 .flv），你只需要在项目中引入对应的文件（如cdn）即可，无需其他配置。
|
||||
|
||||
**Q. 关于导入JSON文件**
|
||||
|
||||
A. 首先，出于安全等原因，个人并不建议将这种功能在前端直接暴露给用户，或者说用户根本就不应该接触到JSON这种格式（甚至导出JSON功能的初衷也只是为了方便开发）。如果真的有相关的需求，请自行在服务端实现，核心在于做好进行数据的校验，前端实现也是一样。
|
||||
|
||||
**Q. 打印 / 导出 PDF 样式与实际有出入**
|
||||
|
||||
A. 请注意在浏览器弹出的打印窗口调整相关的设置。建议：设置边距为【默认】、取消勾选【页眉和页脚】、勾选【背景图形】
|
||||
|
||||
**Q. 为什么移动端不支持 xxx 功能？**
|
||||
|
||||
A. 首先需要明确的一点，就是移动端无论怎么做，体验上都是必然大不如 PC 端的。因此个人将移动端定位为：简单进行一些临时处理的应急使用。真正的设计/制作幻灯片应在电脑上使用完整的功能。如实在有移动端的特殊需求，可尝试在移动端使用电脑模式打开（当然，体验会更槽糕），或者开发者自己进行二次开发。
|
||||
Loading…
x
Reference in New Issue
Block a user