Add documentation in Simplified Chinese language (#893)
OldJii
3 years ago
committed by
GitHub
parent
42b416ea56
commit
cdf6b56a61
2 changed files with 356 additions and 1 deletions
@ -0,0 +1,353 @@ |
|||||||
|
<p align="center"> |
||||||
|
<img src="https://user-images.githubusercontent.com/10923085/119221946-2de89000-baf2-11eb-8285-68168a78c658.png" width="600px"> |
||||||
|
</p> |
||||||
|
<h1 align="center">支持 Flutter 平台的富文本编辑器</h1> |
||||||
|
|
||||||
|
[![MIT License][license-badge]][license-link] |
||||||
|
[![PRs Welcome][prs-badge]][prs-link] |
||||||
|
[![Watch on GitHub][github-watch-badge]][github-watch-link] |
||||||
|
[![Star on GitHub][github-star-badge]][github-star-link] |
||||||
|
[![Watch on GitHub][github-forks-badge]][github-forks-link] |
||||||
|
|
||||||
|
[license-badge]: https://img.shields.io/github/license/singerdmx/flutter-quill.svg?style=for-the-badge |
||||||
|
[license-link]: https://github.com/singerdmx/flutter-quill/blob/master/LICENSE |
||||||
|
[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge |
||||||
|
[prs-link]: https://github.com/singerdmx/flutter-quill/issues |
||||||
|
[github-watch-badge]: https://img.shields.io/github/watchers/singerdmx/flutter-quill.svg?style=for-the-badge&logo=github&logoColor=ffffff |
||||||
|
[github-watch-link]: https://github.com/singerdmx/flutter-quill/watchers |
||||||
|
[github-star-badge]: https://img.shields.io/github/stars/singerdmx/flutter-quill.svg?style=for-the-badge&logo=github&logoColor=ffffff |
||||||
|
[github-star-link]: https://github.com/singerdmx/flutter-quill/stargazers |
||||||
|
[github-forks-badge]: https://img.shields.io/github/forks/singerdmx/flutter-quill.svg?style=for-the-badge&logo=github&logoColor=ffffff |
||||||
|
[github-forks-link]: https://github.com/singerdmx/flutter-quill/network/members |
||||||
|
|
||||||
|
|
||||||
|
FlutterQuill 是一个富文本编辑器，同样也是 [Quill] 在 [Flutter] 的版本。 |
||||||
|
|
||||||
|
该库是为移动平台构建的 “ 所见即所得 ” 的富文本编辑器，同时我们还正在对 Web 平台进行兼容。查看我们的 [Youtube 播放列表] 或 [代码介绍] 以了解代码的详细内容。你可以加入我们的 [Slack Group] 来进行讨论。 |
||||||
|
|
||||||
|
Demo App: https://bulletjournal.us/home/index.html |
||||||
|
|
||||||
|
Pub: https://pub.dev/packages/flutter_quill |
||||||
|
|
||||||
|
## 用法 |
||||||
|
|
||||||
|
查看 `示例` 目录来学习 FlutterQuill 最简单的使用方法，你通常只需要实例化一个控制器： |
||||||
|
|
||||||
|
``` |
||||||
|
QuillController _controller = QuillController.basic(); |
||||||
|
``` |
||||||
|
|
||||||
|
然后在你的 App 中嵌入工具栏和编辑器，例如： |
||||||
|
|
||||||
|
```dart |
||||||
|
Column( |
||||||
|
children: [ |
||||||
|
QuillToolbar.basic(controller: _controller), |
||||||
|
Expanded( |
||||||
|
child: Container( |
||||||
|
child: QuillEditor.basic( |
||||||
|
controller: _controller, |
||||||
|
readOnly: false, // true for view only mode |
||||||
|
), |
||||||
|
), |
||||||
|
) |
||||||
|
], |
||||||
|
) |
||||||
|
``` |
||||||
|
查看 [示例页面] 以了解高级用户。 |
||||||
|
|
||||||
|
## 输入 / 输出 |
||||||
|
|
||||||
|
该库使用 [Quill] 作为内部数据格式。 |
||||||
|
|
||||||
|
* 使用 `_controller.document.toDelta()` 获取增量。 |
||||||
|
* 使用 `_controller.document.toPlainText()` 获取纯文本。 |
||||||
|
|
||||||
|
FlutterQuill 提供了一些 JSON 序列化支持，以便您可以保存和打开文档。 要将文档保存为 JSON 类型，请执行以下操作： |
||||||
|
|
||||||
|
``` |
||||||
|
var json = jsonEncode(_controller.document.toDelta().toJson()); |
||||||
|
``` |
||||||
|
|
||||||
|
然后你就可以将其存储。 |
||||||
|
|
||||||
|
想要 FlutterQuill 编辑器使用你之前存储的 JSON 数据，请执行以下操作： |
||||||
|
|
||||||
|
``` |
||||||
|
var myJSON = jsonDecode(incomingJSONText); |
||||||
|
_controller = QuillController( |
||||||
|
document: Document.fromJson(myJSON), |
||||||
|
selection: TextSelection.collapsed(offset: 0)); |
||||||
|
``` |
||||||
|
|
||||||
|
## Web |
||||||
|
对于 web 开发，请执行 `flutter config --enable-web` 来获取对 flutter 的支持或使用 [ReactQuill] 获取对 React 的支持。 |
||||||
|
|
||||||
|
进行 Web 开发需要提供 `EmbedBuilder`, 参考：[defaultEmbedBuilderWeb](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/universal_ui/universal_ui.dart#L29). |
||||||
|
进行 Web 开发还需要提供 `webImagePickImpl`, 参考： [示例页面](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/pages/home_page.dart#L225). |
||||||
|
|
||||||
|
|
||||||
|
## Desktop |
||||||
|
|
||||||
|
在桌面端进行工具栏按钮开发，需要提供 `filePickImpl`。参考： [示例页面](https://github.com/singerdmx/flutter-quill/blob/master/example/lib/pages/home_page.dart#L205). |
||||||
|
|
||||||
|
## 配置 |
||||||
|
|
||||||
|
`QuillToolbar` 类允许您自定义可用的格式选项。[示例页面] 提供了高级使用和配置的示例代码。 |
||||||
|
|
||||||
|
### 字号 |
||||||
|
在编辑器工具栏中，提供了具有字号功能的下拉菜单。 这可以通过 `showFontSize` 启用或禁用。 |
||||||
|
|
||||||
|
启用后，可以通过*可选的* `fontSizeValues` 属性修改默认字号。 `fontSizeValues` 接受一个 `Map<String, String>`，其中包含一个 `String` 类型的标题和一个 `String` 类型的字号。 例子： |
||||||
|
``` |
||||||
|
fontSizeValues: const {'Small': '8', 'Medium': '24.5', 'Large': '46'} |
||||||
|
``` |
||||||
|
|
||||||
|
字体大小可以使用 `0` 值清除，例如： |
||||||
|
``` |
||||||
|
fontSizeValues: const {'Small': '8', 'Medium': '24.5', 'Large': '46', 'Clear': '0'} |
||||||
|
``` |
||||||
|
|
||||||
|
### 字体 |
||||||
|
想要使用你自己的字体，请更新你的 [assets folder](https://github.com/singerdmx/flutter-quill/tree/master/example/assets/fonts) 并且传入 `fontFamilyValues`。详情内容请查看 [this change](https://github.com/singerdmx/flutter-quill/commit/71d06f6b7be1b7b6dba2ea48e09fed0d7ff8bbaa), [this article](https://stackoverflow.com/questions/55075834/fontfamily-property-not-working-properly-in-flutter) 和 [this](https://www.flutterbeads.com/change-font-family-flutter/)。 |
||||||
|
|
||||||
|
### 自定义按钮 |
||||||
|
您可以通过 `customButtons` 可选参数将自定义按钮添加到工具栏的*末尾*，该参数接收的了行是 `QuillCustomButton` 的 `List`。 |
||||||
|
|
||||||
|
要添加一个 Icon，我们应该实例化一个新的新的 `QuillCustomButton` |
||||||
|
``` |
||||||
|
QuillCustomButton( |
||||||
|
icon:Icons.ac_unit, |
||||||
|
onTap: () { |
||||||
|
debugPrint('snowflake'); |
||||||
|
} |
||||||
|
), |
||||||
|
``` |
||||||
|
|
||||||
|
每个 `QuillCustomButton` 都是 `customButtons` 可选参数的一部分，如下所示： |
||||||
|
``` |
||||||
|
QuillToolbar.basic( |
||||||
|
(...), |
||||||
|
customButtons: [ |
||||||
|
QuillCustomButton( |
||||||
|
icon:Icons.ac_unit, |
||||||
|
onTap: () { |
||||||
|
debugPrint('snowflake1'); |
||||||
|
} |
||||||
|
), |
||||||
|
|
||||||
|
QuillCustomButton( |
||||||
|
icon:Icons.ac_unit, |
||||||
|
onTap: () { |
||||||
|
debugPrint('snowflake2'); |
||||||
|
} |
||||||
|
), |
||||||
|
|
||||||
|
QuillCustomButton( |
||||||
|
icon:Icons.ac_unit, |
||||||
|
onTap: () { |
||||||
|
debugPrint('snowflake3'); |
||||||
|
} |
||||||
|
), |
||||||
|
] |
||||||
|
``` |
||||||
|
|
||||||
|
### 移动端上自定义图片尺寸 |
||||||
|
|
||||||
|
定义`mobileWidth`、`mobileHeight`、`mobileMargin`、`mobileAlignment`如下： |
||||||
|
``` |
||||||
|
{ |
||||||
|
"insert": { |
||||||
|
"image": "https://user-images.githubusercontent.com/122956/72955931-ccc07900-3d52-11ea-89b1-d468a6e2aa2b.png" |
||||||
|
}, |
||||||
|
"attributes":{ |
||||||
|
"style":"mobileWidth: 50; mobileHeight: 50; mobileMargin: 10; mobileAlignment: topLeft" |
||||||
|
} |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
### 自定义嵌入块 |
||||||
|
有时您想在文本中添加一些自定义内容或者是自定义小部件。 比如向文本添加注释，或者在文本编辑器中添加的任何自定义内容。 |
||||||
|
|
||||||
|
您唯一需要做的就是添加一个 `CustomBlockEmbed` 并将其映射到 `customElementsEmbedBuilder` 中，以将自定义块内的数据转换为一个 widget！ |
||||||
|
|
||||||
|
例子： |
||||||
|
|
||||||
|
从 `CustomBlockEmbed` 开始，我们在这里扩展它并添加对 'Note' widget 的方法，这就是 `Document`，`flutter_quill` 使用它来呈现富文本。 |
||||||
|
|
||||||
|
```dart |
||||||
|
class NotesBlockEmbed extends CustomBlockEmbed { |
||||||
|
const NotesBlockEmbed(String value) : super(noteType, value); |
||||||
|
|
||||||
|
static const String noteType = 'notes'; |
||||||
|
|
||||||
|
static NotesBlockEmbed fromDocument(Document document) => |
||||||
|
NotesBlockEmbed(jsonEncode(document.toDelta().toJson())); |
||||||
|
|
||||||
|
Document get document => Document.fromJson(jsonDecode(data)); |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
然后，我们需要将这个 “notes” 类型映射到 widget 中。在例子中，我使用 `ListTile` 来显示它，使用 `onTap` 方法俩编辑内容，另外不要忘记将此方法添加到 `QuillEditor` 中。 |
||||||
|
|
||||||
|
```dart |
||||||
|
Widget customElementsEmbedBuilder( |
||||||
|
BuildContext context, |
||||||
|
QuillController controller, |
||||||
|
CustomBlockEmbed block, |
||||||
|
bool readOnly, |
||||||
|
void Function(GlobalKey videoContainerKey)? onVideoInit, |
||||||
|
) { |
||||||
|
switch (block.type) { |
||||||
|
case 'notes': |
||||||
|
final notes = NotesBlockEmbed(block.data).document; |
||||||
|
|
||||||
|
return Material( |
||||||
|
color: Colors.transparent, |
||||||
|
child: ListTile( |
||||||
|
title: Text( |
||||||
|
notes.toPlainText().replaceAll('\n', ' '), |
||||||
|
maxLines: 3, |
||||||
|
overflow: TextOverflow.ellipsis, |
||||||
|
), |
||||||
|
leading: const Icon(Icons.notes), |
||||||
|
onTap: () => _addEditNote(context, document: notes), |
||||||
|
shape: RoundedRectangleBorder( |
||||||
|
borderRadius: BorderRadius.circular(10), |
||||||
|
side: const BorderSide(color: Colors.grey), |
||||||
|
), |
||||||
|
), |
||||||
|
); |
||||||
|
default: |
||||||
|
return const SizedBox(); |
||||||
|
} |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
然后，编写一个方法来添加/编辑内容，`showDialog` 方法显示 Quill 编辑器以编辑内容，用户编辑完成后，需要检查文档是否有内容，如果有内容，在 `CustomBlockEmbed` 中添加/编辑 `NotesBlockEmbed`（注意，如果没有在 `NotesBlockEmbed` 中传递 `CustomBlockEmbed` ，编辑将不会生效）。 |
||||||
|
|
||||||
|
```dart |
||||||
|
Future<void> _addEditNote(BuildContext context, {Document? document}) async { |
||||||
|
final isEditing = document != null; |
||||||
|
final quillEditorController = QuillController( |
||||||
|
document: document ?? Document(), |
||||||
|
selection: const TextSelection.collapsed(offset: 0), |
||||||
|
); |
||||||
|
|
||||||
|
await showDialog( |
||||||
|
context: context, |
||||||
|
builder: (context) => AlertDialog( |
||||||
|
titlePadding: const EdgeInsets.only(left: 16, top: 8), |
||||||
|
title: Row( |
||||||
|
mainAxisAlignment: MainAxisAlignment.spaceBetween, |
||||||
|
children: [ |
||||||
|
Text('${isEditing ? 'Edit' : 'Add'} note'), |
||||||
|
IconButton( |
||||||
|
onPressed: () => Navigator.of(context).pop(), |
||||||
|
icon: const Icon(Icons.close), |
||||||
|
) |
||||||
|
], |
||||||
|
), |
||||||
|
content: QuillEditor.basic( |
||||||
|
controller: quillEditorController, |
||||||
|
readOnly: false, |
||||||
|
), |
||||||
|
), |
||||||
|
); |
||||||
|
|
||||||
|
if (quillEditorController.document.isEmpty()) return; |
||||||
|
|
||||||
|
final block = BlockEmbed.custom( |
||||||
|
NotesBlockEmbed.fromDocument(quillEditorController.document), |
||||||
|
); |
||||||
|
final controller = _controller!; |
||||||
|
final index = controller.selection.baseOffset; |
||||||
|
final length = controller.selection.extentOffset - index; |
||||||
|
|
||||||
|
if (isEditing) { |
||||||
|
final offset = getEmbedNode(controller, controller.selection.start).item1; |
||||||
|
controller.replaceText( |
||||||
|
offset, 1, block, TextSelection.collapsed(offset: offset)); |
||||||
|
} else { |
||||||
|
controller.replaceText(index, length, block, null); |
||||||
|
} |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
这样我们就成功的在富文本编辑器中添加了一个自定义小组件。 |
||||||
|
|
||||||
|
<p float="left"> |
||||||
|
<img width="400" alt="1" src="https://i.imgur.com/yBTPYeS.png"> |
||||||
|
</p> |
||||||
|
|
||||||
|
> 更多信息和视频示例，请参阅 [PR of this feature](https://github.com/singerdmx/flutter-quill/pull/877) |
||||||
|
|
||||||
|
> 有关更多详细信息，请查看 [this YouTube video](https://youtu.be/pI5p5j7cfHc) |
||||||
|
|
||||||
|
### 翻译 |
||||||
|
|
||||||
|
该库为 quill 工具栏和编辑器提供翻译，除非您设置自己的语言环境，否则它将遵循系统语言环境： |
||||||
|
|
||||||
|
```dart |
||||||
|
QuillToolbar(locale: Locale('fr'), ...) |
||||||
|
QuillEditor(locale: Locale('fr'), ...) |
||||||
|
``` |
||||||
|
|
||||||
|
目前，可提供以下 22 种语言环境的翻译： |
||||||
|
|
||||||
|
* `Locale('en')` |
||||||
|
* `Locale('ar')` |
||||||
|
* `Locale('de')` |
||||||
|
* `Locale('da')` |
||||||
|
* `Locale('fr')` |
||||||
|
* `Locale('zh', 'CN')` |
||||||
|
* `Locale('zh', 'HK')` |
||||||
|
* `Locale('ko')` |
||||||
|
* `Locale('ru')` |
||||||
|
* `Locale('es')` |
||||||
|
* `Locale('tr')` |
||||||
|
* `Locale('uk')` |
||||||
|
* `Locale('ur')` |
||||||
|
* `Locale('pt')` |
||||||
|
* `Locale('pl')` |
||||||
|
* `Locale('vi')` |
||||||
|
* `Locale('id')` |
||||||
|
* `Locale('nl')` |
||||||
|
* `Locale('no')` |
||||||
|
* `Locale('fa')` |
||||||
|
* `Locale('hi')` |
||||||
|
* `Locale('sr')` |
||||||
|
|
||||||
|
#### 贡献翻译 |
||||||
|
翻译文件位于 [toolbar.i18n.dart](lib/src/translations/toolbar.i18n.dart)。 随意贡献您自己的翻译，只需复制英文翻译映射并将值替换为您的翻译。 然后打开一个拉取请求，这样每个人都可以从您的翻译中受益！ |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
<p float="left"> |
||||||
|
<img width="400" alt="1" src="https://user-images.githubusercontent.com/122956/103142422-9bb19c80-46b7-11eb-83e4-dd0538a9236e.png"> |
||||||
|
<img width="400" alt="1" src="https://user-images.githubusercontent.com/122956/103142455-0531ab00-46b8-11eb-89f8-26a77de9227f.png"> |
||||||
|
</p> |
||||||
|
|
||||||
|
|
||||||
|
<p float="left"> |
||||||
|
<img width="400" alt="1" src="https://user-images.githubusercontent.com/122956/102963021-f28f5a00-449c-11eb-8f5f-6e9dd60844c4.png"> |
||||||
|
<img width="400" alt="1" src="https://user-images.githubusercontent.com/122956/102977404-c9c88e00-44b7-11eb-9423-b68f3b30b0e0.png"> |
||||||
|
</p> |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 帮助 |
||||||
|
|
||||||
|
<a href="https://bulletjournal.us/home/index.html"> |
||||||
|
<img src= |
||||||
|
"https://user-images.githubusercontent.com/122956/72955931-ccc07900-3d52-11ea-89b1-d468a6e2aa2b.png" |
||||||
|
width="150px" height="150px"></a> |
||||||
|
|
||||||
|
[Quill]: https://quilljs.com/docs/formats |
||||||
|
[Flutter]: https://github.com/flutter/flutter |
||||||
|
[FlutterQuill]: https://pub.dev/packages/flutter_quill |
||||||
|
[ReactQuill]: https://github.com/zenoamaro/react-quill |
||||||
|
[Youtube 播放列表]: https://youtube.com/playlist?list=PLbhaS_83B97vONkOAWGJrSXWX58et9zZ2 |
||||||
|
[Slack Group]: https://join.slack.com/t/bulletjournal1024/shared_invite/zt-fys7t9hi-ITVU5PGDen1rNRyCjdcQ2g |
||||||
|
[示例页面]: https://github.com/singerdmx/flutter-quill/blob/master/example/lib/pages/home_page.dart |
||||||
|
[代码介绍]: https://github.com/singerdmx/flutter-quill/blob/master/CodeIntroduction.md |
||||||
Loading…
Reference in new issue