Metadata-Version: 2.5
Name: reflex-qicheng-docedit
Version: 0.2.0
Summary: Feishu-style block document editor for Reflex (personal package by qicheng)
Requires-Python: >=3.10
Requires-Dist: reflex>=0.9.0
Description-Content-Type: text/markdown

# reflex-qicheng-docedit

飞书风块文档编辑器，自用 Reflex 组件包（作者：qicheng）。底层基于 [TipTap](https://tiptap.dev) 实现。

## 安装 / 运行 demo

```bash
pip install -e .
reflex run
```

## 使用

```python
import reflex as rx
from reflex_qicheng_docedit import doc_edit


class State(rx.State):
    content: str = "<p></p>"
    revision: int = 0

    @rx.event
    def on_change(self, html: str):
        self.content = html  # 日常编辑不要改 revision


def index():
    return doc_edit(
        content=State.content,
        revision=State.revision,
        on_change=State.on_change,
        height="70vh",
    )


app = rx.App()
app.add_page(index)
```

仅在需要从 Python 强制重载编辑器内容时，才递增 `revision`。

## 选区 AI

在 `rxconfig.py` 里挂上插件后，选区工具栏会出现 AI 菜单（纠错、扩写、解释、中英翻译、自定义提示词）。密钥只留在服务端。未配置插件时不显示按钮。解释会在编辑器右侧打开对话，可以围绕选中文字连续追问；某条回答可以插到选区后面，原文保留。其余动作仍是先预览，接受后才替换选区。

```python
import os
import reflex as rx
from reflex_qicheng_docedit import DocEditAiPlugin

config = rx.Config(
    app_name="my_app",
    plugins=[
        DocEditAiPlugin(
            api_key=os.environ["DOC_EDIT_AI_API_KEY"],
            base_url=os.environ.get("DOC_EDIT_AI_BASE_URL", "https://api.openai.com/v1"),
            model=os.environ.get("DOC_EDIT_AI_MODEL", "gpt-4o-mini"),
        ),
    ],
)
```

页面把选区请求交给 `complete_doc_ai`，再把同一次 `request_id` 的结果传回编辑器。纠错、扩写、翻译和自定义提示词先给出预览，接受后才替换选区。解释把追问放在 `option` 的 JSON 里（`question` 与 `history`），由编辑器自己维持对话。

```python
from reflex_qicheng_docedit import DocEditAiError, complete_doc_ai, doc_edit

class State(rx.State):
    content: str = "<p></p>"
    revision: int = 0
    ai_request_id: str = ""
    ai_preview: str = ""
    ai_error: str = ""

    @rx.event
    def on_change(self, html: str):
        self.content = html

    @rx.event
    async def on_ai_request(self, request_id: str, action: str, text: str, option: str):
        try:
            preview = await complete_doc_ai(action, text, option)
        except DocEditAiError as exc:
            self.ai_request_id = request_id
            self.ai_preview = ""
            self.ai_error = str(exc)
            return
        self.ai_request_id = request_id
        self.ai_preview = preview
        self.ai_error = ""

def index():
    return doc_edit(
        content=State.content,
        revision=State.revision,
        on_change=State.on_change,
        on_ai_request=State.on_ai_request,
        ai_request_id=State.ai_request_id,
        ai_preview=State.ai_preview,
        ai_error=State.ai_error,
    )
```

## 包结构

```
reflex_qicheng_docedit/
  editor.jsx              # 编辑器入口
  panels/
    insertMenu.jsx        # 「+」/「/」边栏
    blockGutter.jsx       # 块边栏（拖拽 / 高亮）
    selectionToolbar.jsx  # 选区浮动工具栏
    basic.jsx             # 基础插入
    table.jsx             # 表格
    task.jsx              # 任务
    media.jsx             # 图片 / 视频
    imageExt.jsx          # 图片节点扩展
    highlightBlockExt.jsx # 高亮块
    shared.jsx            # 共用组件
```
