tiptap-extension-shiki 1.0.0

package/dist/index.cjs.js

@@ -0,0 +1,412 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var CodeBlock = require('@tiptap/extension-code-block');
+var core = require('@tiptap/core');
+var state = require('@tiptap/pm/state');
+var view = require('@tiptap/pm/view');
+
+/**
+ * 为整个文档计算语法高亮装饰
+ * 该函数遍历文档中的所有自定义节点，为每个节点生成相应的装饰样式
+ *
+ * @param doc - ProseMirror文档节点
+ * @param name - 插件名称，用于识别目标节点类型
+ * @param highlighter - Shiki语法高亮器实例
+ * @param defaultTheme - 默认主题
+ * @param defaultLanguage - 默认编程语言
+ * @returns 装饰器集合，用于渲染语法高亮
+ */
+function getDecorations({ doc, name, highlighter, defaultTheme, defaultLanguage, }) {
+    console.log("doc", doc);
+    // 查找文档中所有指定类型的节点（shiki代码块）
+    const decorations = core.findChildren(doc, (node) => {
+        console.log("node node ", node);
+        return node.type.name === name;
+    }).reduce((acc, block) => {
+        // 为每个代码块生成装饰
+        const nodeDecorations = getSingleNodeDecorations(block.node, block.pos, highlighter, defaultTheme, defaultLanguage);
+        return acc.concat(nodeDecorations);
+    }, []);
+    // 创建装饰器集合
+    return view.DecorationSet.create(doc, decorations);
+}
+/**
+ * 为单个代码块节点生成语法高亮装饰
+ * 使用Shiki对代码进行分词，然后为每个token生成相应的装饰样式
+ *
+ * @param node - 代码块节点
+ * @param pos - 节点在文档中的位置
+ * @param highlighter - Shiki语法高亮器
+ * @param defaultTheme - 默认主题
+ * @param defaultLanguage - 默认语言
+ * @returns 该节点的所有装饰器数组
+ */
+function getSingleNodeDecorations(node, pos, highlighter, defaultTheme, defaultLanguage) {
+    const decorations = [];
+    // 获取代码块的语言和主题属性，如果没有则使用默认值
+    const language = node.attrs.language || defaultLanguage;
+    const theme = node.attrs.theme || defaultTheme;
+    // 计算文本内容的起始位置（跳过节点标记）
+    let startPos = pos + 1;
+    // 使用Shiki对代码进行分词，返回每个token的颜色信息
+    const lines = highlighter.codeToTokensBase(node.textContent, {
+        lang: language,
+        theme: theme,
+    });
+    // 遍历每一行的token，为有颜色的token创建装饰
+    lines.forEach((line) => {
+        line.forEach((token) => {
+            const endPos = startPos + token.content.length;
+            // 如果token有颜色信息，创建内联装饰器设置文本颜色
+            if (token.color) {
+                decorations.push(view.Decoration.inline(startPos, endPos, {
+                    style: `color: ${token.color}`,
+                }));
+            }
+            // 更新下一个token的起始位置
+            startPos = endPos;
+        });
+        // 处理换行符（每个line之间的分隔符）
+        startPos += 1;
+    });
+    return decorations;
+}
+/**
+ * 创建Shiki轻量级语法高亮插件
+ * 该插件负责在ProseMirror编辑器中为代码块提供实时的语法高亮显示
+ * 通过ProseMirror的装饰器系统实现高性能的语法高亮渲染
+ *
+ * @param name - 插件名称
+ * @param highlighter - Shiki语法高亮器实例
+ * @param defaultTheme - 默认主题
+ * @param defaultLanguage - 默认编程语言
+ * @returns ProseMirror插件实例
+ */
+function ShikiLightPlugin({ name, highlighter, defaultTheme, defaultLanguage, }) {
+    const shikiLightPlugin = new state.Plugin({
+        key: new state.PluginKey("shiki"),
+        // 插件状态管理
+        state: {
+            /**
+             * 初始化装饰器
+             * 在插件首次加载时为整个文档计算初始的语法高亮装饰
+             */
+            init: (_, { doc }) => {
+                return getDecorations({
+                    doc,
+                    name,
+                    highlighter,
+                    defaultTheme,
+                    defaultLanguage,
+                });
+            },
+            /**
+             * 应用事务变化
+             * 当文档发生变化时，智能更新受影响的代码块的语法高亮
+             * 实现了性能优化：只重新计算变化范围内的装饰
+             */
+            apply: (transaction, decorationSet, oldState, newState) => {
+                // 1. 如果文档内容没有变化，直接映射现有装饰（最高性能）
+                if (!transaction.docChanged) {
+                    return decorationSet.map(transaction.mapping, transaction.doc);
+                }
+                // 2. 重新计算受影响的装饰器
+                let newDecorationSet = decorationSet.map(transaction.mapping, transaction.doc);
+                // 3. 遍历事务中的每个步骤映射，精确更新受影响的节点
+                transaction.mapping.maps.forEach((stepMap) => {
+                    stepMap.forEach((fromA, toA, fromB, toB) => {
+                        // 限制计算范围在文档边界内，避免越界错误
+                        const docSize = newState.doc.content.size;
+                        const start = Math.max(0, Math.min(fromB, docSize));
+                        const end = Math.max(0, Math.min(toB, docSize));
+                        // 检查范围内的节点是否为代码块类型
+                        newState.doc.nodesBetween(start, end, (node, pos) => {
+                            if (node.type.name === "text")
+                                return;
+                            // 先移除这个节点旧的高亮
+                            const nodeEnd = pos + node.nodeSize;
+                            // 移除该节点范围内现有的所有装饰
+                            const oldDecos = newDecorationSet.find(pos, nodeEnd);
+                            newDecorationSet = newDecorationSet.remove(oldDecos);
+                            if (node.type.name === name) {
+                                // 重新计算该节点的语法高亮装饰
+                                const newSpecs = getSingleNodeDecorations(node, pos, highlighter, defaultTheme, defaultLanguage);
+                                newDecorationSet = newDecorationSet.add(newState.doc, newSpecs);
+                            }
+                        });
+                    });
+                });
+                return newDecorationSet;
+            },
+        },
+        // 插件属性：将装饰器提供给编辑器视图
+        props: {
+            decorations(state) {
+                return shikiLightPlugin.getState(state);
+            },
+        },
+    });
+    return shikiLightPlugin;
+}
+
+/**
+ * Tiptap Shiki 语法高亮扩展
+ *
+ * 本文件实现了一个基于 Shiki 的 Tiptap 扩展，用于在富文本编辑器中提供语法高亮功能。
+ * 该扩展扩展了 Tiptap 的 CodeBlock，添加了以下功能：
+ * - 支持多种编程语言的语法高亮
+ * - 支持多种主题切换
+ * - 自定义工具栏界面
+ * - 键盘快捷键支持
+ * - 实时语法高亮渲染
+ */
+// 导入 Tiptap 核心组件
+/**
+ * TiptapShiki 扩展类定义
+ *
+ * 该类扩展了 Tiptap 的 CodeBlock，添加了语法高亮功能和相关配置选项。
+ * 使用泛型类型定义扩展选项和节点视图属性。
+ *
+ * @template T - 扩展选项类型，包含默认主题、语言、高亮器等配置
+ * @template U - 节点视图属性类型，定义 DOM 元素的类型
+ */
+const TiptapShiki = CodeBlock.extend({
+    // 扩展名称，用于标识这个自定义扩展
+    name: "tiptapShiki",
+    /**
+     * 添加扩展配置选项
+     *
+     * 定义了 Shiki 语法高亮的默认配置，包括默认主题、编程语言等。
+     * 使用父类的配置选项并添加本扩展特有的选项。
+     *
+     * @returns 配置对象，包含默认主题、语言和高亮器设置
+     */
+    addOptions() {
+        var _a;
+        return Object.assign(Object.assign({}, (_a = this.parent) === null || _a === void 0 ? void 0 : _a.call(this)), { 
+            // 默认语法高亮主题
+            defaultTheme: "dracula", 
+            // 默认编程语言
+            defaultLanguage: "javascript", 
+            // 初始化时的高亮器实例（可选）
+            highlighter: undefined });
+    },
+    /**
+     * 添加节点属性
+     *
+     * 定义了代码块节点的自定义属性，包括编程语言和主题。
+     * 这些属性用于存储和渲染代码块的语法高亮配置。
+     *
+     * @returns 属性配置对象，包含语言和主题属性
+     */
+    addAttributes() {
+        var _a;
+        return Object.assign(Object.assign({}, (_a = this.parent) === null || _a === void 0 ? void 0 : _a.call(this)), { 
+            // 编程语言属性
+            language: {
+                // 默认语言配置
+                default: this.options.defaultLanguage || "javascript",
+                /**
+                 * 从 HTML 元素解析语言属性
+                 * @param element - HTML 元素
+                 * @returns 编程语言字符串
+                 */
+                parseHTML: (element) => {
+                    // 从 data-language 属性获取语言信息
+                    return element.getAttribute("data-language");
+                },
+                /**
+                 * 渲染 HTML 时设置语言属性
+                 * @param attributes - 节点属性对象
+                 * @returns HTML 属性对象
+                 */
+                renderHTML: (attributes) => {
+                    // 将语言信息存储在 data-language 属性中
+                    return { "data-language": attributes.language };
+                },
+            }, 
+            // 主题属性
+            theme: {
+                // 默认主题配置
+                default: this.options.defaultTheme || "dracula",
+                /**
+                 * 从 HTML 元素解析主题属性
+                 * @param element - HTML 元素
+                 * @returns 主题名称字符串
+                 */
+                parseHTML: (element) => element.getAttribute("data-theme"),
+                /**
+                 * 渲染 HTML 时设置主题属性
+                 * @param attributes - 节点属性对象
+                 * @returns HTML 属性对象
+                 */
+                renderHTML: (attributes) => ({
+                    "data-theme": attributes.theme,
+                }),
+            } });
+    },
+    /**
+     * 渲染 HTML
+     *
+     * 定义了代码块节点在静态 HTML 中的渲染逻辑。
+     * 如果配置了 getHighlighHTML 和 highlighter，将使用 Shiki 生成高亮的 HTML；
+     * 否则返回标准的 pre/code 标签结构。
+     *
+     * @param node - ProseMirror 节点对象
+     * @param HTMLAttributes - HTML 属性对象
+     * @returns HTML 数组或元素
+     */
+    renderHTML({ node, HTMLAttributes }) {
+        // 如果启用了高亮 HTML 生成并且有高亮器实例
+        if (this.options.getHighlighHTML && this.options.highlighter) {
+            // 获取代码内容、编程语言和主题
+            const language = node.attrs.language || this.options.defaultLanguage;
+            const theme = node.attrs.theme || this.options.defaultTheme;
+            const content = node.textContent;
+            // 使用 Shiki 将代码转换为带样式的 HTML
+            const highlightedCode = this.options.highlighter.codeToHtml(content, {
+                lang: language,
+                theme: theme,
+            });
+            // 解析生成的 HTML 字符串并返回第一个元素
+            const container = document.createElement("div");
+            container.innerHTML = highlightedCode;
+            if (container.firstElementChild)
+                return container.firstElementChild;
+        }
+        // 返回标准的 pre/code 标签结构
+        return ["pre", HTMLAttributes, ["code", 0]];
+    },
+    /**
+     * 添加节点视图
+     *
+     * 创建代码块的交互式 DOM 视图，包括工具栏和代码显示区域。
+     * 提供了实时的语法高亮和主题切换功能。
+     *
+     * @returns 节点视图工厂函数
+     */
+    addNodeView() {
+        // 检查是否有高亮器实例
+        if (!this.options.highlighter)
+            throw new Error("highlighter is required");
+        return (props) => {
+            // 获取视图相关参数
+            const { view, getPos, node } = props;
+            // 获取当前主题配置
+            const theme = this.options.highlighter.getTheme(node.attrs.theme || this.options.defaultTheme);
+            // 创建主容器 DOM 元素
+            const dom = document.createElement("div");
+            dom.classList.add("tiptap-shiki--container", "not-prose", "shiki", "dracula");
+            // 应用主题颜色
+            dom.style.backgroundColor = theme.bg;
+            dom.style.color = theme.fg;
+            // 创建工具栏（如果配置了自定义渲染器）
+            let toolbarDOM;
+            if (this.options.renderToolbar &&
+                typeof this.options.renderToolbar === "function") {
+                // 创建工具栏容器
+                toolbarDOM = document.createElement("div");
+                toolbarDOM.classList.add("tiptap-shiki--toolbar");
+                toolbarDOM.setAttribute("contenteditable", "false");
+                // 创建节点标记更新函数
+                const setNodeMarkup = (attr) => {
+                    if (typeof getPos !== "function")
+                        return;
+                    const pos = getPos();
+                    if (pos === undefined)
+                        return;
+                    const { tr } = view.state;
+                    const nowNode = view.state.doc.nodeAt(pos);
+                    // 更新节点属性
+                    tr.setNodeMarkup(pos, this.type, Object.assign(Object.assign({}, nowNode === null || nowNode === void 0 ? void 0 : nowNode.attrs), attr));
+                    view.dispatch(tr);
+                };
+                // 创建语言设置函数
+                const setLanguage = (language) => {
+                    setNodeMarkup({
+                        language, // 仅修改当前代码块的编程语言
+                    });
+                };
+                // 创建主题设置函数
+                const setTheme = (theme) => {
+                    setNodeMarkup({
+                        theme, // 仅修改当前代码块的主题
+                    });
+                };
+                // 调用自定义工具栏渲染器
+                this.options.renderToolbar({
+                    language: node.attrs.language,
+                    theme: node.attrs.theme,
+                    toolbarDOM,
+                    setLanguage,
+                    setTheme,
+                });
+                // 将工具栏添加到主容器
+                dom.appendChild(toolbarDOM);
+            }
+            // 创建代码显示区域
+            const preDOM = document.createElement("pre");
+            const contentDOM = document.createElement("code");
+            contentDOM.classList.add("tiptap-shiki--content");
+            // 组装 DOM 结构
+            preDOM.appendChild(contentDOM);
+            dom.appendChild(preDOM);
+            // 返回节点视图对象
+            return {
+                // 主 DOM 元素
+                dom: dom,
+                // 内容 DOM 元素
+                contentDOM,
+                /**
+                 * 更新节点视图
+                 * @param updatedNode - 更新后的节点
+                 * @returns 是否成功更新
+                 */
+                update: (updatedNode) => {
+                    // 如果不是相同类型的节点，拒绝更新
+                    return updatedNode.type === node.type;
+                },
+                /**
+                 * 忽略某些 DOM 变化
+                 * @param mutation - DOM 变化对象
+                 * @returns 是否忽略该变化
+                 */
+                ignoreMutation: (mutation) => {
+                    // 忽略工具栏区域的 DOM 变化
+                    return (toolbarDOM === null || toolbarDOM === void 0 ? void 0 : toolbarDOM.contains(mutation.target)) || false;
+                },
+            };
+        };
+    },
+    /**
+     * 添加 ProseMirror 插件
+     *
+     * 注册 Shiki 轻量级语法高亮插件，实现实时语法高亮功能。
+     * 继承父类的插件并添加自定义的高亮插件。
+     *
+     * @returns ProseMirror 插件数组
+     */
+    addProseMirrorPlugins() {
+        var _a;
+        // 检查是否有高亮器实例
+        if (!this.options.highlighter)
+            throw new Error("highlighter is required");
+        return [
+            // 继承父类的插件
+            ...(((_a = this.parent) === null || _a === void 0 ? void 0 : _a.call(this)) || []),
+            // 添加 Shiki 轻量级高亮插件
+            ShikiLightPlugin({
+                name: this.name,
+                highlighter: this.options.highlighter,
+                defaultLanguage: this.options.defaultLanguage,
+                defaultTheme: this.options.defaultTheme,
+            }),
+        ];
+    },
+});
+
+exports.TiptapShiki = TiptapShiki;
+exports.default = TiptapShiki;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.css

