如何在GrapesJS中正确使用页面框架头部持久化字体资源？

你遇到的问题核心是直接操作画布DOM的方式无法持久化到页面模型，而使用addHeadItem/setHead时格式不正确导致框架未渲染这些项。以下是符合GrapesJS框架设计的正确实现方式：

1. 正确使用Frame模型添加Head项 #

GrapesJS的Frame模型要求head项是结构化的对象（而非直接的DOM元素），每个对象需包含tag、可选的attrs和content字段。示例代码如下：

// 获取当前页面的主框架
const currentPage = editor.Pages.getSelected();
const frame = currentPage.getMainFrame();

// 添加@font-face样式
frame.addHeadItem({
  tag: 'style',
  attrs: { type: 'text/css' },
  content: `@font-face {
    font-family: "CustomFont";
    src: url("path/to/your/font.woff2") format("woff2"),
         url("path/to/your/font.woff") format("woff");
    font-weight: normal;
    font-style: normal;
  }`
});

// 添加字体预加载链接
frame.addHeadItem({
  tag: 'link',
  attrs: {
    rel: 'preload',
    href: 'path/to/your/font.woff2',
    as: 'font',
    type: 'font/woff2',
    crossorigin: 'anonymous'
  }
});

// 触发框架重新渲染，确保新添加的head项生效
frame.render();

2. 页面切换时自动同步Head项 #

由于每个页面的Frame实例是独立的，切换页面后需要确保目标页面的框架包含所需的字体配置。可以监听page:switch事件实现自动注入：

editor.on('page:switch', () => {
  const targetPage = editor.Pages.getSelected();
  const frame = targetPage.getMainFrame();
  const fontName = 'CustomFont';

  // 检查是否已存在该字体的配置，避免重复添加
  const hasFontConfig = frame.get('head').some(item => 
    item.tag === 'style' && item.content?.includes(fontName)
  );

  if (!hasFontConfig) {
    // 重复上述添加head项的代码
    frame.addHeadItem({/* style配置 */});
    frame.addHeadItem({/* link配置 */});
    frame.render();
  }
});

3. 全局初始化时预设所有页面的Head项 #

如果你的字体是全局通用的，也可以在编辑器初始化时，给所有现有页面和新创建的页面自动注入配置：

const editor = grapesjs.init({
  // 其他配置...
});

// 给现有页面添加字体配置
editor.Pages.getAll().forEach(page => {
  const frame = page.getMainFrame();
  // 添加head项...
});

// 监听新页面创建事件，自动注入
editor.on('page:add', (page) => {
  const frame = page.getMainFrame();
  // 添加head项...
});

关键注意事项 #

• 不要直接操作画布的document.head，这种修改不会被GrapesJS的页面模型持久化，切换页面后会被重置
• 确保head项的格式符合要求：必须是包含tag属性的对象，attrs为键值对的属性集合，content用于style/script等需要内容的标签
• 修改后调用frame.render()触发框架重新渲染，确保变更生效

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