diff --git a/packages/docs/fluent-editor/.vitepress/sidebar.ts b/packages/docs/fluent-editor/.vitepress/sidebar.ts index 0d6529b..ef30bdc 100644 --- a/packages/docs/fluent-editor/.vitepress/sidebar.ts +++ b/packages/docs/fluent-editor/.vitepress/sidebar.ts @@ -35,5 +35,12 @@ export function sidebar() { { text: 'Fluent Editor 类', link: '/docs/api/fluent-editor-class' }, ], }, + { + text: '模块生态', + items: [ + { text: '工具栏提示', link: '/docs/modules/toolbar-tip' }, + { text: '标题列表', link: '/docs/modules/header-list' }, + ], + }, ] } diff --git a/packages/docs/fluent-editor/docs/api/fluent-editor-class.md b/packages/docs/fluent-editor/docs/api/fluent-editor-class.md index 6d32290..655af9c 100644 --- a/packages/docs/fluent-editor/docs/api/fluent-editor-class.md +++ b/packages/docs/fluent-editor/docs/api/fluent-editor-class.md @@ -86,6 +86,6 @@ Quill.register({ Quill.register(CustomFormat) ``` -- 参考[工具栏提示](/docs/toolbar-tip) +- 参考[工具栏提示](/docs/demo/toolbar-tip) -更多静态变量和静态方法请参考 Quill 官方文档:[https://quilljs.com/docs/api](https://quilljs.com/docs/api) +更多静态变量和静态方法请参考 Quill 官方文档:[https://quilljs.com/docs/api](https://quilljs.com/docs/api)。 diff --git a/packages/docs/fluent-editor/docs/api/fluent-editor-instance.md b/packages/docs/fluent-editor/docs/api/fluent-editor-instance.md index 00f2b62..78840f7 100644 --- a/packages/docs/fluent-editor/docs/api/fluent-editor-instance.md +++ b/packages/docs/fluent-editor/docs/api/fluent-editor-instance.md @@ -84,4 +84,4 @@ editor.setContents([ - 参考[内容初始化](/docs/demo/set-content) -更多实例方法请参考 Quill 官方文档:[https://quilljs.com/docs/api](https://quilljs.com/docs/api) +更多实例方法请参考 Quill 官方文档:[https://quilljs.com/docs/api](https://quilljs.com/docs/api)。 diff --git a/packages/docs/fluent-editor/docs/api/options.md b/packages/docs/fluent-editor/docs/api/options.md index 892c693..7a10722 100644 --- a/packages/docs/fluent-editor/docs/api/options.md +++ b/packages/docs/fluent-editor/docs/api/options.md @@ -66,4 +66,4 @@ export interface FluentEditorOptions extends QuillOptions { } ``` -更多配置项请参考 Quill 官方文档:[https://quilljs.com/docs/configuration](https://quilljs.com/docs/configuration) +更多配置项请参考 Quill 官方文档:[https://quilljs.com/docs/configuration](https://quilljs.com/docs/configuration)。 diff --git a/packages/docs/fluent-editor/docs/modules/header-list.md b/packages/docs/fluent-editor/docs/modules/header-list.md new file mode 100644 index 0000000..678e6cc --- /dev/null +++ b/packages/docs/fluent-editor/docs/modules/header-list.md @@ -0,0 +1,72 @@ +# 标题列表 + +在线演示:[标题列表](/docs/demo/header-list)。 + +## 安装 + +```bash +npm install quill-header-list +``` + +## 使用 + +```js +import FluentEditor from '@opentiny/fluent-editor' +import HeaderList from 'quill-header-list' +import 'quill-header-list/dist/index.css' + +FluentEditor.register({ 'modules/header-list': HeaderList }, true) + +new FluentEditor('#editor', { + theme: 'snow', + modules: { + 'toolbar': { + container: [[{ header: [null, 1, 2, 3, 4, 5, 6] }, 'header-list']], + handlers: { + 'header-list': HeaderList.toolbarHandle + } + }, + 'header-list': { + container: document.getElementById('directory'), // 指定一个元素来接收头部列表 + }, + }, +}) +``` + +## options 配置 + +| 名称 | 类型 | 描述 | 默认值 | 是否必选 | +| --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- | +| container | `string \| HTMLElement` | 列表容器,字符串必须是元素的id | - | `true` | +| scrollContainer | `string \| HTMLElement` | 编辑器滚动容器,默认是 `quill.root` | - | `false` | +| hideClass | `number` | 列表隐藏时的类名 | `is-hidden` | `false` | +| topOffset | `number \| () => number` | 从顶部的偏移量(单位为 `px`) | `0` | `false` | +| headerHeight | `number` | 编辑器中的头部高度,这是用于计算头部滚动高亮的,不要使h1和h6之间的高度差过大 | `36` | `false` | +| onBeforeShow | `() => boolean` | 在显示前触发,返回 `true` 将取消显示 | - | `false` | +| onBeforeHide | `() => boolean` | 在隐藏前触发,返回 `true` 将取消隐藏 | - | `false` | +| onItemClick | `(id: string) => void` | 点击列表项时触发,id是头部元素的id | - | `false` | + +## 其他 + +如果你的页面中有一个固定元素,你可以使用`topOffset`来返回该固定元素的高度,这样头部列表项的滚动位置就不会被固定元素遮盖。 + +```js +new FluentEditor('#editor', { + theme: 'snow', + modules: { + 'toolbar': [[{ header: [null, 1, 2, 3, 4, 5, 6] }, 'header-list'],], + 'header-list': { + container: document.getElementById('directory'), // 指定一个元素来接收头部列表 + topOffset: () => { + // 获取固定元素的高度 + const navOffset = document.querySelector('.fixed')?.getBoundingClientRect().height || 0 + return navOffset + }, + // 或者如果你已经知道高度 + // topOffset: 36, + }, + }, +}) +``` + +想了解更多 quill-header-list 模块的使用说明,请参考:[https://github.com/opentiny/quill-header-list](https://github.com/opentiny/quill-header-list)。 diff --git a/packages/docs/fluent-editor/docs/modules/toolbar-tip.md b/packages/docs/fluent-editor/docs/modules/toolbar-tip.md new file mode 100644 index 0000000..5448ff7 --- /dev/null +++ b/packages/docs/fluent-editor/docs/modules/toolbar-tip.md @@ -0,0 +1,201 @@ +# 工具栏提示 + +在线演示:[工具栏提示](/docs/demo/toolbar-tip)。 + +## 安装 + +```bash +npm install quill-toolbar-tip +``` + +## 使用 + +如果你想使用英文文本,你可以使用导出名为 `defaultToolbarTip` 的默认提示文本。 + +```ts +import FluentEditor from "@opentiny/fluent-editor"; +import QuillToolbarTip, { defaultToolbarTip } from "quill-toolbar-tip"; +import "quill-toolbar-tip/dist/index.css"; + +FluentEditor.register( + { + [`modules/${QuillToolbarTip.moduleName}`]: QuillToolbarTip, + }, + true +); + +const QuillToolbarTipOption = { + tipTextMap: defaultToolbarTip["en-US"], +}; + +const editor = new FluentEditor("#editor", { + theme: "snow", + modules: { + toolbar: [ + ["bold", "italic"], + [{ list: "ordered" }, { list: "bullet" }], + [{ script: "sub" }, { script: "super" }], + [{ color: [] }, { background: [] }], + ], + [QuillToolbarTip.moduleName]: QuillToolbarTipOption, + }, +}); +``` + +或者你可以在 `tipTextMap` 中添加文本以在工具提示中显示。键与工具栏格式名称相匹配。 + +```ts +import QuillToolbarTip from "quill-toolbar-tip"; +import "quill-toolbar-tip/dist/index.css"; + +FluentEditor.register( + { + [`modules/${QuillToolbarTip.moduleName}`]: QuillToolbarTip, + }, + true +); + +const QuillToolbarTipOption = { + tipTextMap: { + bold: "Bold", + italic: "Italic", + color: { + onShow(target, value) { + return `Font Color${value ? `: ${value}` : ""}`; + }, + }, + background: { + onShow(target, value) { + return `Background Color${value ? `: ${value}` : ""}`; + }, + }, + }, +}; + +const editor = new FluentEditor("#editor", { + theme: "snow", + modules: { + toolbar: [ + ["bold", "italic"], + [{ list: "ordered" }, { list: "bullet" }], + [{ script: "sub" }, { script: "super" }], + [{ color: [] }, { background: [] }], + ], + [QuillToolbarTip.moduleName]: QuillToolbarTipOption, + }, +}); +``` + +你可以使用 `key:value` 来设置特定的提示。例如,要为项目符号列表设置提示文本“无序列表”,你可以使用 `'list: bullet': 'Unordered List'`。 + +```ts +const QuillToolbarTipOption = { + tipTextMap: { + "list:ordered": "Ordered List", + "list:bullet": "Unordered List", + }, +}; +``` + +你还可以为键设置一个选项,并使用 `onShow` 来计算工具提示的文本。但是,如果你使用了 `onShow` 选项,`msg` / `content` 或字符串值将被忽略。最终显示的文本将是项的值。 + +```ts +const QuillToolbarTipOption = { + tipTextMap: { + script: { + onShow(target, value) { + const text = { + sub: "Subscript", + super: "Superscript", + }; + return text[value] || null; + }, + }, + }, +}; +``` + +## Options 配置 + +| 名称 | 类型 | 描述 | +| --------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | +| defaultTooltipOptions | `Partial` | 默认工具提示选项 | +| tipTextMap | `Record \| string>` | 工具提示文本映射。你也可以设置一个对象,该对象将在工具提示中使用。工具提示选项的配置如下所示: | + +### TooltipOptions 配置 + +| 名称 | 描述 | +| ------------ | ----------------------------------------------------------------------------- | +| direction | 工具提示显示的方向 | +| delay | 工具提示显示和隐藏前的延迟时间,单位为毫秒 | +| msg | 工具提示的消息 | +| content | 工具提示的内容 | +| className | 工具提示的类名 | +| tipHoverable | 当工具提示被悬停时显示工具提示。默认值为 `true` | +| onShow | 工具提示显示时的回调函数。如果 `onShow`返回 `undefined`,则工具提示将不会显示 | + +```ts +interface TooltipOptions { + direction: + | "auto" + | "auto-start" + | "auto-end" + | "top" + | "top-start" + | "top-end" + | "bottom" + | "bottom-start" + | "bottom-end" + | "right" + | "right-start" + | "right-end" + | "left" + | "left-start" + | "left-end"; + msg: string; + delay: number; + content: HTMLElement; + className: string | string[]; + onShow: (target: HTMLElement) => string | HTMLElement | undefined; +} +``` + +`msg` / `content` 和 `onShow` 在同一时间只有一个会生效,优先级顺序为 `onShow` > `content` > `msg`。 + +这意味着如果你设置了如下选项,最终显示的文本将是 'C'。 + +```js +const B = document.createElement("span"); +B.textContent = "B"; + +tipTextMap = { + color: { + msg: "A", + content: B, + onShow() { + return "C"; + }, + }, +}; +``` + +`onShow` 的参数 `value` 是工具栏按钮或选择框的当前值。 + +```ts +interface TooltipItem extends Omit { + onShow: (target: HTMLElement, value: string) => string | HTMLElement; +} +``` + +`defaultTooltipOptions` 如下所示。 + +```ts +const tooltipDefaultOptions = { + msg: "", + delay: 150, + direction: "top", + className: [] as string[], +}; +``` + +想了解更多 quill-toolbar-tip 模块的使用说明,请参考:[https://github.com/opentiny/quill-toolbar-tip](https://github.com/opentiny/quill-toolbar-tip)。