官方文档

https://www.jetbrains.org/intellij/sdk/docs/basics/architectural_overview/documents.html

Github

https://github.com/kungyutucheng/my_gradle_plugin

运行环境

macOS 10.14.5
IntelliJ idea 2019.2.4

定义

Document是一种可编辑的unicode字符序列，一般与virtual file的文本的内容是一致的，在Document中，换行符规范为\n

获取方式

• 从action：e.getData(PlatformDateKeys.EDITOR).getDocument()
• 从virtual file：FileDoucmentManager.getDocument()，如果文件未从硬盘加载过，则会被硬性加载，如果只对已打开的Document或者是修改过的Document感兴趣，则使用FileDocumentManager.getCachedDocument()
• 从PSI file：PsiDocumentManager.getInstance().getDocument() 或者PsiDocumentManager.getInstance().getCachedDocument()

用处

以纯文本格式访问或者修改文件内容

Document来源

当需要访问文件内容时，一个Document被创建，当然，不和任何virtual file关联的Document也可以被创建，比如，为了在对话框展示一个文本编辑器的内容

Document生命周期

Document实例和virtual file实例之间是弱引用关系，因此，一个未曾被修改的Document实例在不存在任何引用的情况是可以被垃圾回收的，而当文件内容在这之后再次被访问的时候，则又会创建一个新实例。插件中的长期数据结构的Document强引用会造成内存泄漏

创建Document

注意和上文的获取Document不同，此处是创建，一般来说，我们都不需要去创建，只需要获取，比如说通过PSI file获取Document，当然，我们也可以通过EditorFactory.createDocument来创建一个未和任何事物绑定的Document

Docuemnt更新通知机制

• Document.addDocumentListener：接收特定Document实例的改变通知
• EditorFactory.getEventMulticaster().addDocumentListener：接收所有已打开的Document的改变通知
• 监听AppTopics#FILE_DOCUMENT_SYNC消息，接收Document保存或者从硬盘加载的通知

Document处理规则

通用读写规则对Document是生效的，除此之外，任何对Document的修改操作都应该被包装在CommandProcessor.getInstance().executeCommand()命令中，该命令允许嵌套，并且最外层命令会被包含在撤销栈中

另外，在修改Document之前，应该调用ReadonlyStatusHandler.getInstance(project).ensureFilesWritable()来确认Document是否可写，否则，对于只读文件，修改操作将会失败

所有Document中的stirng相关的修改方法的换行符都必须使用\n

官方工具类

DocumentUtil