块占位符

PreviousNext

当块为空时显示占位内容。

Files
components/demo.tsx
'use client';

import * as React from 'react';

import { Plate, usePlateEditor } from 'platejs/react';

import { EditorKit } from '@/components/editor/editor-kit';
import { Editor, EditorContainer } from '@/components/ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = usePlateEditor({
    plugins: EditorKit,
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
block-placeholder-demo
block-placeholder-demo

特性

  • 为空白块添加可自定义的占位文本
  • 根据块类型显示不同的占位内容
  • 使用查询函数配置可见性规则

套件使用方式

安装

最快速添加块占位符的方式是使用 BlockPlaceholderKit，它包含预配置的 BlockPlaceholderPlugin。

'use client';

import { KEYS } from 'platejs';
import { BlockPlaceholderPlugin } from 'platejs/react';

export const BlockPlaceholderKit = [
  BlockPlaceholderPlugin.configure({
    options: {
      className:
        'before:absolute before:cursor-text before:text-muted-foreground/80 before:content-[attr(placeholder)]',
      placeholders: {
        [KEYS.p]: 'Type something...',
      },
      query: ({ path }) => {
        return path.length === 1;
      },
    },
  }),
];

添加套件

import { createPlateEditor } from 'platejs/react';
import { BlockPlaceholderKit } from '@/components/editor/plugins/block-placeholder-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    ...BlockPlaceholderKit,
  ],
});

手动使用方式

安装

块占位符功能已包含在 Plate 核心包中。

import { BlockPlaceholderPlugin } from 'platejs/react';

添加插件

import { BlockPlaceholderPlugin } from 'platejs/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    BlockPlaceholderPlugin,
  ],
});

配置插件

为不同块类型配置占位内容：

import { KEYS } from 'platejs';
import { BlockPlaceholderPlugin } from 'platejs/react';
 
BlockPlaceholderPlugin.configure({
  options: {
    placeholders: {
      [KEYS.p]: '输入内容...',
      [KEYS.h1]: '输入标题...',
      [KEYS.blockquote]: '输入引用...',
      [KEYS.codeBlock]: '输入代码...',
    },
  },
});

高级配置

自定义外观和可见性规则：

import { KEYS } from 'platejs';
import { BlockPlaceholderPlugin } from 'platejs/react';
 
BlockPlaceholderPlugin.configure({
  options: {
    className: 'before:absolute before:cursor-text before:opacity-30 before:content-[attr(placeholder)]',
    placeholders: {
      [KEYS.p]: '输入内容...',
    },
    query: ({ path }) => {
      // 仅在最外层块显示占位符
      return path.length === 1;
    },
  },
});
  • placeholders: 块类型与占位文本的映射
  • className: 应用于带占位符块的 CSS 类
  • query: 决定哪些块应显示占位符的函数

插件

BlockPlaceholderPlugin

用于在空白块中显示占位文本的插件。

当满足以下所有条件时，插件会显示占位符：

  1. 块为空（不含内容）
  2. 编辑器不为空（有其他内容）
  3. 编辑器处于聚焦状态
  4. 块符合查询函数条件
  5. 块类型匹配 placeholders 映射中的键

Options

Collapse all

    插件键与占位文本字符串的映射

    • 默认值: { [KEYS.p]: '输入内容...' }

    决定块是否应显示占位符的函数

    • 默认值: 对最外层块返回 true (path.length === 1)

    应用于带占位符块的 CSS 类

Block MenuBlock Placeholder