From 35d5bc92ac403fa66c8de5cd049e2afc7fcfeae1 Mon Sep 17 00:00:00 2001 From: "Lucas.Xu" Date: Tue, 16 Aug 2022 18:14:09 +0800 Subject: [PATCH] chore: publish preparation --- .../packages/flowy_editor/.gitignore | 1 + .../app_flowy/packages/flowy_editor/README.md | 19 ++++--- .../packages/flowy_editor/coverage/lcov.info | 0 .../flowy_editor/documentation/node.md | 51 +++++++++++++++++++ .../flowy_editor/lib/flowy_editor.dart | 1 + .../lib/src/service/input_service.dart | 27 +++++++++- .../lib/src/service/keyboard_service.dart | 26 ++++++++++ .../src/service/render_plugin_service.dart | 2 +- .../lib/src/service/scroll_service.dart | 27 ++++++++++ .../lib/src/service/selection_service.dart | 6 +-- 10 files changed, 147 insertions(+), 13 deletions(-) delete mode 100644 frontend/app_flowy/packages/flowy_editor/coverage/lcov.info create mode 100644 frontend/app_flowy/packages/flowy_editor/documentation/node.md diff --git a/frontend/app_flowy/packages/flowy_editor/.gitignore b/frontend/app_flowy/packages/flowy_editor/.gitignore index d920ae6823..7501b909b4 100644 --- a/frontend/app_flowy/packages/flowy_editor/.gitignore +++ b/frontend/app_flowy/packages/flowy_editor/.gitignore @@ -28,3 +28,4 @@ migrate_working_dir/ .dart_tool/ .packages build/ +coverage/ diff --git a/frontend/app_flowy/packages/flowy_editor/README.md b/frontend/app_flowy/packages/flowy_editor/README.md index 1e23b05409..4f104fb3a2 100644 --- a/frontend/app_flowy/packages/flowy_editor/README.md +++ b/frontend/app_flowy/packages/flowy_editor/README.md @@ -15,7 +15,10 @@ and the Flutter guide for

An easily extensible, test-covered rich text editing component for Flutter

