jvs-ppt-ui 0.0.10 → 0.0.12

package/README.md

@@ -86,7 +86,7 @@ const onChange = (data: any) => {
 | 属性名 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
 | **`modelValue`** | `Slide[] \| DeckData \| null` | `null` | 幻灯片数据，支持 `v-model` 双向绑定 |
-| **`readonly`** | `boolean` | `false` | 是否只读模式（禁用工具栏与编辑能力，只保留浏览放映） |
+| **`readonly`** | `boolean` | `false` | 是否只读/预览模式（禁用工具栏与编辑篡改，彻底屏蔽双击添加、元素拖拽、选中框选，同时完整保留浏览缩放、幻灯片放映、PPT 导入与 PPT 导出能力） |
 | **`showHeader`** | `boolean` | `true` | 是否展示顶部导航与工具栏 |
 | **`showMenu`** | `boolean` | `true` | **是否显示顶部左上角主菜单按钮**（导入/导出/快捷键等弹窗菜单）。设置为 `false` 时，彻底隐藏主菜单按钮，左上角仅保留文档标题与重命名图标。适合弹窗嵌入或已有自定义操作栏场景 |
 | **`toolbarMode`** | `'auto' \| 'more' \| 'full'` | `'auto'` | **工具栏布局模式**：`'auto'` 智能自适应窄屏（宽度不足时自动折叠收纳）；`'more'` 强制收纳扩展功能为【··· 更多】功能模块面板（核心保留撤销/恢复/文本/形状/线条，其余收纳至弹出卡片，极其适合弹窗与小屏幕场景）；`'full'` 强制全平铺展示 |
@@ -794,3 +794,70 @@ const handleSave = async () => {
 - 宿主系统（如 Vue CLI / Vite 项目）引入 `jvs-ppt-ui` 时，**无需在宿主系统的 `index.html` 中手动添加任何 `<script>` 或 `<link>` 图标标签**。
 - 只需在入口 `import 'jvs-ppt-ui/dist/lib/style.css'`（或 `import 'jvs-ppt-ui/style.css'`），组件库内部已自执行注入阿里巴巴 Iconfont SVG Symbol 与样式，实现真正的“开箱即用”。
 
+---
+
+## 十一、非编辑/预览模式（Readonly Mode）使用与行为规范
+
+在许多业务场景（如课件预览、报告审阅、大屏展示、审批流中查看幻灯片）中，需要将 PPT 编辑器作为**纯预览/浏览播放器**使用。
+通过在 `<PptEditor>` 上设置 `:readonly="true"` 即可一键启用非编辑/只读预览模式。
+
+### 1. 基础用法
+
+```vue
+<template>
+  <PptEditor
+    ref="editorRef"
+    v-model="deckData"
+    :readonly="true"
+    :show-menu="false"
+    :show-sidebar-right="false"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { PptEditor } from 'jvs-ppt-ui'
+import 'jvs-ppt-ui/dist/lib/style.css'
+
+const editorRef = ref(null)
+const deckData = ref(null)
+</script>
+```
+
+### 2. 非编辑/预览模式下的严格限制（防止意外篡改）
+
+| 交互类型 | 只读模式下的行为表现 |
+| :--- | :--- |
+| **画布空白处双击** | **彻底禁用**。不会创建任何新文本框或元素，画布保持原样。 |
+| **图元双击编辑** | **彻底禁用**。双击文本、形状、表格单元格均不会进入可编辑（ContentEditable）状态，双击公式不弹窗，双击图片占位符不弹上传框。 |
+| **图元拖拽移动** | **彻底禁用**。无法通过鼠标拖动改变任何文字、图形、图片、表格、组合子元素或线条控制点的位置与尺寸。 |
+| **选中状态与边框** | **彻底隐藏**。点击图元不再显示编辑选中边框、旋转手柄与拖动手柄（`cursor: move`），统一保持默认箭头光标（`cursor: default`）。 |
+| **画布拉框框选** | **彻底禁用**。在画布上拖拽鼠标不会拉出蓝色橡皮筋选区框，不会批量选中图元。 |
+| **表格编辑标识** | **彻底隐藏**。表格和公式上不再显示“双击编辑”浮层提示；禁用表格列宽与行高拖拽把手。 |
+| **编辑工具栏** | **彻底隐藏**。顶部文本、形状、线条、图片、AI美化等插入与格式工具栏自动隐藏。 |
+| **幻灯片管理** | 左侧缩略图列表**隐藏“新建幻灯片”按钮**，并**禁用幻灯片上下拖拽排序**；汉堡菜单中**屏蔽“重置幻灯片”**清空操作。 |
+
+### 3. 非编辑/预览模式下保留的完整功能
+
+即使在 `:readonly="true"` 下，以下关键浏览、演示及导入导出能力依然完全可用：
+
+1. **幻灯片全屏放映（F5 / Shift+F5）**：
+   - 顶部常驻【幻灯片放映 ▾】按钮，支持从头放映或从当前页放映；
+   - 快捷键 `F5`（从第一页放映）、`Shift + F5`（从当前页放映）依然生效；
+   - 放映模式支持键盘空格、左右方向键切页，按 `Esc` 键退出放映。
+2. **导入 PPT（PPTX / JSON）**：
+   - **界面操作**：顶部导航栏直接提供【导入 ▾】下拉菜单，支持选择本地 `.pptx` 文件或 `.json` 配置文件一键导入解析并即时渲染预览；
+   - **编程式调用**：支持通过组件 API 调用 `editorRef.value.loadFile(file)` 或 `editorRef.value.importFile(file)` 载入并呈现文件；
+   - 导入后自动适配屏幕并继续保持只读模式。
+3. **导出 PPT（PPTX / JSON / ZIP / PNG / JPEG）**：
+   - **界面操作**：顶部导航栏直接提供【导出 ▾】下拉菜单，支持快速下载为 PPTX、导出完整工程 JSON、打包全部页面为图片 ZIP、或下载当前页高清 PNG/JPEG 图片；
+   - **编程式调用**：可直接通过组件 API 调用 `editorRef.value.exportPptx()`、`editorRef.value.exportJson()`、`editorRef.value.exportImages()` 或 `editorRef.value.getSavePptxBlob()`。
+4. **画布多尺度缩放与平移浏览**：
+   - 顶部提供比例切换下拉框（50%、75%、100%、125%、150%、200% 及“适合画布”）；
+   - 按住 `Space`（空格键）或鼠标中键拖动画布，可自由平移浏览大尺寸幻灯片。
+5. **缩略图导航与翻页**：
+   - 点击左侧缩略图可自由跳转指定幻灯片；支持键盘 `PageUp`/`PageDown`、`ArrowUp`/`ArrowDown` 快速切页。
+6. **文字原生划词复制（Copy）**：
+   - 允许鼠标划选幻灯片内的文本内容并按 `Ctrl + C`（或右键复制）拷贝到剪贴板，方便审阅者摘录内容。
+
+