@itshixun/qckeditor-plugin-fullscreen 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# @itshixun/qckeditor-plugin-fullscreen
+
+CKEditor 5 插件：全屏编辑模式。点击工具栏按钮切换编辑器全屏/退出全屏。
+
+## 安装
+
+```bash
+npm install @itshixun/qckeditor-plugin-fullscreen
+# 或
+pnpm add @itshixun/qckeditor-plugin-fullscreen
+```
+
+依赖 `ckeditor5`（peerDependencies，需自行安装）。
+
+## 基本使用
+
+### 1. 引入样式
+
+```ts
+import '@itshixun/qckeditor-plugin-fullscreen/dist/index.css';
+```
+
+### 2. 注册插件
+
+```ts
+import { ClassicEditor } from 'ckeditor5';
+import { FullScreen } from '@itshixun/qckeditor-plugin-fullscreen';
+
+const editor = await ClassicEditor.create(element, {
+  plugins: [
+    // ... 其他插件
+    FullScreen,
+  ],
+  toolbar: [
+    // ... 其他按钮
+    'fullScreen',  // 工具栏按钮名称：全屏
+  ],
+  fullScreen: {
+    // 可选：自定义 z-index，默认 1000
+    zIndex: 2000,
+  },
+});
+```
+
+### 3. Vue 中使用
+
+```vue
+<script setup lang="ts">
+import { ClassicEditor } from 'ckeditor5';
+import { FullScreen } from '@itshixun/qckeditor-plugin-fullscreen';
+
+const config = {
+  editor: ClassicEditor,
+  plugins: [/* ... */, FullScreen],
+  toolbar: ['bold', 'italic', 'fullScreen'],
+  fullScreen: {
+    zIndex: 2000,
+  },
+};
+</script>
+
+<template>
+  <ckeditor :editor="config.editor" :config="config" />
+</template>
+```
+
+## 配置项
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `zIndex` | `number` | 否 | 全屏模式下的 z-index，默认 `1000` |
+
+## 命令说明
+
+### `fullScreen` — 切换全屏模式
+
+```ts
+// 手动切换全屏状态
+editor.execute('fullScreen');
+
+// 获取当前全屏状态
+const isFullScreen = editor.commands.get('fullScreen')!.value;
+```
+
+## 插件行为
+
+1. 点击工具栏按钮进入全屏模式
+2. 全屏时编辑器占据整个视口，工具栏置顶
+3. 再次点击按钮退出全屏，恢复原始布局
+4. 全屏时自动隐藏页面滚动条
+
+## 类型支持
+
+导入插件后，`EditorConfig` 类型自动扩展：
+
+```ts
+const config: EditorConfig = {
+  // 无类型错误，fullScreen 已声明
+  fullScreen: {
+    zIndex: 2000,
+  },
+};
+```
+
+## 导出 API
+
+```ts
+import {
+  FullScreen,           // 主插件（Editing + UI）
+  FullScreenEditing,    // 编辑插件（注册 fullScreen 命令）
+  FullScreenUI,         // UI 插件（工具栏按钮）
+  FullScreenCommand,    // 全屏命令
+  type FullScreenConfig,
+} from '@itshixun/qckeditor-plugin-fullscreen';
+```

package/dist/fullscreen.d.ts

@@ -0,0 +1,12 @@
+import { Plugin } from 'ckeditor5';
+import { FullScreenEditing } from './fullscreenediting.js';
+import { FullScreenUI } from './fullscreenui.js';
+/**
+ * FullScreen 主插件
+ * 聚合 Editing 和 UI 功能
+ */
+export declare class FullScreen extends Plugin {
+    static get pluginName(): "FullScreen";
+    static get requires(): readonly [typeof FullScreenEditing, typeof FullScreenUI];
+}
+//# sourceMappingURL=fullscreen.d.ts.map

package/dist/fullscreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullscreen.d.ts","sourceRoot":"","sources":["../src/fullscreen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;GAGG;AACH,qBAAa,UAAW,SAAQ,MAAM;IACpC,WAAkB,UAAU,IACnB,YAAY,CACpB;IAED,WAAkB,QAAQ,6DAEzB;CACF"}

package/dist/fullscreencommand.d.ts

