jvs-ppt-ui 0.0.8 → 0.0.10

package/README.md

@@ -29,8 +29,9 @@ app.use(JvsPptUi) // 注册全局组件: <JvsPptEditor /> 和 <PptEditor />
 app.mount('#app')
 ```
 
-> **💡 零外部 UI 依赖（完全自包含）**：
-> `jvs-ppt-ui` 已内置自包含所需的组件与完整样式，宿主项目**无需安装、引入 Element Plus**，也不受宿主项目自身 UI 库（无论使用的是 Ant Design Vue、Naive UI、Arco Design 还是原生开发）的任何限制，开箱即用，绝不产生依赖冲突。
+> **💡 零外部依赖与资产完全自包含（开箱即用）**：
+> 1. `jvs-ppt-ui` 已内置自包含所需的组件与完整样式，宿主项目**无需安装、引入 Element Plus**，也不受宿主项目自身 UI 库的任何限制，绝不产生依赖冲突。
+> 2. **图标库 100% 自包含**：组件库已将阿里巴巴 Iconfont SVG Symbol 与字体样式全量打入 JS/CSS 产物中，**宿主应用的 `index.html` 彻底不需要引入任何 `<script>` 或 `<link>` 图标文件**，直接使用即可完整回显所有图标。
 
 ---
 
@@ -87,6 +88,8 @@ const onChange = (data: any) => {
 | **`modelValue`** | `Slide[] \| DeckData \| null` | `null` | 幻灯片数据，支持 `v-model` 双向绑定 |
 | **`readonly`** | `boolean` | `false` | 是否只读模式（禁用工具栏与编辑能力，只保留浏览放映） |
 | **`showHeader`** | `boolean` | `true` | 是否展示顶部导航与工具栏 |
+| **`showMenu`** | `boolean` | `true` | **是否显示顶部左上角主菜单按钮**（导入/导出/快捷键等弹窗菜单）。设置为 `false` 时，彻底隐藏主菜单按钮，左上角仅保留文档标题与重命名图标。适合弹窗嵌入或已有自定义操作栏场景 |
+| **`toolbarMode`** | `'auto' \| 'more' \| 'full'` | `'auto'` | **工具栏布局模式**：`'auto'` 智能自适应窄屏（宽度不足时自动折叠收纳）；`'more'` 强制收纳扩展功能为【··· 更多】功能模块面板（核心保留撤销/恢复/文本/形状/线条，其余收纳至弹出卡片，极其适合弹窗与小屏幕场景）；`'full'` 强制全平铺展示 |
 | **`showSidebarLeft`** | `boolean` | `true` | 是否展示左侧幻灯片缩略图列表 |
 | **`showSidebarRight`** | `boolean` | `true` | 是否展示右侧对象/页面属性面板 |
 | **`enableAi`** | `boolean` | `undefined` | 是否启用 AI 功能（未配置或为 false 时不显示一键美化功能） |
@@ -108,6 +111,10 @@ const onChange = (data: any) => {
 interface PptEditorConfig {
   /** 演示文稿初始标题 */
   title?: string
+  /** 是否显示左上角主菜单按钮（导入/导出/快捷键等弹窗菜单），默认为 true */
+  showMenu?: boolean
+  /** 工具栏布局模式：'auto' (自适应折叠)、'more' (收纳更多功能模式，适合弹窗/小屏)、'full' (全展开)，默认为 'auto' */
+  toolbarMode?: 'auto' | 'more' | 'full'
   /** 是否启用 AI PPT 智能生成与一键美化功能。未配置或为 false 时不显示一键美化功能 */
   enableAi?: boolean
   /** AI 一键美化请求接口地址。若未配置或未开启，则不显示一键美化功能 */
@@ -736,3 +743,54 @@ editorRef.value.setCustomUploadHandler(null)
 - 相同的图片/媒体在单次导入中**仅会触发一次真实的服务器上传请求**；
 - 其余引用处会自动复用首个上传请求返回的远程 URL，避免重复浪费网络流量与服务器存储空间。
 
+---
+
+## 十、常见接入场景与最佳实践
+
+### 1. 弹窗 / 抽屉模式嵌入（小屏响应式自适应）
+在将 `PptEditor` 嵌入到 Dialog 模态弹窗或 Drawer 抽屉时（容器宽度在 800px ~ 1200px 左右），推荐以下配置：
+
+```vue
+<template>
+  <el-dialog v-model="visible" fullscreen :show-close="false">
+    <PptEditor
+      ref="editorRef"
+      v-model="deckData"
+      :show-menu="false"
+      @save="handleSave"
+    >
+      <!-- 在右侧添加弹窗关闭或自定义业务按钮 -->
+      <template #header-right-suffix>
+        <el-button size="small" type="primary" @click="handleSave">保存</el-button>
+        <el-button size="small" @click="visible = false">关闭</el-button>
+      </template>
+    </PptEditor>
+  </el-dialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { PptEditor } from 'jvs-ppt-ui'
+import 'jvs-ppt-ui/dist/lib/style.css'
+
+const visible = ref(true)
+const deckData = ref(null)
+const editorRef = ref(null)
+
+const handleSave = async () => {
+  const data = await editorRef.value?.save({ format: 'json' })
+  // 保存到服务端...
+}
+</script>
+```
+
+#### 小屏自适应机制说明：
+- **菜单控制 (`:show-menu="false"`)**：关闭左上角内置的测试/导入弹层菜单，左上角仅保留文档标题与重命名，更符合宿主系统定制界面的规范。
+- **标题防挤压折行**：标题容器内置单行截断（`white-space: nowrap; text-overflow: ellipsis`）和鼠标悬浮 `:title` 提示，不再被中间工具栏挤成纵向乱序文字。
+- **工具栏弹性间距**：工具栏按钮间距自适应缩小（`gap: clamp(...)`），宽度受限时末尾的“动画与切换”、“一键美化”等按钮依然紧凑展示；极窄尺寸下支持平滑横向滚动。
+- **右侧功能区恒定展示**：全屏放映、母版模式与缩放下拉框恒定单行展示（`flex-shrink: 0`），绝不被压扁变形。
+
+### 2. 图标库免配置说明（Zero Configuration）
+- 宿主系统（如 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 与样式，实现真正的“开箱即用”。
+