文档

原文链接：
http://www.jetbrains.org/intellij/sdk/docs/basics/architectural_overview/documents.html

文档就是可编辑的Unicode字符序列，它可以对应于虚拟文件中的文本内容。文档中的换行符总是被标准化为\n。IntelliJ平台会在加载和保存文档时透明地处理编码和转换换行符。

我怎样得到一个文档？

• 操作：e.getData(PlatformDataKeys.EDITOR).getDocument()；
• 虚拟文件：FileDocumentManager.getDocument()。如果文件之前并没有被加载，这个方法会强制从磁盘加载文档内容；如果你只对打开的文档或被修改过的文档感兴趣，使用FileDocumentManager.getCachedDocument()代替；
• PSI文件：PsiDocumentManager.getInstance().getDocument()或PsiDocumentManager.getInstance().getCachedDocument()。

我能用它来做什么？

你可以在“纯文本”级别（作为字符序列，而不是Java元素树）执行任何访问或修改文件内容的操作。

它从何而来？

文档实例在某些操作需要访问文件的文本内容时（特别是需要构建文件的PSI时）被创建。此外，未链接到任何虚拟文件的文档实例也可以被创建，例如对话框中的文本编辑器字段的内容。

文档可以持久化多长时间？

文档实例是来自VirtualFile实例的弱引用。因此一个未修改且没有任何引用的Document实例会被垃圾回收机制回收，如果以后再次访问文档内容将会创建一个新实例。 在插件的长期数据结构中存储Document引用将导致内存泄漏。

我怎样创建一个文档？

如果你需要在磁盘上创建文件，你不必创建Document：你可以创建PSI文件然后获取它的Document。如果你需要创建一个不绑定任何其它东西的Document实例，你可以使用EditorFactory.createDocument。

文档改变时我怎样得到通知？

• Document.addDocumentListener允许你接受Document实例更改的通知；
• EditorFactory.getEventMulticaster().addDocumentListener允许你接受所有打开文档更改的通知；
• FileDocumentManager.addFileDocumentManagerListener允许你接受任何Document保存或从磁盘重新加载时的通知。

使用文档有什么规则?

通用的读/写操作规则都是有效的。除此之外，任何修改文档内容的操作都必须包裹在命令（CommandProcessor.getInstance().executeCommand()）中。executeCommand()可以嵌套调用，最外层的executeCommand调用将被添加到撤销堆栈。如果一个命令中修改多个文档，则取消此命令将默认向用户显示确认对话框。

如果Document对应的文件是只读的（例如, 未从版本控制系统中签出），文档修改将会失败。因此在修改 Document之前需要调用ReadonlyStatusHandler.getInstance(project).ensureFilesWritable()方法文件是否可写。

所有传递给Document文档修改方法(setText, insertString, replaceString)的文本字符串必须只使用\n作为换行符。