内容格式

此页面上的选项定义并自定义编辑器中可用的文本格式。要限制、禁用或从内容中剥离 HTML 格式（例如限制允许的元素或从粘贴的文本中移除格式），请参阅禁用或剥离 HTML 格式。

formats

此选项用于覆盖默认的 TinyMCE formats 或向编辑器添加自定义 formats。

TinyMCE 配备了一个格式化引擎，允许您将一组样式和属性注册为一个命名 format。例如，bold 格式就是点击加粗按钮时应用于文本的样式。

查看自定义格式示例以演示此选项。

formats 配置选项接收一个格式名称和格式规范对的对象。每个格式规范必须定义为一个对象，其值要么是格式选项的对象，要么是此类对象的数组。

如果格式指定了一个变体数组，当应用该格式时，将仅使用数组中的第一个项。但是，当尝试匹配格式以移除或更新 UI 时，数组中的其他变体也将被考虑。因此，第一个格式是主格式，其余的是次格式。

以下是包含三个变体的格式规范数组的示例：

bold: [
  { inline: 'strong', remove: 'all' },
  { inline: 'span', styles: { fontWeight: 'bold' } },
  { inline: 'b', remove: 'all' }
],

样式合并

默认情况下，相似的元素和样式会被合并，以减小输出 HTML 的大小。因此，例如，如果为一个单词选择了字体大小和字体类型，它会将这两个样式合并到一个 span 元素中，而不是每个格式类型各一个 span。

内置格式

以下格式由 TinyMCE 提供。

常规内置格式

以下格式适用于大多数内容。

mceToggleFormat 和 FormatBlock 命令不接受以下格式：

• forecolor

• hilitecolor

• fontname

• fontsize

• fontsize_class

定义列表相关格式

以下格式适用于定义列表（<dl>）。

定义数据（<dd>）元素。

链接相关格式

以下格式适用于链接（<a>）。

表格相关格式

以下格式可在表格内的 <td> 和 <th> 元素中使用。

一些内置格式 fontsize、fontname、forecolor、hilitecolor 在其定义中使用了一个名为 %value 的变量。该变量会被替换为用户选择的项，例如 color 值。详细信息请参阅下文的变量替换部分。

格式类型

有三种格式类型：

• 块格式

• 内联格式

• 选择器格式

所有三种格式类型都可以与 formats 配置选项一起使用。它们也可以用于在 style_formats 配置选项中指定新的格式项。但是，使用 formats 指定的格式会注册到编辑器中，可以在 style_formats 中通过名称引用，而无需再次指定格式。

例如，以下两个配置是等效的：

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for h1 to have a class of heading
    h1: { block: 'h1', classes: 'heading' }
  },
  style_formats: [
    // Adds the h1 format defined above to style_formats
    { title: 'My heading', format: 'h1' }
  ]
});

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  style_formats: [
    // Adds a h1 format to style_formats that applies a class of heading
    { title: 'My heading', block: 'h1', classes: 'heading' }
  ]
});

已注册的格式也可以通过内置的 使用自定义格式 按名称使用，示例如下。

block

用作包装器的块元素的标签名，例如 h1。选区内的现有块元素会被此块元素替换。

类型： String

示例：使用 block 格式

tinymce.init({
  selector: 'textarea', // change this value according to your HTML
  formats: {
    // Changes the default format for h1 to have a class of heading
    h1: { block: 'h1', classes: 'heading' }
  }
});

inline

用作包装器的内联元素的标签名，例如 span 用于包装当前选区。

类型： String

示例：使用 inline 格式

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for the bold button to produce a span with a bold class
    bold: { inline: 'span', classes: 'bold' }
  }
});

selector

用于在选区内查找元素的 CSS3 选择器模式。它可以用于仅将类应用于特定元素，例如仅应用于表格中的奇数行。

类型： String

示例：使用 selector 格式

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the alignment buttons to add a class to each of the matching selector elements
    alignleft: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'left' },
    aligncenter: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'center' },
    alignright: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'right' },
    alignjustify: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'full' }
  }
});

格式参数

对于每种格式，可以指定一些附加参数：

classes

以空格分隔的类列表，这些类：

• 应用于新创建的块或内联元素。

• 附加到块或内联元素上的现有类。

要替换现有类，请使用 class 属性。

类型： String

示例：使用 classes 参数

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for the bold button to produce a span with a bold class
    bold: { inline: 'span', classes: 'bold' }
  }
});

styles

键值对象，包含要应用于所选或新建的行内/块级元素的 CSS 样式（如 color、backgroundColor、textDecoration 等）。

类型： Object

示例：使用 styles 参数

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for the bold button to produce a span with style with font-width: bold
    bold: { inline: 'span', styles: { 'font-weight': 'bold' } }
  }
});

attributes

键值对象，包含要应用于所选或新建的行内/块级元素的属性。

类型： Object

