组合框(Combobox)

Utilities for adding combobox to your editor.

内联组合框

提及功能

使用@插入用户、页面或任何参考的提及

斜杠命令

通过/快速访问编辑器命令和块

表情符号

使用:自动补全插入表情符号

功能特性

创建基于触发器的组合框功能的实用工具
可配置的触发字符和模式
键盘导航和选择处理

创建组合框插件

安装

pnpm add @platejs/combobox

pnpm add @platejs/combobox

创建输入插件

首先创建一个输入插件，当触发器激活时将被插入：

import { createSlatePlugin } from 'platejs';
 
const TagInputPlugin = createSlatePlugin({
  key: 'tag_input',
  editOnly: true,
  node: {
    isElement: true,
    isInline: true,
    isVoid: true,
  },
});

import { createSlatePlugin } from 'platejs';
 
const TagInputPlugin = createSlatePlugin({
  key: 'tag_input',
  editOnly: true,
  node: {
    isElement: true,
    isInline: true,
    isVoid: true,
  },
});

创建主插件

使用withTriggerCombobox创建主插件：

import { createTSlatePlugin, type PluginConfig } from 'platejs';
import { 
  type TriggerComboboxPluginOptions, 
  withTriggerCombobox 
} from '@platejs/combobox';
 
type TagConfig = PluginConfig<'tag', TriggerComboboxPluginOptions>;
 
export const TagPlugin = createTSlatePlugin<TagConfig>({
  key: 'tag',
  node: { isElement: true, isInline: true, isVoid: true },
  options: {
    trigger: '#',
    triggerPreviousCharPattern: /^\s?$/,
    createComboboxInput: () => ({
      children: [{ text: '' }],
      type: 'tag_input',
    }),
  },
  plugins: [TagInputPlugin],
}).overrideEditor(withTriggerCombobox);

import { createTSlatePlugin, type PluginConfig } from 'platejs';
import { 
  type TriggerComboboxPluginOptions, 
  withTriggerCombobox 
} from '@platejs/combobox';
 
type TagConfig = PluginConfig<'tag', TriggerComboboxPluginOptions>;
 
export const TagPlugin = createTSlatePlugin<TagConfig>({
  key: 'tag',
  node: { isElement: true, isInline: true, isVoid: true },
  options: {
    trigger: '#',
    triggerPreviousCharPattern: /^\s?$/,
    createComboboxInput: () => ({
      children: [{ text: '' }],
      type: 'tag_input',
    }),
  },
  plugins: [TagInputPlugin],
}).overrideEditor(withTriggerCombobox);

