514 lines
10 KiB
Markdown
514 lines
10 KiB
Markdown
# 工具栏配置
|
||
|
||
引入工具栏
|
||
|
||
```ts
|
||
//vue3 请使用 @aomao/toolbar-vue
|
||
//vue2 请使用 am-editor-toolbar-vue2
|
||
import Toolbar, { ToolbarPlugin, ToolbarComponent } from '@aomao/toolbar';
|
||
```
|
||
|
||
- Toolbar 工具栏组件
|
||
- ToolbarPlugin 提供给引擎的插件
|
||
- ToolbarComponent 提供给引擎的卡片组件
|
||
|
||
除了 `Toolbar` 组件，后两者都是实现在编辑器按下 `/` 出现工具栏卡片插件选项的快捷方式
|
||
|
||
## 类型
|
||
|
||
工具栏现在有四种展现方式
|
||
|
||
- `button` 按钮
|
||
- `downdrop` 下拉框
|
||
- `color` 颜色板
|
||
- `collapse` 下拉面板，工具栏的第一个按钮出现的下拉框，卡片形式的组件基本上都放在这里
|
||
|
||
## 属性
|
||
|
||
Toolbar 组件需要传入的属性：
|
||
|
||
- `editor` 编辑器实例，可以用于自动调用插件执行
|
||
- `items` 插件展示配置列表
|
||
|
||
## 配置项
|
||
|
||
items 是一个二维数组，我们可以把相同概念的插件放在一个组里面，便于寻找。渲染出来后，每个组都会有分割线分开
|
||
|
||
```ts
|
||
items: [['collapse'], ['bold', 'italic']];
|
||
```
|
||
|
||
在 Toolbar 组件里面已经配置好了现有插件的所有展现形式，我们可以直接传入插件名称使用这些配置。当然，我们也可以传入一个对象覆盖部分配置
|
||
|
||
```ts
|
||
items: [
|
||
['collapse'],
|
||
[
|
||
{
|
||
name: 'bold',
|
||
icon: '图标',
|
||
title: '提示文字',
|
||
},
|
||
'italic',
|
||
],
|
||
];
|
||
```
|
||
|
||
如果通过 `name` 属性找到了默认配置，那么 `type` 属性是不会被覆盖的。如果配置的`name`不属于默认配置的一部分，就按照自定义按钮处理
|
||
|
||
## Collapse
|
||
|
||
通常用于配置卡片下拉框
|
||
|
||
需要指定 `type` 为 `collapse`
|
||
|
||
### className
|
||
|
||
自定义样式名称
|
||
|
||
### icon
|
||
|
||
可选
|
||
|
||
按钮图标，可以是 React 组件，在 Vue 中也可以是一段字符串的 html
|
||
|
||
### content
|
||
|
||
可选
|
||
|
||
按钮显示内容，会与 icon 一起显示
|
||
|
||
可以是 React 组件，在 Vue 中也可以是一段字符串的 html。或者是一个方法，并且返回 React 组件或者 html 字符串
|
||
|
||
### onSelect
|
||
|
||
列表项选中事件，返回 `false` 不会执行列表项配置的默认命令
|
||
|
||
```ts
|
||
onSelect?: (event: React.MouseEvent, name: string) => void | boolean;
|
||
```
|
||
|
||
### groups
|
||
|
||
分组显示
|
||
|
||
通过 `groups` 属性可以设置按需要把不同用途的卡片分类
|
||
|
||
不填写 `title` 将不会出现分组样式
|
||
|
||
```ts
|
||
// 显示分组信息
|
||
items: [
|
||
[
|
||
{
|
||
type: 'collapse',
|
||
groups: [
|
||
{
|
||
title: '文件',
|
||
items: ['image-uploader', 'file-uploader'],
|
||
},
|
||
],
|
||
},
|
||
],
|
||
];
|
||
|
||
// or 不显示分组信息
|
||
|
||
items: [
|
||
[
|
||
{
|
||
type: 'collapse',
|
||
groups: [
|
||
{
|
||
items: ['bold', 'underline'],
|
||
},
|
||
],
|
||
},
|
||
],
|
||
];
|
||
```
|
||
|
||
### items
|
||
|
||
配置 `collapse` 的 `items`
|
||
|
||
默认情况下已经配置了以下卡片
|
||
|
||
```ts
|
||
'image-uploader',
|
||
'codeblock',
|
||
'table',
|
||
'file-uploader',
|
||
'video-uploader',
|
||
'math',
|
||
'status',
|
||
```
|
||
|
||
我们可以指定 `name` 为已存在的卡片名称，并且配置其它选项覆盖默认配置。
|
||
|
||
当然我们也可以指定其它名称，完成自定义`item`
|
||
|
||
```ts
|
||
items: [
|
||
[
|
||
{
|
||
type: 'collapse',
|
||
groups: [
|
||
{
|
||
items: [{ name: 'codeblock', content: '我是CodeBlock' }],
|
||
},
|
||
],
|
||
},
|
||
],
|
||
];
|
||
```
|
||
|
||
基本属性与 `button` 属性一样，可以在文章以下部分查看，这里列出了相对于 `button` 外的特殊属性
|
||
|
||
#### search
|
||
|
||
查询字符，在工具栏插件中我们可以使用 `/` 在编辑器唤出快捷选项，并且可以搜索相关卡片，所以这里可以指定相关关键字字符组合
|
||
|
||
#### description
|
||
|
||
列表项描述，可以返回一个 `React` 组件，或者 `Vue` 可以返回 `html` 字符串
|
||
|
||
#### prompt
|
||
|
||
鼠标移入到列表项时需要渲染的内容，可以返回一个 `React` 组件，或者 `Vue` 可以返回 `html` 字符串
|
||
|
||
效果类似于 `table` 卡片项，输入移入后展示一个选择列和行数的表格
|
||
|
||
#### onClick
|
||
|
||
列表项单击事件，返回 `false` 将不会执行配置的默认命令
|
||
|
||
```ts
|
||
onClick?: (event: React.MouseEvent, name: string) => void | boolean;
|
||
```
|
||
|
||
## Button
|
||
|
||
button 配置属性
|
||
|
||
在工具栏 items 里面配置，需要指定 `type` 为 `button`
|
||
|
||
```ts
|
||
items:[
|
||
[
|
||
{
|
||
type: 'button',
|
||
name: 'test',
|
||
...
|
||
}
|
||
]
|
||
]
|
||
```
|
||
|
||
### name
|
||
|
||
按钮名称
|
||
|
||
如果按钮名称与工具栏默认配置项名称相同，那么会覆盖默认已有配置，否则将作为自定义按钮
|
||
|
||
### icon
|
||
|
||
可选
|
||
|
||
按钮图标，可以是 React 组件，在 Vue 中也可以是一段字符串的 html
|
||
|
||
### content
|
||
|
||
可选
|
||
|
||
按钮显示内容，会与 icon 一起显示
|
||
|
||
可以是 React 组件，在 Vue 中也可以是一段字符串的 html。或者是一个方法，并且返回 React 组件或者 html 字符串
|
||
|
||
### title
|
||
|
||
鼠标移入按钮时显示的提示信息
|
||
|
||
### placement
|
||
|
||
设置提示信息的位置
|
||
|
||
```ts
|
||
placement?:
|
||
| 'right'
|
||
| 'top'
|
||
| 'left'
|
||
| 'bottom'
|
||
| 'topLeft'
|
||
| 'topRight'
|
||
| 'bottomLeft'
|
||
| 'bottomRight'
|
||
| 'leftTop'
|
||
| 'leftBottom'
|
||
| 'rightTop'
|
||
| 'rightBottom';
|
||
```
|
||
|
||
### hotkey
|
||
|
||
是否显示热键，或者设置热键的信息
|
||
|
||
默认为显示热键到提示信息（`title`），并且通过 `name` 信息找到插件设置的热键
|
||
|
||
```ts
|
||
hotkey?: boolean | string;
|
||
```
|
||
|
||
### autoExecute
|
||
|
||
按钮单击时，是否自动执行插件命令，默认启用
|
||
|
||
### command
|
||
|
||
插件命令或参数
|
||
|
||
如果有配置此参数，并且 `autoExecute` 属性为启用状态，在按钮单击时，调用此配置执行插件命令
|
||
|
||
如果有配置 `name` 就执行`name` 对应的插件，否则就执行 `button` 指定的 `name` 对应的插件
|
||
|
||
如果有配置 `args` 或者 `command` 为纯数组，会作为参数传入执行插件的命令
|
||
|
||
```ts
|
||
command?: { name: string; args: Array<any> } | Array<any>;
|
||
```
|
||
|
||
### className
|
||
|
||
为按钮配置样式名称
|
||
|
||
### onClick
|
||
|
||
鼠标单击事件
|
||
|
||
如果返回 `false` 将不会自动执行插件命令
|
||
|
||
```ts
|
||
onClick?: (event: React.MouseEvent) => void | boolean;
|
||
```
|
||
|
||
### onMouseDown
|
||
|
||
鼠标按下按钮事件
|
||
|
||
```ts
|
||
onMouseDown?: (event: React.MouseEvent) => void;
|
||
```
|
||
|
||
### onMouseEnter
|
||
|
||
鼠标移入按钮事件
|
||
|
||
```ts
|
||
onMouseEnter?: (event: React.MouseEvent) => void;
|
||
```
|
||
|
||
### onMouseLeave
|
||
|
||
鼠标移开按钮事件
|
||
|
||
```ts
|
||
onMouseLeave?: (event: React.MouseEvent) => void;
|
||
```
|
||
|
||
### onActive
|
||
|
||
自定义按钮激活选中，默认调用插件 `engine.command.queryState` 方法
|
||
|
||
```ts
|
||
onActive?: () => boolean;
|
||
```
|
||
|
||
### onDisabled
|
||
|
||
自定义按钮禁用，默认调用插件 `engine.command.queryEnabled`
|
||
|
||
```ts
|
||
onDisabled?: () => boolean;
|
||
```
|
||
|
||
## Dropdown
|
||
|
||
dropdown 配置属性
|
||
|
||
在工具栏 items 里面配置，需要指定 `type` 为 `dropdown`
|
||
|
||
```ts
|
||
items:[
|
||
[
|
||
{
|
||
type: 'dropdown',
|
||
name: 'test',
|
||
items: [
|
||
{
|
||
key: 'item1',
|
||
content: 'item1'
|
||
}
|
||
]
|
||
...
|
||
}
|
||
]
|
||
]
|
||
```
|
||
|
||
### items
|
||
|
||
下拉列表项，与按钮类似
|
||
|
||
```ts
|
||
items:[{
|
||
key: string;
|
||
icon?: React.ReactNode;
|
||
content?: React.ReactNode | (() => React.ReactNode);
|
||
hotkey?: boolean | string;
|
||
isDefault?: boolean;
|
||
title?: string;
|
||
placement?:
|
||
| 'right'
|
||
| 'top'
|
||
| 'left'
|
||
| 'bottom'
|
||
| 'topLeft'
|
||
| 'topRight'
|
||
| 'bottomLeft'
|
||
| 'bottomRight'
|
||
| 'leftTop'
|
||
| 'leftBottom'
|
||
| 'rightTop'
|
||
| 'rightBottom';
|
||
className?: string;
|
||
disabled?: boolean;
|
||
command?: { name: string; args: Array<any> } | Array<any>;
|
||
autoExecute?: boolean;
|
||
}]
|
||
```
|
||
|
||
### name
|
||
|
||
下拉列表名称
|
||
|
||
如果名称与工具栏默认配置项名称相同，那么会覆盖默认已有配置，否则将作为自定义下拉列表
|
||
|
||
### icon
|
||
|
||
可选
|
||
|
||
按钮图标，可以是 React 组件，在 Vue 中也可以是一段字符串的 html
|
||
|
||
### content
|
||
|
||
可选
|
||
|
||
按钮显示内容，会与 icon 一起显示
|
||
|
||
可以是 React 组件，在 Vue 中也可以是一段字符串的 html。或者是一个方法，并且返回 React 组件或者 html 字符串
|
||
|
||
### title
|
||
|
||
鼠标移入按钮时显示的提示信息
|
||
|
||
### values
|
||
|
||
下拉列表选中值，默认通过 `engine.command.queryState` 获取，如果有配置 `onActive` 将会从自定义 `onActive` 中获取值
|
||
|
||
```ts
|
||
values?: string | Array<string>;
|
||
```
|
||
|
||
### single
|
||
|
||
单选还是可以多选
|
||
|
||
```ts
|
||
single?: boolean;
|
||
```
|
||
|
||
### className
|
||
|
||
下拉列表样式
|
||
|
||
### direction
|
||
|
||
排列方向 `vertical` | `horizontal`
|
||
|
||
```ts
|
||
direction?: 'vertical' | 'horizontal';
|
||
```
|
||
|
||
### onSelect
|
||
|
||
列表项选中事件，返回 `false` 将不自动执行选中项配置的命令
|
||
|
||
```ts
|
||
onSelect?: (event: React.MouseEvent, key: string) => void | boolean;
|
||
```
|
||
|
||
### hasArrow
|
||
|
||
是否显示下拉箭头
|
||
|
||
```ts
|
||
hasArrow?: boolean;
|
||
```
|
||
|
||
### hasDot
|
||
|
||
是否显示选中值后的勾选效果
|
||
|
||
```ts
|
||
hasDot?: boolean;
|
||
```
|
||
|
||
### renderContent
|
||
|
||
自定义渲染下拉列表选中后显示的内容，默认为下拉列表配置的 `icon` 或者 `content`
|
||
|
||
可以返回 React 组件或者 Vue 可以返回 html 字符串
|
||
|
||
```ts
|
||
renderContent?: (item: DropdownListItem) => React.ReactNode;
|
||
```
|
||
|
||
### onActive
|
||
|
||
自定义按钮激活选中，默认调用插件 `engine.command.queryState` 方法
|
||
|
||
```ts
|
||
onActive?: () => boolean;
|
||
```
|
||
|
||
### onDisabled
|
||
|
||
自定义按钮禁用，默认调用插件 `engine.command.queryEnabled`
|
||
|
||
```ts
|
||
onDisabled?: () => boolean;
|
||
```
|
||
|
||
## 所有插件的默认配置
|
||
|
||
```ts
|
||
[
|
||
['collapse'],
|
||
['undo', 'redo', 'paintformat', 'removeformat'],
|
||
['heading', 'fontfamily', 'fontsize'],
|
||
['bold', 'italic', 'strikethrough', 'underline', 'moremark'],
|
||
['fontcolor', 'backcolor'],
|
||
['alignment'],
|
||
['unorderedlist', 'orderedlist', 'tasklist', 'indent', 'line-height'],
|
||
['link', 'quote', 'hr'],
|
||
];
|
||
```
|
||
|
||
这些默认配置详细信息可以在这里找到定义：
|
||
|
||
React: [https://github.com/yanmao-cc/am-editor/blob/master/packages/toolbar/src/config/toolbar/index.tsx](https://github.com/yanmao-cc/am-editor/blob/master/packages/toolbar/src/config/toolbar/index.tsx)
|
||
|
||
Vue3: [https://github.com/yanmao-cc/am-editor/blob/master/packages/toolbar-vue/src/config/index.ts](https://github.com/yanmao-cc/am-editor/blob/master/packages/toolbar-vue/src/config/index.ts)
|
||
|
||
Vue2: [https://github.com/zb201307/am-editor-vue2/blob/main/packages/toolbar/src/config/index.ts](https://github.com/zb201307/am-editor-vue2/blob/main/packages/toolbar/src/config/index.ts)
|