示例：使用 attributes 参数

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for the bold button to produce a strong with data-style attribute
    bold: { inline: 'strong', attributes: { 'data-style': 'bold' } }
  }
});

示例：在 attributes 参数中使用 class

要将类应用于新的或选定的现有元素，请将 'class' 属性添加到 attributes 参数。当应用格式时，所提供的类将替换元素上所有现有的类。

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for the bold button to produce a span with a bold class
    bold: {
      inline: 'span',
      attributes: { class: 'bold' }
    }
  }
});

exact

确保该格式不会与其他具有相同格式的包装器合并。我们使用它来避免 underline 和 strikethrough 格式之间的文本装饰冲突。

类型： Boolean

默认值： false

可能的值： true、false

示例：使用 exact 参数

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // Changes the default format for the underline button to produce a span with a class and not merge that underline into parent spans
    underline: { inline: 'span', styles: { 'text-decoration': 'underline' }, exact: true },
    strikethrough: { inline: 'span', styles: { 'text-decoration': 'line-through' }, exact: true }
  }
});

wrapper

声明该格式是块级元素的容器格式。例如 div 包装器或 blockquote。

类型： Boolean

默认值： false

可能的值： true、false

示例：使用 wrapper

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    // A custom format that wraps blocks into a div with the specified wrapper class
    'custom-wrapper': { block: 'div', classes: 'wrapper', wrapper: true }
  }
});

remove

指定当格式被移除时元素的移除行为。

类型： String

默认值：对于 Selector 格式为 none，对于所有其他格式类型为 empty。

它可以设置为三种不同的模式：

• none：仅从元素移除样式、类或属性，元素本身永远不会被移除。

• empty：如果元素没有样式、类或属性，则移除该元素。

• all：无论元素的样式、类或属性如何，都移除该元素。

示例：使用 remove

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  extended_valid_elements: 'span[*]', // Needed to retain spans without attributes these are removed by default
  formats: {
    removeformat: [
      // Configures `clear formatting` to remove specified elements regardless of its attributes
      { selector: 'b,strong,em,i,font,u,strike,s', remove: 'all' },

      // Configures `clear formatting` to remove the class red from spans and if the element then becomes empty i.e has no attributes it gets removed
      { selector: 'span', classes: 'red', remove: 'empty' },

      // Configures `clear formatting` to remove the class green from spans and if the element then becomes empty it's left intact
      { selector: 'span', classes: 'green', remove: 'none' }
    ]
  }
});

block_expand

此选项控制选区是否应向上扩展到最近的匹配块级元素。在配置 removeformat 以移除块级元素时，这会很有用。因此，如果选区起始于匹配块的开头，则该匹配块也将被包含在内。如果选区结束于匹配块级元素的末尾，则该父元素也将被包含在内。

因此，如果在这个 HTML 内容 <h1><b>[a</b></h1><p>b]</p> 中，选区从 a 到 b，那么 h1 将被移除，即使它不是实际选区的一部分。

类型： Boolean

默认值： false

可能的值： true, false

示例：使用 block_expand

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配你的 HTML
  formats: {
    removeformat: [
      {
        selector: 'h1,h2,h3,h4,h5,h6',
        remove: 'all',
        split: false,
        expand: false,
        block_expand: true,
        deep: true
      },
      {
        selector: 'b,strong,em,i,font,u,strike,s,sub,sup,dfn,code,samp,kbd,var,cite,mark,q,del,ins,small',
        remove: 'all',
        split: true,
        expand: false,
        deep: true
      },
      { selector: 'span', attributes: ['style', 'class'], remove: 'empty', split: true, expand: false, deep: true },
      { selector: '*', attributes: ['style', 'class'], split: false, expand: false, deep: true }
    ]
  }
});

expand

控制是否在应用或移除格式之前将选区扩展到封闭的匹配 selector 元素。这适用于那些不是 inline 格式的 selector 格式。启用后，如果选区仅部分覆盖匹配元素，则范围会扩展到覆盖整个元素。将 expand 设置为 false 会将操作限制在当前选区内。

类型： Boolean

默认值： 对于不是 inline 格式的 selector 格式为 true

可能的值： true, false

示例：使用 expand

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配你的 HTML
  formats: {
    removeformat: [
      // 限制移除范围为当前选区，而不是扩展到整个匹配元素
      { selector: 'h1,h2,h3,h4,h5,h6', remove: 'all', expand: false, deep: true }
    ]
  }
});

split

用于移除格式时。控制是否在选区边界处拆分包裹选区的元素，以便仅从选中的文本中移除格式。当设置为 false 时，不会拆分包裹元素，因此不会从部分选区中移除格式。

类型： Boolean

默认值： 对于 inline 格式和非 selector 格式为 true；对于 selector (block) 格式为 false。

可能的值： true, false

示例：使用 split

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配你的 HTML
  formats: {
    removeformat: [
      // 移除格式而不在选区边界处拆分包裹元素
      { selector: 'span', attributes: ['style', 'class'], remove: 'empty', split: false, deep: true }
    ]
  }
});