-![](documentation/images/example.png) + +
+ +
## Features @@ -77,16 +80,16 @@ flutter run ## Examples * 样式扩展 - * Checkbox text - 展示如何基于已有的富文本组件扩展新的样式， - * Image - 展示如何扩展新的节点，并且渲染 + * [Checkbox Text](https://github.com/LucasXu0/AppFlowy/blob/documentation/flowy_editor/frontend/app_flowy/packages/flowy_editor/lib/src/render/rich_text/checkbox_text.dart) - 展示如何基于已有的富文本组件扩展新的样式， + * [Image](https://github.com/LucasXu0/AppFlowy/blob/documentation/flowy_editor/frontend/app_flowy/packages/flowy_editor/example/lib/plugin/image_node_widget.dart) - 展示如何扩展新的节点，并且渲染 + * 更多请参照 [rich text plugins](https://github.com/LucasXu0/AppFlowy/tree/documentation/flowy_editor/frontend/app_flowy/packages/flowy_editor/lib/src/render/rich_text) * 快捷键扩展 - * BUIS - 展示如何通过快捷键对文字进行加粗/下划线/斜体/加粗 - * 粘贴HTML - 展示如何通过快捷键处理粘贴的样式 + * [BUIS](https://github.com/LucasXu0/AppFlowy/blob/documentation/flowy_editor/frontend/app_flowy/packages/flowy_editor/lib/src/service/internal_key_event_handlers/update_text_style_by_command_x_handler.dart) - 展示如何通过快捷键对文字进行加粗/下划线/斜体/加粗 + * [粘贴HTML](https://github.com/LucasXu0/AppFlowy/blob/documentation/flowy_editor/frontend/app_flowy/packages/flowy_editor/lib/src/service/internal_key_event_handlers/copy_paste_handler.dart) - 展示如何通过快捷键处理粘贴的样式 + * 更多请参照 [internal key event handlers](https://github.com/LucasXu0/AppFlowy/tree/documentation/flowy_editor/frontend/app_flowy/packages/flowy_editor/lib/src/service/internal_key_event_handlers) ## Glossary - - - +我们正在编写更详细的说明，目前使用请查照API文档 ## Contributing Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Please look at [CONTRIBUTING.md](documentation/contributing.md) for details. \ No newline at end of file diff --git a/frontend/app_flowy/packages/flowy_editor/coverage/lcov.info b/frontend/app_flowy/packages/flowy_editor/coverage/lcov.info deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/frontend/app_flowy/packages/flowy_editor/documentation/node.md b/frontend/app_flowy/packages/flowy_editor/documentation/node.md new file mode 100644 index 0000000000..00c4d7ac88 --- /dev/null +++ b/frontend/app_flowy/packages/flowy_editor/documentation/node.md @@ -0,0 +1,51 @@ +# Node + +Node is the data structure used to describe the rendering information. + +## JSON + +FlowyEditor uses a specific JSON data format to describe documents. + +![Untitled](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/7bd4be04-82c8-458c-9321-a5ed79aa94ed/Untitled.png) + +Each part of a document can be converted by the above format, for example + +![Untitled](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/930ae42a-055f-4d79-bc83-921fa7845b4d/Untitled.png) + +An outermost layer is an object whose type is ‘editor’, which is used as the entry for FlowyEditor to parse data. And children are the details of the document. + +## Node + +The state tree is an in-memory mapping of a JSON file, consisting of nodes**,** and its property names are consistent with JSON keys. So each node must contain fields for **type, attributes, and children**. + +![Untitled](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/04986ead-9bb6-4f32-9584-190bd70ce5e8/Untitled.png) + +### **Type** + +Type is an identifier describing the current node. The render system distributes to the corresponding builders according to the type. Note that nodes whose type is equal to ‘text’ are used as internal reserved fields. + +### Attributes + +Attributes is an information data describing the current node. We reserve the **subtype** field to describe the derived type of the current node, and other fields can be extended at will. + +### Children + +Children are the child node describing the current node. We assume that each node can nest the other nodes. + +We encapsulate operations on Node, such as insert, delete and modify info StateTree. It holds the root node and is responsible for converting between JSON to and from it. + +### Path + +Path is an array of integer numbers to locate a node in the state tree. For example, [0, 1] represents the second child of the first child of the root node. + +### Selection + +### Reversed field + +**Type** + +- text + +**Attributes** + +- subtype \ No newline at end of file diff --git a/frontend/app_flowy/packages/flowy_editor/lib/flowy_editor.dart b/frontend/app_flowy/packages/flowy_editor/lib/flowy_editor.dart index f134d309b0..6f13228474 100644 --- a/frontend/app_flowy/packages/flowy_editor/lib/flowy_editor.dart +++ b/frontend/app_flowy/packages/flowy_editor/lib/flowy_editor.dart @@ -1,3 +1,4 @@ +/// FlowyEditor library library flowy_editor; export 'src/document/node.dart'; diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/service/input_service.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/service/input_service.dart index da755ab346..2ca2a723d5 100644 --- a/frontend/app_flowy/packages/flowy_editor/lib/src/service/input_service.dart +++ b/frontend/app_flowy/packages/flowy_editor/lib/src/service/input_service.dart @@ -7,13 +7,38 @@ import 'package:flowy_editor/src/editor_state.dart'; import 'package:flowy_editor/src/extensions/node_extensions.dart'; import 'package:flowy_editor/src/operation/transaction_builder.dart'; +/// [FlowyInputService] is responsible for processing text input, +/// including text insertion, deletion and replacement. +/// +/// Usually, this service can be obtained by the following code. +/// ```dart +/// final inputService = editorState.service.inputService; +/// +/// /** update text editing value*/ +/// inputService?.attach(...); +/// +/// /** apply text editing deltas*/ +/// inputService?.apply(...); +/// ``` +/// abstract class FlowyInputService { + /// Updates the [TextEditingValue] of the text currently being edited. + /// + /// Note that if there are IME-related requirements, + /// please config `composing` value within [TextEditingValue] void attach(TextEditingValue textEditingValue); + + /// Applies insertion, deletion and replacement + /// to the text currently being edited. + /// + /// For more information, please check [TextEditingDelta]. void apply(List deltas); + + /// Closes the editing state of the text currently being edited. void close(); } -/// process input +/// Processes text input class FlowyInput extends StatefulWidget { const FlowyInput({ Key? key, diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/service/keyboard_service.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/service/keyboard_service.dart index b7573e4ed6..9f3a7be761 100644 --- a/frontend/app_flowy/packages/flowy_editor/lib/src/service/keyboard_service.dart +++ b/frontend/app_flowy/packages/flowy_editor/lib/src/service/keyboard_service.dart @@ -3,9 +3,35 @@ import 'package:flutter/services.dart'; import 'package:flutter/material.dart'; +/// [FlowyKeyboardService] is responsible for processing shortcut keys, +/// like command, shift, control keys. +/// +/// Usually, this service can be obtained by the following code. +/// ```dart +/// final keyboardService = editorState.service.keyboardService; +/// +/// /** Simulates shortcut key input*/ +/// keyboardService?.onKey(...); +/// +/// /** Enables or disables this service */ +/// keyboardService?.enable(); +/// keyboardService?.disable(); +/// ``` +/// abstract class FlowyKeyboardService { + /// Processes shortcut key input. KeyEventResult onKey(RawKeyEvent event); + + /// Enables shortcuts service. void enable(); + + /// Disables shortcuts service. + /// + /// In some cases, if your custom component needs to monitor + /// keyboard events separately, + /// you can disable the keyboard service of flowy_editor. + /// But you need to call the `enable` function to restore after exiting + /// your custom component, otherwise the keyboard service will fail. void disable(); } diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/service/render_plugin_service.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/service/render_plugin_service.dart index b6f9414a9e..c681c3283e 100644 --- a/frontend/app_flowy/packages/flowy_editor/lib/src/service/render_plugin_service.dart +++ b/frontend/app_flowy/packages/flowy_editor/lib/src/service/render_plugin_service.dart @@ -17,7 +17,7 @@ abstract class FlowyRenderPluginService { /// Register render plugin with specified [name]. /// /// [name] should be [Node].type - /// or [Node].type + '/' + [Node].attributes['subtype']. + /// or `[Node].type + '/' + [Node].attributes['subtype']`. /// /// e.g. 'text', 'text/checkbox', or 'text/heading' /// diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/service/scroll_service.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/service/scroll_service.dart index 199249b715..a7bbd8256f 100644 --- a/frontend/app_flowy/packages/flowy_editor/lib/src/service/scroll_service.dart +++ b/frontend/app_flowy/packages/flowy_editor/lib/src/service/scroll_service.dart @@ -2,18 +2,45 @@ import 'package:flutter/gestures.dart'; import 'package:flutter/material.dart'; import 'package:flowy_editor/src/extensions/object_extensions.dart'; +/// [FlowyScrollService] is responsible for processing document scrolling. +/// +/// Usually, this service can be obtained by the following code. +/// ```dart +/// final keyboardService = editorState.service.scrollService; +/// ``` +/// abstract class FlowyScrollService { + /// Returns the offset of the current document on the vertical axis. double get dy; + + /// Returns the height of the current document. double? get onePageHeight; + /// Returns the number of pages in the current document. int? get page; + /// Returns the maximum scroll height on the vertical axis. double get maxScrollExtent; + + /// Returns the minimum scroll height on the vertical axis. double get minScrollExtent; + /// Scrolls to the specified position. + /// + /// This function will filter illegal values. + /// Only within the range of minScrollExtent and maxScrollExtent are legal values. void scrollTo(double dy); + /// Enables scroll service. void enable(); + + /// Disables scroll service. + /// + /// In some cases, you can disable scroll service of flowy_editor + /// when your custom component appears, + /// + /// But you need to call the `enable` function to restore after exiting + /// your custom component, otherwise the scroll service will fails. void disable(); } diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/service/selection_service.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/service/selection_service.dart index a256d71f03..aea643af08 100644 --- a/frontend/app_flowy/packages/flowy_editor/lib/src/service/selection_service.dart +++ b/frontend/app_flowy/packages/flowy_editor/lib/src/service/selection_service.dart @@ -40,9 +40,9 @@ abstract class FlowySelectionService { /// The result are ordered from back to front if the selection is forward. /// The result are ordered from front to back if the selection is backward. /// - /// For example, Here is an array of selected nodes, [n1, n2, n3]. - /// The result will be [n3, n2, n1] if the selection is forward, - /// and [n1, n2, n3] if the selection is backward. + /// For example, Here is an array of selected nodes, `[n1, n2, n3]`. + /// The result will be `[n3, n2, n1]` if the selection is forward, + /// and `[n1, n2, n3]` if the selection is backward. /// /// Returns empty result if there is no nodes are selected. List get currentSelectedNodes;