Documents

Documents 是可编辑的Unicode编码的字符串，通常虚拟文件（Virtual File）的内容封装为Documents对象。

在 Documents 中换行符统一使用 \n ,当加载和保存Documents时，IntelliJ Platform 会对内容进行统一编码，并转换换行符。

如何获取Documents

操作环境	API
Action	AnActionEvent.getData(CommonDataKeys.EDITOR).getDocument()
PSI File	PsiDocumentManager.getDocument()/getCachedDocument()
虚拟文件 （Virtual File）	FileDocumentManager.getDocument() ：如果没有加载过document，会进行强制加载 FileDocumentManager.getCachedDocument() )：仅在打开过的或修改过的document里使用

Documents能干什么

可以基于"纯文本"访问和修改文件内容（不同于 Program Structure Interface (PSI) 将文件内容封闭为树形结构）

Documents从何而来

当需要访问文件内容的时候，会把文件内容创建为 Document 实例（特别是构建一个文件的 PSI 时）。

一般情况下，Document都关联了某个virtual files，但是可以创建未关联 virtual files 的临时Document，例如可以为对话框中文本输入框的内容创建Document

Documents能保存多久？

Document 实例和virtual files是弱引用。所以，如果未修改过的Document 没有被引用，它会被垃圾回收。当再次访问Document内容的时候会创建新的实例

注意

在插件中，长时间的强引用Document可能会造成内存泄漏

如何创建Documents

不要直接创建 Documents。可以先创建PSI File 文件，然后再访问该文件的内容，从而生成 Documents实例。

使用EditorFactory.createDocument() 可以创建一个未绑定任何东西的 Documents实例

如何订阅VFS文件修改事件

• Document.addDocumentListener() 可以接收具体某一个 Document 实例修改的通知。

actionEvent.getData(CommonDataKeys.EDITOR).getDocument().addDocumentListener("监听器实现类")

• EditorFactory.getInstance().getEventMulticaster().addDocumentListener() ：可以接收到所有打开的documents的修改通知

• 当保存或重新加载Documents时。通过在plugin.xml 里注册 FileDocumentManagerListener 类型 监听器 或 订阅任意级别总线上的 AppTopics.FILE_DOCUMENT_SYNC 事件都可以接收到修改通知

Documents使用规范

需要符合线程规则 。另外，修改内容的操作必须包装在CommandProcessor.executeCommand() 方法里执行。executeCommand() 可以嵌套使用，最外层的 executeCommand() 调用被添加到撤消堆栈中。如果在一个命令中同时修改了多个Documents，默认情况下撤消此命令时将向用户显示一个确认对话框。

如果一个文件是只读的，那么修改这个文件对应的Documents 将会失败。所以在修改Documents之前，最好调用ReadonlyStatusHandler.ensureFilesWritable() 方法确认该文件是否是只读的。

所有通过Document (setText(), insertString(), replaceString() 等)的方法修改的内容，换行符必须使用 \n

了解更多可以查看编辑器基础教程里的Working with Text

操作Documents的方法

DocumentUtil 里包含处理 Document 的常用方法。可以获取到某一行的文本偏移量等信息。方便你获取 PsiElement 的位置和偏移量等信息。