🐛 [Bug]: 复制Word里面的图文内容到富文本中，图片和文字错位

[kagol]

Version

latest

Link to minimal reproduction

测试地址：https://opentiny.github.io/tiny-editor/docs/demo/basic-usage

• 在Word中输入一些内容，并在文本内容中间插入几张图片
• 然后Ctrl+A全选所有内容，Ctrl+V粘贴到TinyEditor富文本中

出现下面的情况：

• 文本和图片错位
• 多了几个image字样的文本
• 粘贴之后的光标位置也不对

预期表现应该和Word里一样：

Step to reproduce

如上

What is expected

No response

What is actually happening

No response

What is your project name

Wiki

Any additional comments (optional)

No response

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Possible Duplicates

• 🐛 [Bug]: macOS 粘贴 word 文档内容变成了图片 #72

Related Issues

• 🐛 [Bug]: 格式丢失 #68
• 🐛 [Bug]: 格式刷功能：在quill-table-up表格中使用格式刷会导致表格错乱 #294
• 🐛 [Bug]: 输入中文插入公式后输入中文标点符号逗号，会重复输入两个 #282
• ✨ [Feature]: 编辑器支持word导入功能 #120
• 🐛 [Bug]: 有序列表和无序列表内容超过一行时，序号位置显示错误 #353
• 🐛 [Bug]: better-table 表格中无法粘贴idea webstorm 等编辑器中复制的文字 #106
• 🐛 [Bug]: 上传图片以html格式时缺失src #224

👤 Suggested Assignees

• zttAsoiaf
• ihwf
• HostDay123
• code98man
• qiantan001

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Fix Word content paste issues by registering a custom image clipboard matcher to prevent Quill's default image-to-text conversion, ensuring images are properly converted to Delta embeds during HTML-to-Delta conversion. Update the image processing pipeline to work with properly formatted embeds and fix cursor positioning to correctly account for image embeds rather than text placeholders.

Observations

The fluent-editor extends Quill 2.0's Clipboard module with CustomClipboard class that handles paste operations, RTF image extraction from Word documents, and async file processing. The clipboard flow converts HTML to Delta using Quill's inherited convert() method, then processes images through an extraction-replacement pipeline. Currently, no custom clipboard matchers are registered, causing Quill's default image conversion to create text placeholders instead of proper image embeds.

Assumptions

Assumption 1: How should the custom image matcher handle the Delta conversion for img tags?

Options Considered:

• Convert each img tag to a Delta image embed operation with preserved attributes during the initial HTML-to-Delta conversion
• Skip image conversion in the matcher and let the existing extraction pipeline handle all images

Chosen Option: 1

Rationale: Converting images to proper embeds during initial conversion prevents the "image" text insertion and maintains correct text-image ordering from the start, allowing the existing RTF/file pipeline to work as refinements rather than fixes.

Assumption 2: Should cursor positioning logic calculate position before or after async image URL replacements?

Options Considered:

• Set cursor position immediately after initial paste, before async image processing completes
• Set cursor position after all async image URL replacements finish
• Set cursor position twice - initially and after async completion

Chosen Option: 1

Rationale: The existing pattern sets cursor immediately after updateContents, which is appropriate since the Delta structure (text length and image positions) is already determined; async processing only swaps image URLs without changing Delta structure or lengths.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Register Custom Image Clipboard Matcher

Prevent Quill's default image-to-text conversion by intercepting img tags during clipboard HTML-to-Delta conversion and creating proper image embeds from the start.

Add Image Matcher Registration

Register a custom clipboard matcher for IMG elements in the CustomClipboard initialization

• Add constructor to CustomClipboard class in packages/fluent-editor/src/modules/custom-clipboard.ts that calls this.addMatcher() to register image handler
• Register matcher for Node.ELEMENT_NODE with nodeName 'IMG' selector
• Implement matcher function that extracts src, alt, and other image attributes from img node
• Return Delta with image embed operation: new Delta().insert({ image: src }, { alt: altText }) instead of allowing default text conversion
• Preserve any existing image attributes supported by CustomImage blot (reference the ATTRIBUTES array in packages/fluent-editor/src/modules/custom-image/image.ts)

🤖 Prompt for AI agents

Register a custom clipboard matcher for IMG elements to convert them to proper
Delta image embeds during HTML-to-Delta conversion.

Add a constructor to CustomClipboard class in
`packages/fluent-editor/src/modules/custom-clipboard.ts`:
- Call `this.addMatcher()` to register image handler for Node.ELEMENT_NODE with
nodeName 'IMG'
- Extract src, alt, and other supported attributes from img node
- Return `new Delta().insert({ image: src }, { alt: altText })` to create proper
image embed
- Preserve attributes supported by CustomImage blot (reference ATTRIBUTES in
`packages/fluent-editor/src/modules/custom-image/image.ts`)

