feat(docs): add bilingual package documentation site
This commit is contained in:
Maofeng
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: 定义 Action
|
||||
description: 在保留自动依赖收集能力的同时添加产品专属行为。
|
||||
order: 20
|
||||
toc:
|
||||
- id: declare-the-action
|
||||
title: 声明 Action
|
||||
- id: custom-control
|
||||
title: 自定义控件
|
||||
- id: typed-values
|
||||
title: 类型化参数
|
||||
---
|
||||
|
||||
## 声明 Action {#declare-the-action}
|
||||
|
||||
将命令与其编辑器依赖放在同一个定义中：
|
||||
|
||||
```tsx
|
||||
const Mention = defineLexicalAction({
|
||||
name: "mention",
|
||||
label: "插入提及",
|
||||
nodes: [MentionNode],
|
||||
plugins: [MentionPopoverPlugin],
|
||||
execute: ({ editor }) => openMentionPicker(editor),
|
||||
})
|
||||
```
|
||||
|
||||
只要 `<Mention />` 出现在 `LexicalActions` 内，它需要的节点和插件就会自动启用。
|
||||
|
||||
## 自定义控件 {#custom-control}
|
||||
|
||||
```tsx
|
||||
<Mention>
|
||||
{({ disabled, execute }) => (
|
||||
<MentionButton disabled={disabled} onSelect={execute} />
|
||||
)}
|
||||
</Mention>
|
||||
```
|
||||
|
||||
替换可见控件不会改变依赖收集结果。
|
||||
|
||||
## 类型化参数 {#typed-values}
|
||||
|
||||
渲染上下文会公开带有 Action 参数类型的 `execute(value?)`。普通按钮可以使用无参数快捷方式 `onClick`。
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: 编辑器本地化
|
||||
description: 将内置标签和自定义 Actions 接入工作区国际化运行时。
|
||||
order: 21
|
||||
toc:
|
||||
- id: add-the-catalog
|
||||
title: 添加词典
|
||||
- id: fallback
|
||||
title: 回退行为
|
||||
- id: custom-labels
|
||||
title: 自定义标签
|
||||
---
|
||||
|
||||
## 添加词典 {#add-the-catalog}
|
||||
|
||||
```json
|
||||
{
|
||||
"catalogSources": ["@workspace/lexical/locales/{locale}"]
|
||||
}
|
||||
```
|
||||
|
||||
该包提供简体中文（`zh-Hans`）和美式英语（`en-US`）编辑器词典。
|
||||
|
||||
## 回退行为 {#fallback}
|
||||
|
||||
内置控件跟随当前 `@workspace/i18n` Provider。在 Provider 外部会回退为英文，使编辑器在独立预览和测试中仍可使用。
|
||||
|
||||
## 自定义标签 {#custom-labels}
|
||||
|
||||
外部 Action 标签可以是普通字符串，也可以是包含 `id` 和 `message` 的消息描述符。描述符会参与和应用文案相同的提取流程。
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: 添加媒体
|
||||
description: 插入已上传媒体，并处理粘贴或拖入编辑器的图片。
|
||||
order: 30
|
||||
toc:
|
||||
- id: image-and-video
|
||||
title: 图片和视频
|
||||
- id: clipboard-images
|
||||
title: 剪贴板图片
|
||||
- id: editing-media
|
||||
title: 编辑媒体
|
||||
---
|
||||
|
||||
## 图片和视频 {#image-and-video}
|
||||
|
||||
默认的 `Image` 和 `Video` Actions 会打开内置输入对话框。自定义上传器可以把完成后的数据直接交给 Action：
|
||||
|
||||
```tsx
|
||||
<Image>
|
||||
{({ execute }) => (
|
||||
<ImageUploader
|
||||
onUploaded={({ src, alt, caption }) => execute({ src, alt, caption })}
|
||||
/>
|
||||
)}
|
||||
</Image>
|
||||
```
|
||||
|
||||
## 剪贴板图片 {#clipboard-images}
|
||||
|
||||
完整预设包含 `ClipboardImages`。生产环境应通过对象存储解析粘贴和拖放的文件：
|
||||
|
||||
```tsx
|
||||
<ClipboardImages
|
||||
resolveImage={async (file, { reportProgress, signal }) => {
|
||||
const uploaded = await uploadImage(file, {
|
||||
signal,
|
||||
onProgress: reportProgress,
|
||||
})
|
||||
return { alt: file.name, src: uploaded.url }
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
## 编辑媒体 {#editing-media}
|
||||
|
||||
选中的图片支持调整尺寸、编辑说明、对齐，以及可见按钮或键盘删除。非图片剪贴板文件继续交由浏览器的默认行为处理。
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: 编排操作
|
||||
description: 用显式 Actions 替换预设，并将控件放入正确的编辑区域。
|
||||
order: 11
|
||||
toc:
|
||||
- id: explicit-actions
|
||||
title: 显式 Actions
|
||||
- id: placement
|
||||
title: 放置位置
|
||||
- id: action-groups
|
||||
title: Action 分组
|
||||
---
|
||||
|
||||
## 显式 Actions {#explicit-actions}
|
||||
|
||||
当产品需要精确控制功能和顺序时，将预设切换为子元素：
|
||||
|
||||
```tsx
|
||||
<LexicalActions>
|
||||
<Undo />
|
||||
<Redo />
|
||||
<Bold />
|
||||
<Italic />
|
||||
<Link />
|
||||
</LexicalActions>
|
||||
```
|
||||
|
||||
## 放置位置 {#placement}
|
||||
|
||||
Actions 默认显示在固定工具栏中。`in` 属性接受一个或多个区域：
|
||||
|
||||
```tsx
|
||||
<Bold in={["toolbar", "bubble"]} />
|
||||
<Date in="bubble" />
|
||||
<ClearFormatting in="footer" />
|
||||
```
|
||||
|
||||
隐藏 Action 可以提供编辑器行为而不渲染控件，`DraggableBlocks` 就使用了这种模式。
|
||||
|
||||
## Action 分组 {#action-groups}
|
||||
|
||||
`ActionGroup` 可以是逻辑分组，也可以是可见菜单。普通文本、标题、引用和列表样式等相互关联的选择适合放入菜单。
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: 创建编辑器
|
||||
description: 渲染根节点、内容区域、工具栏和完整的默认 Action 集合。
|
||||
order: 10
|
||||
toc:
|
||||
- id: styles
|
||||
title: 样式
|
||||
- id: editor-structure
|
||||
title: 编辑器结构
|
||||
- id: presets
|
||||
title: 预设
|
||||
---
|
||||
|
||||
## 样式 {#styles}
|
||||
|
||||
在应用中导入一次编辑器样式：
|
||||
|
||||
```ts
|
||||
import "@workspace/lexical/globals.css"
|
||||
```
|
||||
|
||||
## 编辑器结构 {#editor-structure}
|
||||
|
||||
```tsx
|
||||
import {
|
||||
LexicalActions,
|
||||
LexicalBubbleToolbar,
|
||||
LexicalContent,
|
||||
LexicalFixedToolbar,
|
||||
LexicalFooter,
|
||||
LexicalRoot,
|
||||
} from "@workspace/lexical"
|
||||
|
||||
;<LexicalRoot value="" onChange={setHtml}>
|
||||
<LexicalActions useDefaults="full" />
|
||||
<LexicalFixedToolbar />
|
||||
<LexicalContent placeholder="开始输入…" />
|
||||
<LexicalBubbleToolbar />
|
||||
<LexicalFooter />
|
||||
</LexicalRoot>
|
||||
```
|
||||
|
||||
当某个区域没有 Actions 或自定义子元素时，对应工具栏和 Footer 不会渲染 DOM。
|
||||
|
||||
## 预设 {#presets}
|
||||
|
||||
基础文本编辑选择 `minimal`，完整内置功能选择 `full`。预设模式有意不接受手动 Action 子元素。
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 概览
|
||||
description: 在组装完整编辑界面之前，先理解编辑器的声明式 Action 模型。
|
||||
order: 1
|
||||
toc:
|
||||
- id: mental-model
|
||||
title: 心智模型
|
||||
- id: tutorial-map
|
||||
title: 教程路线
|
||||
- id: stable-capabilities
|
||||
title: 稳定的能力集合
|
||||
---
|
||||
|
||||
## 心智模型 {#mental-model}
|
||||
|
||||
`@workspace/lexical` 将编辑器操作视为声明。每个 Action 描述自身行为及其需要的节点、插件或嵌入内容。`LexicalRoot` 会在创建编辑器前收集这些依赖。
|
||||
|
||||
工具栏只决定 Action 出现的位置，不负责单独注册编辑器能力。
|
||||
|
||||
## 教程路线 {#tutorial-map}
|
||||
|
||||
你将创建根节点和内容区域、选择预设、自定义 Action 位置、定义应用专属 Action、添加媒体上传，最后接入本地化标签。
|
||||
|
||||
## 稳定的能力集合 {#stable-capabilities}
|
||||
|
||||
编辑器实例创建后，其 Actions、节点和插件保持固定。当应用需要替换整套能力时，请为 `LexicalRoot` 提供新的 React `key`。
|
||||
Reference in New Issue
Block a user