@@ -0,0 +1,45 @@
+import { Command } from 'ckeditor5';
+/**
+ * 全屏切换命令
+ *
+ * 修复说明：
+ * 当编辑器进入全屏模式（position: fixed）后，CKEditor 5 的 Rect.getVisible()
+ * 在计算 tooltip 等 balloon panel 的位置时，会继续检查编辑器原父链上的 overflow 裁剪。
+ * 如果父链中有 overflow: hidden 的容器（如 Vue2 演示项目中的 .editor-wrapper），
+ * 且该容器不在视口内，getVisible() 会返回 null，导致 tooltip 被定位到视口外（-99999px）。
+ *
+ * 根因：Rect.getVisible() 对 position: fixed 的处理与 CSS 规范不一致——
+ * fixed 定位元素实际不会被普通 overflow 容器裁剪，但 Rect.getVisible() 没有正确跳过。
+ *
+ * 修复方案：仿照 CKEditor 5 官方 fullscreen 插件的做法，进入全屏时将编辑器元素
+ * 移动到 body 下，彻底脱离原 DOM 上下文，避免被祖先 overflow 裁剪影响。
+ * 退出全屏时恢复原位置。
+ *
+ * 参考：https://github.com/ckeditor/ckeditor5/issues/14798（类似问题）
+ */
+export declare class FullScreenCommand extends Command {
+    /**
+     * 当前全屏状态
+     */
+    value: boolean;
+    /**
+     * 进入全屏时创建的占位元素，用于退出时恢复原位置
+     */
+    private _placeholder;
+    /**
+     * 进入全屏时保存的原父元素，用于退出时恢复
+     */
+    private _originalParent;
+    refresh(): void;
+    execute(): void;
+    /**
+     * 将编辑器元素恢复到原来的 DOM 位置
+     */
+    private _restoreEditorPosition;
+    /**
+     * 清理全屏状态
+     * 在编辑器销毁时调用，防止 body overflow 等全局样式泄漏
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=fullscreencommand.d.ts.map

package/dist/fullscreencommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullscreencommand.d.ts","sourceRoot":"","sources":["../src/fullscreencommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,SAAQ,OAAO;IAC5C;;OAEG;IACa,KAAK,UAAS;IAE9B;;OAEG;IACH,OAAO,CAAC,YAAY,CAA4B;IAEhD;;OAEG;IACH,OAAO,CAAC,eAAe,CAAqB;IAE5B,OAAO,IAAI,IAAI;IAIf,OAAO,IAAI,IAAI;IAsD/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAQ9B;;;OAGG;IACI,OAAO,IAAI,IAAI;CAsBvB"}

package/dist/fullscreenediting.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from 'ckeditor5';
+/**
+ * FullScreen 编辑插件
+ * 负责注册 fullscreen 命令
+ */
+export declare class FullScreenEditing extends Plugin {
+    static get pluginName(): "FullScreenEditing";
+    init(): void;
+}
+//# sourceMappingURL=fullscreenediting.d.ts.map

package/dist/fullscreenediting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullscreenediting.d.ts","sourceRoot":"","sources":["../src/fullscreenediting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGnC;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,WAAkB,UAAU,IACnB,mBAAmB,CAC3B;IAEM,IAAI,IAAI,IAAI;CAUpB"}

package/dist/fullscreenui.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from 'ckeditor5';
+/**
+ * FullScreen UI 插件
+ * 负责工具栏按钮（全屏/取消全屏切换）
+ */
+export declare class FullScreenUI extends Plugin {
+    static get pluginName(): "FullScreenUI";
+    init(): void;
+}
+//# sourceMappingURL=fullscreenui.d.ts.map

package/dist/fullscreenui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullscreenui.d.ts","sourceRoot":"","sources":["../src/fullscreenui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAc,MAAM,WAAW,CAAC;AAO/C;;;GAGG;AACH,qBAAa,YAAa,SAAQ,MAAM;IACtC,WAAkB,UAAU,IACnB,cAAc,CACtB;IAEM,IAAI,IAAI,IAAI;CAiCpB"}

package/dist/index.css

@@ -0,0 +1 @@
+.ck-fullscreen{position:fixed!important;top:0!important;left:0!important;right:0!important;bottom:0!important;z-index:var(--ck-fullscreen-z-index, 1000)!important}.ck-fullscreen .ck-sticky-panel__content{top:0!important;width:100%!important}.ck-fullscreen .ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline,.ck-fullscreen .ck.ck-editor__main{height:100%}body:has(.ck-fullscreen) .ck-body-wrapper{z-index:calc(var(--ck-fullscreen-z-index, 1000) + 1)!important}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { FullScreenConfig } from './types.js';
+declare module 'ckeditor5' {
+    interface EditorConfig {
+        /** FullScreen 插件配置 */
+        fullScreen?: FullScreenConfig;
+    }
+}
+export { FullScreen } from './fullscreen.js';
+export { FullScreenEditing } from './fullscreenediting.js';
+export { FullScreenUI } from './fullscreenui.js';
+export { FullScreenCommand } from './fullscreencommand.js';
+export type { FullScreenConfig } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,YAAY;QACpB,sBAAsB;QACtB,UAAU,CAAC,EAAE,gBAAgB,CAAC;KAC/B;CACF;AAGD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,98 @@
+var u = Object.defineProperty;
+var h = (n, t, e) => t in n ? u(n, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : n[t] = e;
+var c = (n, t, e) => h(n, typeof t != "symbol" ? t + "" : t, e);
+import { Command as p, Plugin as d, ButtonView as m } from "ckeditor5";
+class v extends p {
+  constructor() {
+    super(...arguments);
+    /**
+     * 当前全屏状态
+     */
+    c(this, "value", !1);
+    /**
+     * 进入全屏时创建的占位元素，用于退出时恢复原位置
+     */
+    c(this, "_placeholder", null);
+    /**
+     * 进入全屏时保存的原父元素，用于退出时恢复
+     */
+    c(this, "_originalParent", null);
+  }
+  refresh() {
+    this.isEnabled = !0;
+  }
+  execute() {
+    const e = !this.value, r = this.editor, o = r.config.get("fullScreen"), i = (o == null ? void 0 : o.zIndex) ?? 1e3, l = r.ui.element;
+    if (!l)
+      return;
+    const s = document.querySelector(".ck-body-wrapper");
+    e ? (this._originalParent = l.parentNode, this._placeholder = document.createElement("div"), this._placeholder.style.display = "none", this._originalParent.replaceChild(this._placeholder, l), document.body.appendChild(l), l.classList.add("ck-fullscreen"), l.style.setProperty("--ck-fullscreen-z-index", String(i)), document.body.style.overflow = "hidden", s && s.style.setProperty("z-index", String(i + 1), "important"), window.dispatchEvent(new Event("resize"))) : (this._restoreEditorPosition(l), l.classList.remove("ck-fullscreen"), l.style.removeProperty("--ck-fullscreen-z-index"), document.body.style.overflow = "", s && s.style.removeProperty("z-index")), this.value = e;
+  }
+  /**
+   * 将编辑器元素恢复到原来的 DOM 位置
+   */
+  _restoreEditorPosition(e) {
+    this._placeholder && this._originalParent && (this._originalParent.replaceChild(e, this._placeholder), this._placeholder = null, this._originalParent = null);
+  }
+  /**
+   * 清理全屏状态
+   * 在编辑器销毁时调用，防止 body overflow 等全局样式泄漏
+   */
+  cleanup() {
+    if (!this.value)
+      return;
+    const e = this.editor.ui.element;
+    e && (this._restoreEditorPosition(e), e.classList.remove("ck-fullscreen"), e.style.removeProperty("--ck-fullscreen-z-index"));
+    const r = document.querySelector(".ck-body-wrapper");
+    r && r.style.removeProperty("z-index"), document.body.style.overflow = "", this.value = !1;
+  }
+}
+class g extends d {
+  static get pluginName() {
+    return "FullScreenEditing";
+  }
+  init() {
+    const t = new v(this.editor);
+    this.editor.commands.add("fullScreen", t), this.listenTo(this.editor, "destroy", () => {
+      t.cleanup();
+    });
+  }
+}
+const a = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32"><path fill="currentColor" d="M20,8l8,8V8H20z M4,24h8l-8-8V24z"/><path fill="currentColor" d="M32,28V4H0v24h14v2H8v2h16v-2h-6v-2H32z M2,26V6h28v20H2z"/></svg>', f = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32"><path fill="currentColor" d="M4,16v8h8L4,16z M0,4v24h14v2H8v2h16v-0.06c2.702-0.299,5.042-1.791,6.481-3.94H32V4H0z M23,29.999 c-3.865-0.008-6.994-3.135-7-6.999c0.006-3.865,3.135-6.994,7-7c3.864,0.006,6.991,3.135,6.999,7 C29.991,26.864,26.864,29.991,23,29.999z M30,17.35c-0.57-0.707-1.244-1.326-2-1.832V8h-8l6.896,6.896 C25.717,14.328,24.398,14,23,14c-4.972,0-9,4.028-9,9c0,1.054,0.19,2.061,0.523,3H2V6h28V17.35z"/><polygon fill="currentColor" points="19,25 21,27 23,25 25,27 27,25 25,23 27,21 25,19 23,21 21,19 19,21 21,23"/></svg>';
+class y extends d {
+  static get pluginName() {
+    return "FullScreenUI";
+  }
+  init() {
+    const t = this.editor, e = t.commands.get("fullScreen"), r = t.locale.t;
+    t.ui.componentFactory.add("fullScreen", (o) => {
+      const i = new m(o);
+      return i.set({
+        label: r("全屏"),
+        icon: a,
+        tooltip: !0
+      }), i.bind("isEnabled").to(e, "isEnabled"), this.listenTo(i, "execute", () => {
+        t.execute("fullScreen");
+        const l = e.value;
+        i.set("isOn", l), i.set({
+          label: r(l ? "取消全屏" : "全屏"),
+          icon: l ? f : a
+        });
+      }), i;
+    });
+  }
+}
+class S extends d {
+  static get pluginName() {
+    return "FullScreen";
+  }
+  static get requires() {
+    return [g, y];
+  }
+}
+export {
+  S as FullScreen,
+  v as FullScreenCommand,
+  g as FullScreenEditing,
+  y as FullScreenUI
+};

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * FullScreen 插件配置
+ */
+export interface FullScreenConfig {
+    /** 全屏模式 z-index，默认 1000 */
+    zIndex?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@itshixun/qckeditor-plugin-fullscreen",
+  "version": "1.0.0",
+  "description": "CKEditor 5 plugin for fullscreen editing",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:lib": "tsc && vite build",
+    "dev:lib": "vite build --watch",
+    "release": "pnpm build:lib && npm publish --access public"
+  },
+  "peerDependencies": {
+    "ckeditor5": ">=42.0.0"
+  },
+  "devDependencies": {
+    "ckeditor5": "^47.6.1",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "plugin",
+    "fullscreen"
+  ],
+  "license": "MIT"
+}