---
title: "占位符扩展"
description: "为您的 Tiptap 编辑器配置一个有用的占位符，以填充空白。了解如何在文档中设置和使用它！"
canonical_url: "https://tiptap.zhcndoc.com/editor/extensions/functionality/placeholder"
---

# 占位符扩展

为您的 Tiptap 编辑器配置一个有用的占位符，以填充空白。了解如何在文档中设置和使用它！

该扩展提供了占位符支持。给你的用户一个小提示，告诉他们应该写些什么。如果你愿意，可以自定义一些内容。

> **Interactive demo:** [Placeholder](https://embed.tiptap.dev/preview/Extensions/Placeholder)

## 安装

```bash
npm install @tiptap/extensions
```

## 用法

```js
import { Editor } from '@tiptap/core'
import { Placeholder } from '@tiptap/extensions'

new Editor({
  extensions: [
    Placeholder.configure({
      placeholder: '写点什么 …',
    }),
  ],
})
```

### 额外设置

占位符是通过 CSS 显示的。

**仅在空编辑器的第一行显示占位符。**

```
.tiptap p.is-editor-empty:first-child::before {
  color: #adb5bd;
  content: attr(data-placeholder);
  float: left;
  height: 0;
  pointer-events: none;
}
```

**在每个新行上显示占位符。**

```
.tiptap p.is-empty::before {
  color: #adb5bd;
  content: attr(data-placeholder);
  float: left;
  height: 0;
  pointer-events: none;
}
```

## 设置

### emptyEditorClass

如果编辑器为空，添加的 CSS 类。

默认值：`'is-editor-empty'`

```js
Placeholder.configure({
  emptyEditorClass: 'is-editor-empty',
})
```

### emptyNodeClass

如果节点为空，添加的 CSS 类。

默认值：`'is-empty'`

```js
Placeholder.configure({
  emptyNodeClass: 'my-custom-is-empty-class',
})
```

也可以使用函数根据节点来决定类名：

```js
Placeholder.configure({
  emptyNodeClass: ({ node }) => {
    if (node.type.name === 'heading') {
      return 'my-custom-is-empty-heading-class'
    }
    return ''
  },
})
```

### dataAttribute

用于存储占位符文本的数据属性。当设置为 `'my-placeholder'` 时，占位符文本将存储在 `data-my-placeholder` 属性中，例如。

默认值：`'placeholder'`

```js
Placeholder.configure({
  dataAttribute: 'my-placeholder'
})
```

### placeholder

作为 `data-placeholder` 属性添加的占位符文本。

默认值：`'写点什么 …'`

```js
Placeholder.configure({
  placeholder: '我的自定义占位符',
})
```

您甚至可以使用一个函数，根据节点添加占位符：

```js
Placeholder.configure({
  placeholder: ({ node }) => {
    if (node.type.name === 'heading') {
      return '标题是什么？'
    }

    return '您能提供更多上下文吗？'
  },
})
```

### showOnlyWhenEditable

仅在编辑器可编辑时显示装饰。

默认值：`true`

```js
Placeholder.configure({
  showOnlyWhenEditable: false,
})
```

### showOnlyCurrent

仅在当前选定的节点中显示装饰。

默认值：`true`

```js
Placeholder.configure({
  showOnlyCurrent: false,
})
```

### includeChildren

同时为嵌套节点显示装饰。只有文本块节点（直接包含行内内容的节点，例如 `paragraph` 或 `heading`）会显示占位符——像 `bulletList` 或 `listItem` 这样的包装节点会自动跳过。

默认值：`false`

```js
Placeholder.configure({
  includeChildren: true,
})
```

## 源代码

[packages/extensions/src/placeholder](https://github.com/ueberdosis/tiptap/blob/main/packages/extensions/src/placeholder)

## 最小安装

```js
import { Editor } from '@tiptap/core'
import { Placeholder } from '@tiptap/extensions/placeholder'

new Editor({
  extensions: [Placeholder],
})
```