Phase 2: Update Image Processing Pipeline

Adjust the existing image extraction and replacement logic to work with properly formatted image embeds from the matcher instead of text placeholders.

Task 1: Verify extractFilesFromDelta Compatibility

Ensure the image extraction logic correctly processes image embeds created by the custom matcher

• Review extractFilesFromDelta() method in packages/fluent-editor/src/modules/custom-clipboard.ts to confirm it correctly identifies op.insert.image operations from the matcher
• Verify the method properly handles image operations that already have src values (from matcher) vs. those needing hex/file conversion (from RTF)
• Ensure the placeholder mechanism in flipFilesArray() correctly tracks image positions when embeds come from the matcher

Task 2: Update replaceDeltaImage Logic

Modify image replacement to handle properly structured image embeds

• Review replaceDeltaImage() method in packages/fluent-editor/src/modules/custom-clipboard.ts to ensure it correctly updates image src values in embed operations
• Verify that image attributes (alt, title) from the matcher are preserved when URLs are replaced
• Confirm the method handles the case where image embeds from the matcher already have valid src values and may not need replacement

🤖 Prompt for AI agents

Verify and update the image processing pipeline to handle properly formatted
image embeds from the custom matcher.

In `packages/fluent-editor/src/modules/custom-clipboard.ts`:
- Review `extractFilesFromDelta()` to confirm it correctly identifies
`op.insert.image` operations from matcher
- Verify it handles both images with src values (from matcher) and those needing
hex/file conversion (from RTF)
- Ensure placeholder mechanism in `flipFilesArray()` tracks image positions
correctly
- Review `replaceDeltaImage()` to ensure it updates image src values in embed
operations
- Verify image attributes (alt, title) are preserved during URL replacement
- Confirm handling of images that already have valid src values

Phase 3: Fix Cursor Positioning After Paste

Update cursor position calculation to correctly account for image embeds rather than text placeholders, ensuring cursor lands at the end of pasted content.

Adjust Cursor Position Calculation

Correct the cursor positioning logic to account for image embeds vs. text length

• Review the cursor position calculation in handlePasteContent() callback in packages/fluent-editor/src/modules/custom-clipboard.ts (lines 162-168)
• Verify the calculation delta.length() - linePos.length - linePos.fix correctly accounts for image embeds (which have length 1 in Delta operations)
• Test that cursor positioning works correctly when the pasted Delta contains only text, only images, or mixed content
• Ensure the setSelection() call places cursor after all inserted content including trailing images

🤖 Prompt for AI agents

Fix cursor positioning after paste to correctly account for image embeds.

In `packages/fluent-editor/src/modules/custom-clipboard.ts`, review the cursor
position calculation in `handlePasteContent()` callback:
- Verify `delta.length() - linePos.length - linePos.fix` correctly accounts for
image embeds (length 1 in Delta)
- Ensure cursor positioning works for text-only, image-only, and mixed content
- Confirm `setSelection()` places cursor after all inserted content including
trailing images

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Register a custom clipboard matcher for IMG elements to convert them to proper
Delta image embeds during HTML-to-Delta conversion.

Add a constructor to CustomClipboard class in
`packages/fluent-editor/src/modules/custom-clipboard.ts`:
- Call `this.addMatcher()` to register image handler for Node.ELEMENT_NODE with
nodeName 'IMG'
- Extract src, alt, and other supported attributes from img node
- Return `new Delta().insert({ image: src }, { alt: altText })` to create proper
image embed
- Preserve attributes supported by CustomImage blot (reference ATTRIBUTES in
`packages/fluent-editor/src/modules/custom-image/image.ts`)
===============================================================================

Task: 2

Verify and update the image processing pipeline to handle properly formatted
image embeds from the custom matcher.

In `packages/fluent-editor/src/modules/custom-clipboard.ts`:
- Review `extractFilesFromDelta()` to confirm it correctly identifies
`op.insert.image` operations from matcher
- Verify it handles both images with src values (from matcher) and those needing
hex/file conversion (from RTF)
- Ensure placeholder mechanism in `flipFilesArray()` tracks image positions
correctly
- Review `replaceDeltaImage()` to ensure it updates image src values in embed
operations
- Verify image attributes (alt, title) are preserved during URL replacement
- Confirm handling of images that already have valid src values
===============================================================================

Task: 3

Fix cursor positioning after paste to correctly account for image embeds.

In `packages/fluent-editor/src/modules/custom-clipboard.ts`, review the cursor
position calculation in `handlePasteContent()` callback:
- Verify `delta.length() - linePos.length - linePos.fix` correctly accounts for
image embeds (length 1 in Delta)
- Ensure cursor positioning works for text-only, image-only, and mixed content
- Confirm `setSelection()` places cursor after all inserted content including
trailing images

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!