node.isElement: 定义此为元素节点(非文本)
node.isInline: 使标签元素内联(非块级)
node.isVoid: 防止在标签元素内编辑
options.trigger: 触发组合框的字符(本例为#)
options.triggerPreviousCharPattern: 必须匹配触发器前字符的正则表达式。/^\s?$/允许在行首或空白后触发
options.createComboboxInput: 触发器激活时创建输入元素节点的函数

创建组件

使用InlineCombobox创建输入元素组件：

import { PlateElement, useFocused, useReadOnly, useSelected } from 'platejs/react';
import {
  InlineCombobox,
  InlineComboboxContent,
  InlineComboboxEmpty,
  InlineComboboxInput,
  InlineComboboxItem,
} from '@/components/ui/inline-combobox';
import { cn } from '@/lib/utils';
 
const tags = [
  { id: 'frontend', name: '前端', color: 'blue' },
  { id: 'backend', name: '后端', color: 'green' },
  { id: 'design', name: '设计', color: 'purple' },
  { id: 'urgent', name: '紧急', color: 'red' },
];
 
export function TagInputElement({ element, ...props }) {
  return (
    <PlateElement as="span" {...props}>
      <InlineCombobox element={element} trigger="#">
        <InlineComboboxInput />
        
        <InlineComboboxContent>
          <InlineComboboxEmpty>未找到标签</InlineComboboxEmpty>
          
          {tags.map((tag) => (
            <InlineComboboxItem
              key={tag.id}
              value={tag.name}
              onClick={() => {
                // 插入实际标签元素
                editor.tf.insertNodes({
                  type: 'tag',
                  tagId: tag.id,
                  children: [{ text: tag.name }],
                });
              }}
            >
              <span 
                className={`w-3 h-3 rounded-full bg-${tag.color}-500 mr-2`}
              />
              #{tag.name}
            </InlineComboboxItem>
          ))}
        </InlineComboboxContent>
      </InlineCombobox>
      
      {props.children}
    </PlateElement>
  );
}
 
export function TagElement({ element, ...props }) {
  const selected = useSelected();
  const focused = useFocused();
  const readOnly = useReadOnly();
 
  return (
    <PlateElement
      {...props}
      className={cn(
        'inline-block rounded-md bg-primary/10 px-1.5 py-0.5 align-baseline text-sm font-medium text-primary',
        !readOnly && 'cursor-pointer',
        selected && focused && 'ring-2 ring-ring'
      )}
      attributes={{
        ...props.attributes,
        contentEditable: false,
        'data-slate-value': element.value,
      }}
    >
      #{element.value}
      {props.children}
    </PlateElement>
  );
}

import { PlateElement, useFocused, useReadOnly, useSelected } from 'platejs/react';
import {
  InlineCombobox,
  InlineComboboxContent,
  InlineComboboxEmpty,
  InlineComboboxInput,
  InlineComboboxItem,
} from '@/components/ui/inline-combobox';
import { cn } from '@/lib/utils';
 
const tags = [
  { id: 'frontend', name: '前端', color: 'blue' },
  { id: 'backend', name: '后端', color: 'green' },
  { id: 'design', name: '设计', color: 'purple' },
  { id: 'urgent', name: '紧急', color: 'red' },
];
 
export function TagInputElement({ element, ...props }) {
  return (
    <PlateElement as="span" {...props}>
      <InlineCombobox element={element} trigger="#">
        <InlineComboboxInput />
        
        <InlineComboboxContent>
          <InlineComboboxEmpty>未找到标签</InlineComboboxEmpty>
          
          {tags.map((tag) => (
            <InlineComboboxItem
              key={tag.id}
              value={tag.name}
              onClick={() => {
                // 插入实际标签元素
                editor.tf.insertNodes({
                  type: 'tag',
                  tagId: tag.id,
                  children: [{ text: tag.name }],
                });
              }}
            >
              <span 
                className={`w-3 h-3 rounded-full bg-${tag.color}-500 mr-2`}
              />
              #{tag.name}
            </InlineComboboxItem>
          ))}
        </InlineComboboxContent>
      </InlineCombobox>
      
      {props.children}
    </PlateElement>
  );
}
 
export function TagElement({ element, ...props }) {
  const selected = useSelected();
  const focused = useFocused();
  const readOnly = useReadOnly();
 
  return (
    <PlateElement
      {...props}
      className={cn(
        'inline-block rounded-md bg-primary/10 px-1.5 py-0.5 align-baseline text-sm font-medium text-primary',
        !readOnly && 'cursor-pointer',
        selected && focused && 'ring-2 ring-ring'
      )}
      attributes={{
        ...props.attributes,
        contentEditable: false,
        'data-slate-value': element.value,
      }}
    >
      #{element.value}
      {props.children}
    </PlateElement>
  );
}

添加到编辑器

import { createPlateEditor } from 'platejs/react';
import { TagPlugin, TagInputPlugin } from './tag-plugin';
import { TagElement, TagInputElement } from './tag-components';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    TagPlugin.configure({
      options: {
        triggerQuery: (editor) => {
          // 在代码块中禁用
          return !editor.api.some({ match: { type: 'code_block' } });
        },
      },
    }).withComponent(TagElement),
    TagInputPlugin.withComponent(TagInputElement),
  ],
});

