# `@workspace/lexical`

基于 Lexical 的声明式富文本编辑器。编辑器能力由
`<LexicalActions />` 中出现的 action 组件决定；action 同时声明自己依赖的
node、plugin 和 embed，`<LexicalRoot />` 会在创建 Composer 前自动收集并去重。

## 使用预设

`useDefaults` 提供 `minimal` 和 `full` 两套预设。使用预设时不再接收
`children`，避免默认 action 与手动 action 的优先级不明确。

```tsx
import {
  LexicalActions,
  LexicalBubbleToolbar,
  LexicalContent,
  LexicalFixedToolbar,
  LexicalFooter,
  LexicalRoot,
} from "@workspace/lexical"

export function Editor() {
  return (
    <LexicalRoot value="" onChange={(html) => console.log(html)}>
      <LexicalActions useDefaults="full" />
      <LexicalFixedToolbar />
      <LexicalContent placeholder="开始输入…" />
      <LexicalBubbleToolbar />
      <LexicalFooter />
    </LexicalRoot>
  )
}
```

`LexicalFixedToolbar`、`LexicalBubbleToolbar` 和 `LexicalFooter` 都是可选的。
当对应区域没有 action，也没有自定义 children 时，组件不会产生 DOM。
action、node 与 plugin 会在编辑器首次挂载时确定；需要切换整套能力时，应为
`LexicalRoot` 提供新的 `key` 以重新创建编辑器。

## 国际化

内置控件会使用 `@workspace/i18n` 的当前语言；包提供英文与简体中文 catalog。
应用应将对应 locale source 加入自己的 `i18n.config.json`：

```json
{
  "catalogSources": ["@workspace/lexical/locales/{locale}"]
}
```

未置于 `I18nProvider` 内时，编辑器会回退到英文。外部 action 的 `label`
仍可直接传字符串，也可以传 `{ id, message }` 消息描述符。

## 自定义 action 布局

action 默认显示在固定工具栏。通过 `in` 可以指定单个区域或多个区域；
`ActionGroup` 可以只做普通组合，也可以渲染成下拉菜单。

```tsx
import {
  ActionGroup,
  Bold,
  BulletList,
  CheckList,
  ClearFormatting,
  Date,
  Heading,
  LexicalActions,
  NormalText,
  OrderedList,
  Quote,
  Redo,
  Undo,
} from "@workspace/lexical"

;<LexicalActions>
  <Undo />
  <Redo />

  <ActionGroup type="menu" label="段落样式" showActiveAction>
    <NormalText />
    <Heading level={1} />
    <Heading level={2} />
    <Heading level={3} />
    <OrderedList />
    <BulletList />
    <CheckList />
    <Quote />
  </ActionGroup>

  <Bold in={["toolbar", "bubble"]} />
  <Date in="bubble" />
  <ClearFormatting in="footer" />
</LexicalActions>
```

## 定义扩展 action

外部 action 把行为和 Composer 依赖放在同一份定义中，不需要额外注册
feature。只要 action 出现在 `LexicalActions` 中，它声明的 node 和 plugin
就会自动启用。

```tsx
import {
  defineLexicalAction,
  type LexicalActionDefinition,
} from "@workspace/lexical"

const mentionAction: LexicalActionDefinition = {
  name: "mention",
  label: "插入提及",
  nodes: [MentionNode],
  plugins: [MentionPopoverPlugin],
  execute: ({ editor }) => openMentionPicker(editor),
}

export const Mention = defineLexicalAction(mentionAction)
```

action 组件可以用 render function 替换默认控件，但依赖收集仍由同一个
action 完成：

```tsx
<Mention>
  {({ disabled, execute }) => (
    <CustomMentionButton
      disabled={disabled}
      onSelect={(mention) => execute(mention)}
    />
  )}
</Mention>
```

render context 中的 `execute(value?)` 会调用该 action，并保留 value 类型。
`onClick` 是 `execute()` 的无参快捷方式，适合普通按钮。

图片和视频 action 在不传 value 时继续使用内置输入弹窗；自定义上传器可以
在上传结束后直接把结果交给 `execute`，不需要操作 Lexical editor：

```tsx
<Image>
  {({ execute }) => (
    <ImageUploader
      onUploaded={({ src, alt, caption }) =>
        execute({ src, alt, caption })
      }
    />
  )}
</Image>

<Video>
  {({ execute }) => (
    <VideoUploader
      onUploaded={({ src, poster, caption }) =>
        execute({ src, poster, caption })
      }
    />
  )}
</Video>
```

## 粘贴图片

`full` 预设已包含 `<ClipboardImages />`：直接粘贴截图或拖入图片文件时，
会立即插入本地预览；默认完成后把图片编码成可序列化的 `data:` URL。
生产环境通常更适合传入 `resolveImage`，先把图片上传到对象存储，再返回
持久 URL。上传期间可通过 `reportProgress` 汇报 `0` 到 `1` 的进度；不汇报
时编辑器会显示不确定进度：

```tsx
import { ClipboardImages, LexicalActions } from "@workspace/lexical"

;<LexicalActions>
  {/* 其他 action */}
  <ClipboardImages
    resolveImage={async (file, { reportProgress, signal }) => {
      const uploaded = await uploadImage(file, {
        signal,
        onProgress: reportProgress,
      })
      return {
        alt: file.name,
        src: uploaded.url,
      }
    }}
    onError={(error, file) => reportUploadError(error, file)}
  />
</LexicalActions>
```

非图片文件不会被编辑器接管，粘贴仍由浏览器处理。图片被选中后可以通过
控制点缩放、添加或修改说明、切换左/中/右对齐，也可以使用可见删除按钮、
Delete 或 Backspace 删除。该能力同时复用 Lexical 的文件拖放命令，因此
相同 resolver 也适用于拖入编辑器的图片。

没有可见控件、只提供编辑行为的能力也可以声明为 `hidden` action。包内的
`<DraggableBlocks />` 就使用这种方式，因此它会启用拖拽 plugin，但不会占据
任何工具栏位置。