feat(@vben/plugins): tiptap 组件新增 maxHeight 属性支持及文档 (#7897)
* feat(@vben/plugins): tiptap 组件新增 maxHeight 属性支持 - 新增 maxHeight prop 支持限制编辑器最大高度 - 编辑器内容区超出最大高度时自动滚动 - 移除 style.css 中未使用的 CSS 规则 * docs(@vben/plugins): 添加 tiptap 富文本编辑器组件文档 - 新增中文文档 docs/src/components/common-ui/vben-tiptap.md - 新增英文文档 docs/src/en/components/common-ui/vben-tiptap.md - 新增基础用法示例 demos/vben-tiptap/basic - 新增图片上传示例 demos/vben-tiptap/image-upload - 更新文档侧边栏配置 * fix(@vben/plugins): extract URL from response in image upload callback The upload callback was incorrectly passing the AxiosResponse object to resolve() instead of extracting the actual image URL string. This caused the editor to insert [object Object] as image src, resulting in broken images. * chore: add changeset for tiptap maxHeight feature * Revert "chore: add changeset for tiptap maxHeight feature" This reverts commit a28fc4441f14641f6af6c1a143aa6959591315b2.
This commit is contained in:
JyQAQ
199
docs/src/en/components/common-ui/vben-tiptap.md
Normal file
199
docs/src/en/components/common-ui/vben-tiptap.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Vben Tiptap Rich Text Editor
|
||||
|
||||
A rich text editor component built on [Tiptap](https://tiptap.dev/), supporting rich text formatting, image insertion, and image upload features.
|
||||
|
||||
> If some details are not obvious from the docs, check the live demos as well.
|
||||
|
||||
::: info Note
|
||||
|
||||
If you feel the current component implementation doesn't meet your needs, you can use native components directly or create your own component. The components provided by the framework are not constraints - use them at your discretion.
|
||||
|
||||
:::
|
||||
|
||||
## Basic Usage
|
||||
|
||||
<DemoPreview dir="demos/vben-tiptap/basic" />
|
||||
|
||||
## Component List
|
||||
|
||||
### VbenTiptap
|
||||
|
||||
Main rich text editor component.
|
||||
|
||||
### VbenTiptapPreview
|
||||
|
||||
Read-only preview component for displaying editor content.
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| Property | Description | Type | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `modelValue` (v-model) | Editor content (HTML string) | `string` | `''` |
|
||||
| `editable` | Whether the editor is editable | `boolean` | `true` |
|
||||
| `toolbar` | Whether to show the toolbar | `boolean` | `true` |
|
||||
| `previewable` | Whether to show the preview button | `boolean` | `true` |
|
||||
| `placeholder` | Placeholder text | `string` | - |
|
||||
| `minHeight` | Minimum height | `number \| string` | `240` |
|
||||
| `maxHeight` | Maximum height | `number \| string` | `400` |
|
||||
| `extensions` | Custom Tiptap extensions | `Extensions` | - |
|
||||
| `imageUpload` | Image upload configuration | `ImageUploadOptions` | - |
|
||||
|
||||
### Events
|
||||
|
||||
| Event | Description | Parameters |
|
||||
| -------- | ------------------------------ | ----------------------- |
|
||||
| `change` | Triggered when content changes | `VbenTiptapChangeEvent` |
|
||||
|
||||
#### VbenTiptapChangeEvent
|
||||
|
||||
```ts
|
||||
interface VbenTiptapChangeEvent {
|
||||
html: string; // HTML content
|
||||
json: JSONContent; // JSON structure
|
||||
text: string; // Plain text content
|
||||
}
|
||||
```
|
||||
|
||||
### ImageUploadOptions
|
||||
|
||||
Image upload configuration:
|
||||
|
||||
```ts
|
||||
interface ImageUploadOptions {
|
||||
/** Allowed file types, default 'image/*' */
|
||||
accept?: string;
|
||||
/** Max file size in bytes, default 5MB */
|
||||
maxSize?: number;
|
||||
/** Upload error callback, uses alert if not provided */
|
||||
onUploadError?: (error: unknown) => void;
|
||||
/** Upload function, returns image URL */
|
||||
upload: (
|
||||
file: File,
|
||||
onProgress?: (percent: number) => void,
|
||||
) => Promise<string>;
|
||||
}
|
||||
```
|
||||
|
||||
### VbenTiptapPreview Props
|
||||
|
||||
| Property | Description | Type | Default |
|
||||
| ----------- | ----------------------- | ------------------ | ------- |
|
||||
| `content` | HTML content to preview | `string` | `''` |
|
||||
| `minHeight` | Minimum height | `number \| string` | `160` |
|
||||
| `class` | Custom class name | `any` | - |
|
||||
|
||||
## Toolbar Features
|
||||
|
||||
The editor toolbar provides the following features:
|
||||
|
||||
### Formatting
|
||||
|
||||
- **Undo/Redo** - Undo or redo editing operations
|
||||
- **Clear Formatting** - Remove all formatting from selected text
|
||||
- **Bold** - Bold text
|
||||
- **Italic** - Italic text
|
||||
- **Underline** - Underline text
|
||||
- **Strikethrough** - Strikethrough text
|
||||
- **Inline Code** - Inline code mark
|
||||
|
||||
### Structure
|
||||
|
||||
- **Headings** - Paragraph, H1-H4 heading switching
|
||||
- **Ordered List** - Numbered list
|
||||
- **Bullet List** - Bulleted list
|
||||
- **Blockquote** - Quote block style
|
||||
- **Code Block** - Multi-line code block
|
||||
|
||||
### Links & Images
|
||||
|
||||
- **Insert Link** - Insert or edit hyperlinks
|
||||
- **Remove Link** - Remove link from selected text
|
||||
- **Insert Image** - Insert image via URL
|
||||
|
||||
### Style
|
||||
|
||||
- **Text Color** - Set text color (preset palette)
|
||||
- **Highlight Color** - Set text background highlight color
|
||||
|
||||
### Alignment
|
||||
|
||||
- **Align Left** - Left align text
|
||||
- **Align Center** - Center align text
|
||||
- **Align Right** - Right align text
|
||||
|
||||
### Other
|
||||
|
||||
- **Preview** - Preview content in a modal
|
||||
|
||||
## Image Upload
|
||||
|
||||
<DemoPreview dir="demos/vben-tiptap/image-upload" />
|
||||
|
||||
When `imageUpload` is configured, the toolbar image button becomes a dropdown menu with "Upload" and "URL" options.
|
||||
|
||||
### Upload Methods
|
||||
|
||||
Three image upload methods are supported:
|
||||
|
||||
1. **File Selection** - Click the upload button in toolbar
|
||||
2. **Drag & Drop** - Drag images directly into the editor
|
||||
3. **Paste** - Paste images into the editor
|
||||
|
||||
### Upload Progress Display
|
||||
|
||||
During upload:
|
||||
|
||||
- **Loading Indicator** - Spinner animation indicating upload in progress
|
||||
- **Progress Bar** - Shows progress bar when upload function provides `onProgress` callback
|
||||
|
||||
### File Validation
|
||||
|
||||
- `accept` - Specify allowed file types (MIME types)
|
||||
- `maxSize` - Maximum file size limit (bytes)
|
||||
- Validation failure triggers `onUploadError` callback or default alert
|
||||
|
||||
::: warning Important Notes
|
||||
|
||||
- Only single image upload is supported; multi-image drag/paste will show a prompt and process only the first image
|
||||
- Do not save editor content (`getHTML()`) during upload as image URLs are temporary blob URLs
|
||||
- When using custom `extensions`, the image upload feature will not be available (toolbar won't show upload option)
|
||||
|
||||
:::
|
||||
|
||||
## Custom Extensions
|
||||
|
||||
Pass custom Tiptap extension configurations via the `extensions` property:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { VbenTiptap } from '@vben/plugins/tiptap';
|
||||
import StarterKit from '@tiptap/starter-kit';
|
||||
import Underline from '@tiptap/extension-underline';
|
||||
|
||||
const extensions = [
|
||||
StarterKit,
|
||||
Underline,
|
||||
// Other extensions...
|
||||
];
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<VbenTiptap v-model="content" :extensions="extensions" />
|
||||
</template>
|
||||
```
|
||||
|
||||
::: warning Custom Extensions Note
|
||||
|
||||
When using custom `extensions`:
|
||||
|
||||
- Default extension configuration will not take effect
|
||||
- Image upload feature is not available (toolbar won't show upload option)
|
||||
- You need to configure all required editor features yourself
|
||||
|
||||
:::
|
||||
Reference in New Issue
Block a user