如何在Quill.js中实现类似Word的页眉页脚功能（React环境）

嘿，我之前在React项目里折腾过Quill.js的页眉页脚功能，给你分享几个可行的思路，应该能帮到你！

Quill本身不原生处理分页逻辑，但我们可以结合CSS的分页属性和伪元素，给编辑器容器添加全局的页眉页脚，导出PDF时会自动适配每页。

步骤： #

1. 给Quill编辑器套一个固定尺寸的容器（比如A4纸大小），留出页眉页脚的边距
2. 用CSS ::before/::after伪元素实现页眉和页脚，甚至可以用计数器自动生成页码

/* 编辑器容器样式，模拟A4纸 */
.quill-editor-wrapper {
  width: 210mm;
  min-height: 297mm;
  margin: 2rem auto;
  padding: 20mm; /* 上下边距留给页眉页脚 */
  page-break-inside: avoid;
  counter-reset: page 1; /* 初始化页码计数器 */
}

/* 页眉样式 */
.quill-editor-wrapper::before {
  content: "你的自定义页眉内容";
  position: fixed;
  top: 5mm;
  left: 20mm;
  right: 20mm;
  height: 10mm;
  text-align: center;
  border-bottom: 1px solid #ddd;
}

/* 页脚样式（带自动页码） */
.quill-editor-wrapper::after {
  content: "第 " counter(page) " 页 / 共 " counter(pages) " 页";
  position: fixed;
  bottom: 5mm;
  left: 20mm;
  right: 20mm;
  height: 10mm;
  text-align: center;
  border-top: 1px solid #ddd;
  counter-increment: page;
}

React组件示例： #

import React, { useEffect, useRef } from 'react';
import Quill from 'quill';
import 'quill/dist/quill.snow.css';

const QuillWithHeaderFooter = () => {
  const editorRef = useRef(null);
  const quillInstance = useRef(null);

  useEffect(() => {
    if (!editorRef.current || quillInstance.current) return;

    // 初始化Quill
    quillInstance.current = new Quill(editorRef.current, {
      theme: 'snow',
      modules: {
        toolbar: [
          ['bold', 'italic'],
          [{ header: [1, 2, 3, false] }],
          ['pagebreak'] // 自定义分页按钮
        ]
      }
    });

    // 注册自定义分页符Blot
    const PageBreak = class extends Quill.import('blots/block') {
      static blotName = 'pagebreak';
      static tagName = 'div';
      static className = 'page-break';

      static create() {
        const node = super.create();
        node.classList.add(this.className);
        return node;
      }
    };
    Quill.register(PageBreak, true);

    // 给工具栏添加分页按钮的点击事件
    const toolbar = quillInstance.current.getModule('toolbar');
    toolbar.addHandler('pagebreak', () => {
      const range = quillInstance.current.getSelection();
      quillInstance.current.insertEmbed(range.index, 'pagebreak', true, 'user');
      quillInstance.current.setSelection(range.index + 1);
    });
  }, []);

  return (
    <div className="quill-editor-wrapper">
      <div ref={editorRef} />
    </div>
  );
};

export default QuillWithHeaderFooter;

优缺点：

• ✅ 实现简单，不需要复杂的Quill修改
• ✅ 导出PDF（比如用html2pdf）时会自动识别每页的页眉页脚
• ❌ 编辑时页眉页脚是固定在容器顶部/底部的，不会随内容分页实时显示在每一页编辑区域内

如果需要在编辑过程中就能看到每一页的页眉页脚，可以写一个自定义模块，监听内容变化，计算分页位置，动态插入只读的页眉页脚Blot。

步骤： #

1. 定义只读的页眉/页脚Blot（设置contentEditable="false"）
2. 监听编辑器文本变化和窗口resize，计算每页的内容高度，在分页处插入页眉页脚

// 注册只读页眉Blot
const HeaderBlot = class extends Quill.import('blots/block') {
  static blotName = 'editor-header';
  static tagName = 'div';
  static className = 'editor-header';

  static create(content) {
    const node = super.create();
    node.classList.add(this.className);
    node.contentEditable = 'false'; // 设置为只读
    node.innerText = content || '默认页眉';
    return node;
  }
};
Quill.register(HeaderBlot, true);