@@ -0,0 +1 @@
+.tiptap-shiki--container{border-radius:.4rem;font-size:.875em;pre{max-height:400px;overflow:auto;padding:20px}}.tiptap-shiki--toolbar{align-items:center;display:flex;padding:10px}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tiptap Shiki 语法高亮扩展
+ *
+ * 本文件实现了一个基于 Shiki 的 Tiptap 扩展，用于在富文本编辑器中提供语法高亮功能。
+ * 该扩展扩展了 Tiptap 的 CodeBlock，添加了以下功能：
+ * - 支持多种编程语言的语法高亮
+ * - 支持多种主题切换
+ * - 自定义工具栏界面
+ * - 键盘快捷键支持
+ * - 实时语法高亮渲染
+ */
+import "./index.css";
+import type { BundledLanguage, BundledTheme, HighlighterGeneric, SpecialLanguage, StringLiteralUnion, ThemeRegistrationAny } from "shiki";
+/**
+ * TiptapShiki 扩展类定义
+ *
+ * 该类扩展了 Tiptap 的 CodeBlock，添加了语法高亮功能和相关配置选项。
+ * 使用泛型类型定义扩展选项和节点视图属性。
+ *
+ * @template T - 扩展选项类型，包含默认主题、语言、高亮器等配置
+ * @template U - 节点视图属性类型，定义 DOM 元素的类型
+ */
+declare const TiptapShiki: import("@tiptap/core").Node<{
+    defaultTheme: ThemeRegistrationAny | StringLiteralUnion<string>;
+    defaultLanguage: StringLiteralUnion<SpecialLanguage>;
+    highlighter?: HighlighterGeneric<BundledLanguage, BundledTheme>;
+    getHighlighHTML?: boolean;
+    renderToolbar?: (props: {
+        toolbarDOM: HTMLElement;
+        language: StringLiteralUnion<SpecialLanguage>;
+        theme: ThemeRegistrationAny | StringLiteralUnion<string>;
+        setLanguage: (lang: string) => void;
+        setTheme: (theme: string) => void;
+    }) => void;
+}, {
+    container: HTMLElement;
+    shikiCode: HTMLElement;
+    contentDOM: HTMLElement;
+}>;
+export { TiptapShiki };
+export default TiptapShiki;