deep

启用对移除匹配格式的子元素的控制。默认情况下，selector 格式上的此选项设置为 false。因此，当从选中的表格类中移除一个类时，禁用 deep 会在其他嵌套表格内的子元素中保留该类。

类型： Boolean

默认值： 对于 selector 格式为 false

可能的值： true, false

示例：使用 deep

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配你的 HTML
  formats: {
    // 一个自定义格式，将块级元素包裹在一个带有指定包装类的 div 中
    'custom-deep': { inline: 'span', classes: 'myclass', deep: false }
  }
});

merge_siblings

当 merge_siblings 参数设置为 false 时，两个或多个相似的内联元素不会自动合并。

当 merge_siblings 设置为 true 时，以下两个 HTML 元素会自动合并。

合并前：

<span class="myclass">some</span><span class="myclass">text</span>

合并后：

<span class="myclass">sometext</span>

类型： Boolean

默认值： true

可能的值： true, false

示例：使用 merge_siblings

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配你的 HTML
  formats: {
    // 一个自定义格式，将块级元素包裹在一个带有指定包装类的 div 中
    'custom-format': { inline: 'span', classes: 'myclass', merge_siblings: false }
  }
});

formats 选项使用示例

此示例覆盖了一些内置格式，并告诉 TinyMCE 应用类名而不是内联样式。它还包含一个自定义格式，该格式生成带有 title 属性和 red CSS 样式的 h1 元素。

类型： Object

示例：使用 formats 选项

// 以 HTML 风格输出元素
tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  formats: {
    alignleft: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'left' },
    aligncenter: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'center' },
    alignright: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'right' },
    alignjustify: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img,audio,video', classes: 'full' },
    bold: { inline: 'span', classes: 'bold' },
    italic: { inline: 'span', classes: 'italic' },
    underline: { inline: 'span', classes: 'underline', exact: true },
    strikethrough: { inline: 'del' },
    forecolor: { inline: 'span', classes: 'forecolor', styles: { color: '%value' } },
    hilitecolor: { inline: 'span', classes: 'hilitecolor', styles: { backgroundColor: '%value' } },
    custom_format: { block: 'h1', attributes: { title: 'Header' }, styles: { color: 'red' } }
  }
});

使用自定义格式

可以通过 TinyMCE API 处理自定义格式。以下是上面定义的自定义格式的基本用法示例。

// 应用指定的格式
tinymce.activeEditor.formatter.apply('custom_format');

// 移除指定的格式
tinymce.activeEditor.formatter.remove('custom_format');

变量替换

可以在格式定义中使用变量。这些变量随后会被替换为调用 apply 函数时指定的变量。以下是如何在格式中使用变量的示例。

// 注册带有变量的特殊格式
tinymce.activeEditor.formatter.register('custom_format', { inline: 'span', styles: { color: '%value' } });

// 应用带有指定变量的指定格式
tinymce.activeEditor.formatter.apply('custom_format', { value: 'red' });

移除格式

使用 removeformat 选项指定编辑器中的 清除格式 功能应如何工作。

类型： Array

示例：移除格式

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  formats: {
    removeformat: [
      {
        selector: 'b,strong,em,i,font,u,strike,s,sub,sup,dfn,code,samp,kbd,var,cite,mark,q,del,ins,small',
        remove: 'all',
        split: true,
        block_expand: true,
        expand: false,
        deep: true
      },
      { selector: 'span', attributes: ['style', 'class'], remove: 'empty', split: true, expand: false, deep: true },
      { selector: '*', attributes: ['style', 'class'], split: false, expand: false, deep: true }
    ]
  }
});

format_empty_lines

此选项允许将 "inline" 格式应用于多行选择中的空行。inline 格式的示例包括加粗 (<strong>) 和下划线 (<span style="text-decoration: underline;">)。

类型： Boolean

默认值： false

可能的值： true, false

示例：使用 format_empty_lines

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  format_empty_lines: true
});

format_noneditable_selector

如果某个元素具有 contenteditable="false" 属性，则当该元素匹配指定的选择器时，format_noneditable_selector 选项允许用格式包裹该元素。

同样，具有 contenteditable="false" 属性并且还具有 data-mce-cef-wrappable 属性的元素可以用格式包裹。

可包裹的格式包括将 wrapper 参数设置为 true 的块级格式和 inline 格式。

不支持选择器格式。

具有 contenteditable="false" 属性且包含具有 contenteditable="true" 属性的后代元素的元素不可包裹。从 TinyMCE 8.8.2 开始，选择此类元素并应用 inline 格式会将该格式应用于其每个可编辑的后代元素，而不是包裹该元素。移除和切换 inline 格式的行为相同。

类型： String

示例：使用 format_noneditable_selector

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  format_noneditable_selector: 'span,p.special'
});