import { createPlateEditor } from 'platejs/react';
import { TagPlugin, TagInputPlugin } from './tag-plugin';
import { TagElement, TagInputElement } from './tag-components';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    TagPlugin.configure({
      options: {
        triggerQuery: (editor) => {
          // 在代码块中禁用
          return !editor.api.some({ match: { type: 'code_block' } });
        },
      },
    }).withComponent(TagElement),
    TagInputPlugin.withComponent(TagInputElement),
  ],
});

options.triggerQuery: 根据编辑器状态有条件启用/禁用触发器的可选函数

示例

Loading…

配置选项

TriggerComboboxPluginOptions

基于触发器的组合框插件的配置选项。

Options

触发器激活时创建输入节点的函数。

触发组合框的字符。可以是：

单个字符(如'@')
字符数组
正则表达式

匹配触发器前字符的模式。

示例: /^\s?$/ 匹配行首或空格

控制触发器何时激活的自定义查询函数。

钩子函数

useComboboxInput

管理组合框输入行为和键盘交互的钩子。

Options

输入元素的引用。

挂载时自动聚焦输入。

默认: true

方向键取消输入。

默认: true

起始位置退格键取消输入。

默认: true

失去焦点时取消输入。

默认: true

取消选择时取消输入。

默认: true

Escape键取消输入。

默认: true

当前光标位置状态。

将撤销/重做转发给编辑器。

默认: true

输入取消时的回调函数。

Returns

取消输入的函数。

输入元素的属性。

移除输入节点的函数。

useHTMLInputCursorState

跟踪HTML输入元素中光标位置的钩子。

Parameters

要跟踪的输入元素的引用。

Returns

光标是否在输入起始位置。

光标是否在输入结束位置。

Caption Emoji

On This Page

功能特性创建组合框插件安装创建输入插件创建主插件创建组件添加到编辑器示例配置选项 TriggerComboboxPluginOptions 钩子函数 useComboboxInput useHTMLInputCursorState

构建你的编辑器

生产就绪的 AI 模板和可重用的组件。

组合框(Combobox)

提及功能

斜杠命令

表情符号

功能特性

创建组合框插件

安装

创建输入插件

创建主插件

创建组件

添加到编辑器

示例

配置选项

TriggerComboboxPluginOptions

Options

createComboboxInput (trigger: string) => TElement

createComboboxInput (trigger: string) => TElement

trigger RegExp | string[] | string

trigger RegExp | string[] | string

triggerPreviousCharPattern optional RegExp

triggerPreviousCharPattern optional RegExp

triggerQuery optional (editor: SlateEditor) => boolean

triggerQuery optional (editor: SlateEditor) => boolean

钩子函数

useComboboxInput

Options

ref RefObject<HTMLElement>

ref RefObject<HTMLElement>

autoFocus optional boolean

autoFocus optional boolean

cancelInputOnArrowLeftRight optional boolean

cancelInputOnArrowLeftRight optional boolean

cancelInputOnBackspace optional boolean

cancelInputOnBackspace optional boolean

cancelInputOnBlur optional boolean

cancelInputOnBlur optional boolean

cancelInputOnDeselect optional boolean

cancelInputOnDeselect optional boolean

cancelInputOnEscape optional boolean

cancelInputOnEscape optional boolean

cursorState optional ComboboxInputCursorState

cursorState optional ComboboxInputCursorState

forwardUndoRedoToEditor optional boolean

forwardUndoRedoToEditor optional boolean

onCancelInput optional (cause: CancelComboboxInputCause) => void

onCancelInput optional (cause: CancelComboboxInputCause) => void

Returns

cancelInput (cause?: CancelComboboxInputCause, focusEditor?: boolean) => void

cancelInput (cause?: CancelComboboxInputCause, focusEditor?: boolean) => void

props object

props object

removeInput (focusEditor?: boolean) => void

removeInput (focusEditor?: boolean) => void

useHTMLInputCursorState

Parameters

ref RefObject<HTMLInputElement>

ref RefObject<HTMLInputElement>

Returns

atStart boolean

atStart boolean

atEnd boolean

atEnd boolean