aiws3-ppt 打包与集成指南

本库提供一个可嵌入主项目 aiws3-web 的迷你 PPT 编辑器组件 MiniPPTEditor，支持视口尺寸、比例(16:9 / 4:3) 切换、缩放与历史等基础交互。

1. 安装 / 本地调试

方式 A：主项目直接安装本地路径（推荐）

cd D:/projects/aiws3-web
npm install D:/projects/aiws3-ppt

方式 B：npm link（可能遇到缓存与符号链接问题）

cd D:/projects/aiws3-ppt
npm link
cd D:/projects/aiws3-web
npm link @aiws3/ppt

2. 使用示例（主项目）

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import MiniEditor from '@aiws3/ppt'

const app = createApp(App)
app.use(createPinia())
app.use(MiniEditor)
app.mount('#app')

<template>
	<div class="ppt-container">
		<MiniPPTEditor
			style="height:100%;"
			:viewportSize="1000"
			:viewportRatio="aspectRatio"
			:initialPercentage="90"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
// ratio = height / width; 16:9 => 9/16, 4:3 => 3/4
const aspectRatio = ref(9/16)
// 切换示例：aspectRatio.value = 3/4
</script>
<style>
.ppt-container { height:100vh; }
html,body,#app { height:100%; margin:0; }
</style>

3. 构建脚本

npm run build

执行顺序（脚本已内置）：

1. clean -> 删除 dist
2. 生成类型声明 -> dist/types
3. Vite 库模式打包 -> ESM / UMD
4. 产物验证 -> dist/aiws3-ppt.es.js / aiws3-ppt.umd.js / dist/types/index.d.ts

4. 比例与缩放

内部计算：

fitScale = min(容器宽 / viewportSize, 容器高 / (viewportSize * ratio))
实际 scale = fitScale * (canvasPercentage / 100)

常用：

• 16:9 -> ratio = 9/16
• 4:3 -> ratio = 3/4
• 调整缩放：修改组件内部的 percentage（未来可暴露事件/prop）

5. width/height = 0 排查

| 场景 | 原因 | 解决 | |------|------|------| | 容器高度为 0 | 父级未设置高度 | 给父容器 height:100vh 或固定 px | | 初始 scale 未触发 | ResizeObserver 尚未计算 | 确认未处于 display:none / 延迟挂载 | | 比例写反 | 误写 16/9 | ratio 应为 height/width (9/16) | | props 传 0 | 外部错误传值 | 使用默认或传正值 (size=1000, ratio=9/16) | | 视觉过小 | initialPercentage 太低 | 提升到 >= 50 |

诊断：

1. 检查 .viewport-wrapper 实际尺寸
2. 在控制台打印 props 与计算：viewportSize * viewportRatio
3. 查看父层布局是否分配高度

6. 动态比例切换

const aspectRatio = ref(9/16)
function set169() { aspectRatio.value = 9/16 }
function set43() { aspectRatio.value = 3/4 }

切换仅改变逻辑高度计算；通过 ResizeObserver + watch 触发重新布局。

7. 发布注意事项

• vue / pinia 作为 peerDependencies，不随包重复打入
• sideEffects:false 允许 tree-shaking（若后续引入全局样式副作用需调整）
• 确保入口 src/index.ts 导出组件与类型

8. 类型与导出

import { MiniPPTEditor, type MiniSlide } from '@aiws3/ppt'

9. 后续可拓展

• 鼠标点缩放（保持指针逻辑坐标）
• 多比例预设 / 自定义宽高
• 外部控制缩放（暴露 v-model:percentage）
• 历史、撤销重做事件回调对外暴露

MIT Licensed.