标题

标题功能可帮助您通过在文本部分添加标题来构建文档。它们使读者和搜索引擎更容易扫描您的内容。

# 演示

使用工具栏下拉菜单为标题设置样式。您也可以键入一个或多个# 字符（取决于标题级别），然后是一个空格，自动格式化功能将创建一个新标题。

# 标题级别

默认情况下，此功能配置为支持<h2>、<h3> 和 <h4> 元素，分别命名为：“标题 1”、“标题 2”和“标题 3”。从<h2> 开始的原因是<h1> 应保留用于 页面主标题，而页面内容通常从<h2> 开始。

默认情况下，当您的编辑器预设不包含标题插件时，粘贴到富文本编辑器中的<h1> 元素将转换为<h2>（“标题 1”）。

# 标题按钮

标题功能还允许您使用一组标题按钮，而不是下拉列表。工具栏按钮是可配置的，也可以包含一个段落按钮。比较上面演示中的标题工具栏下拉菜单和下面的标题按钮，检查此变体的功能和可用性。

# 安装

在安装编辑器后，将该功能添加到您的插件列表和工具栏配置中。

import { ClassicEditor, Heading } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Heading, /* ... */ ],
        toolbar: [ 'heading', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 带工具栏标题按钮的安装

要配置工具栏按钮以将文本样式设置为标题和段落，您需要将以下内容导入到您的插件列表和配置中。

import { ClassicEditor, HeadingButtonsUI, ParagraphButtonUI } from 'ckeditor5';

# 配置

# 配置标题级别

您可以配置编辑器将支持的标题级别以及它们在“标题”下拉菜单中的显示名称。使用heading.options配置选项来实现此目的。

例如，以下编辑器将仅支持两个级别的标题 - <h1>和<h2>。

<div id="editor">
    <h1>Heading 1</h1>
    <h2>Heading 2</h2>
    <p>This is <a href="https://ckeditor.npmjs.net.cn">CKEditor&nbsp;5</a>.</p>
</div>

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        heading: {
            options: [
                { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置自定义标题元素

也可以通过使用高级格式的heading.options配置选项来定义标题的完全自定义元素。

例如，以下编辑器将同时支持以下两个标题选项：<h2 class="fancy">和<h2>。

<style>
    /* Styles for the heading in the content and for the dropdown item. */
    h2.fancy, .ck.ck-button.ck-heading_heading2_fancy {
        color: #ff0050;
        font-size: 17px;
    }
</style>

<div id="snippet-custom-heading-levels">
    <h1>Heading 1</h1>
    <h2>Heading 2</h2>
    <h2 class="fancy">Fancy Heading 2</h2>
    <p>This is <a href="https://ckeditor.npmjs.net.cn">CKEditor&nbsp;5</a>.</p>
</div>

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        heading: {
            options: [
                { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                {
                    model: 'headingFancy',
                    view: {
                        name: 'h2',
                        classes: 'fancy'
                    },
                    title: 'Heading 2 (fancy)',
                    class: 'ck-heading_heading2_fancy',

                    // It needs to be converted before the standard 'heading2'.
                    converterPriority: 'high'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置工具栏按钮

要使用单个工具栏按钮而不是标题下拉菜单，您需要正确配置该功能。您还需要导入正确的 UI 元素；有关操作方法的说明，请参见安装部分。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', '|', 'undo', 'redo' ],
        heading: {
            options: [
                { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                { model: 'heading5', view: 'h5', title: 'Heading 5', class: 'ck-heading_heading5' },
                { model: 'heading6', view: 'h6', title: 'Heading 6', class: 'ck-heading_heading6' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 相关功能

还有更多 CKEditor 5 功能可以帮助您格式化内容。

• 基本文本样式 - 基本要素，如粗体、斜体等。
• 文档标题 - 清晰地将您的内容划分为标题和正文。
• 块缩进 - 设置段落或列表等文本块的缩进。
• 列表 - 使用可以设置样式的有序和无序列表更好地组织您的内容。
• 删除格式 - 轻松清除基本文本格式。
• 自动格式化 - 在您使用 Markdown 代码键入时添加格式元素（例如标题）。

# 通用 API

Heading插件注册

• 'heading'下拉菜单。

• 'heading'命令，接受基于heading.options配置选项的值。

  您可以通过执行以下命令之一将当前选定的块转换为标题

  editor.execute( 'heading', { value: 'heading2' } );
  

HeadingButtonsUI插件注册六个 UI 按钮组件，这些组件将使用value属性的正确值来执行'heading'命令。

• 'heading1'
• 'heading2'
• 'heading3'
• 'heading4'
• 'heading5'
• 'heading6'

ParagraphButtonUI插件注册 UI 按钮组件：'paragraph'。

# 贡献

该功能的源代码可在 GitHub 上获得，地址为https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-heading。