// 注册只读页脚Blot
const FooterBlot = class extends Quill.import('blots/block') {
  static blotName = 'editor-footer';
  static tagName = 'div';
  static className = 'editor-footer';

  static create(content) {
    const node = super.create();
    node.classList.add(this.className);
    node.contentEditable = 'false';
    node.innerText = content || '默认页脚';
    return node;
  }
};
Quill.register(FooterBlot, true);

动态插入逻辑： #

useEffect(() => {
  if (!quillInstance.current) return;

  const checkAndInsertHeadersFooters = () => {
    const editor = quillInstance.current;
    const container = editor.container;
    const pageContentHeight = 297mm - 40mm; // A4纸减去上下边距的可编辑高度

    // 先移除已有的页眉页脚，避免重复插入
    container.querySelectorAll('.editor-header, .editor-footer').forEach(el => el.remove());

    let currentPageTop = 0;
    const lines = editor.getLines(); // 获取所有文本块

    lines.forEach((line, index) => {
      const rect = line.getBoundingClientRect();
      const lineTop = rect.top - container.getBoundingClientRect().top;

      // 判断当前块是否超出当前页高度
      if (lineTop > currentPageTop + pageContentHeight) {
        // 在上一页末尾插入页脚
        editor.insertEmbed(index, 'editor-footer', '自定义页脚内容', 'user');
        // 在当前页开头插入页眉
        editor.insertEmbed(index + 1, 'editor-header', '自定义页眉内容', 'user');
        currentPageTop += pageContentHeight;
      }
    });

    // 给最后一页添加页脚
    editor.insertEmbed(editor.getLength(), 'editor-footer', '自定义页脚内容', 'user');
  };

  // 监听文本变化和窗口resize
  quillInstance.current.on('text-change', checkAndInsertHeadersFooters);
  window.addEventListener('resize', checkAndInsertHeadersFooters);

  // 初始加载时执行一次
  checkAndInsertHeadersFooters();

  return () => {
    quillInstance.current.off('text-change', checkAndInsertHeadersFooters);
    window.removeEventListener('resize', checkAndInsertHeadersFooters);
  };
}, []);

优缺点：

• ✅ 编辑时能实时看到每一页的页眉页脚，体验更贴近Word
• ❌ 分页计算逻辑较复杂，需要处理图片、大段文本等特殊内容的高度偏差
• ❌ 性能可能受影响（频繁监听文本变化），需要做防抖优化

如果编辑时不需要显示页眉页脚，只要求导出的PDF/文档有，那么可以在导出环节用工具（比如html2pdf、jsPDF）统一添加，Quill只负责编辑内容。

示例（用html2pdf）： #

const exportToPDF = () => {
  const editorContent = quillInstance.current.root.innerHTML;
  const pdfHtml = `
    <div style="width:210mm; padding:20mm;">
      ${editorContent}
    </div>
  `;

  const options = {
    margin: 0,
    filename: 'document.pdf',
    html2canvas: { scale: 2 },
    jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' },
    // 自定义页眉
    header: {
      content: '你的页眉内容',
      fontSize: 10,
      margin: [20, 10, 20, 0]
    },
    // 自定义页脚（带页码）
    footer: {
      content: (page, pages) => `第 ${page} 页 / 共 ${pages} 页`,
      fontSize: 10,
      margin: [20, 0, 20, 10]
    }
  };

  html2pdf().set(options).from(pdfHtml).save();
};

优缺点：

• ✅ 完全不影响Quill的编辑逻辑，实现最简单
• ✅ 导出时的页眉页脚样式可控性强
• ❌ 编辑过程中看不到页眉页脚，适合对预览要求不高的场景

你可以根据自己的需求选择合适的方案：如果要编辑时实时预览选思路2，只需要导出有页眉页脚选思路3，想要平衡开发成本和预览体验选思路1。

内容的提问来源于stack exchange，提问作者Cabezaa