IntelliJ Platform 插件开发文档翻译 － 文档

文档 Document 是一个可编辑的Unicode字符序列，一般作为虚拟文件的内容使用。文档中的换行符被标准化为\n。IntelliJ Platform在读取和保存文档时会显式地对其进行编码和换行符标准化。

如何获取文档?

• 从action获取: e.getData(PlatformDataKeys.EDITOR).getDocument()
• 从虚拟文件获取: FileDocumentManager.getDocument(). 如果文件还没被从硬盘加载，这个方法将帮你完成加载过程。你过你只是要打开文档或者文档已经被修改，请使用 FileDocumentManager.getCachedDocument() 从缓存读取。
• 从PSI 文件读取: PsiDocumentManager.getInstance().getDocument() or PsiDocumentManager.getInstance().getCachedDocument()

文档能做什么?

把它看成简单的"纯文本", 对纯文本能做的任何操作都支持(字符序列，而不是java元素树)。

文档从何而来?

文档实例由需要访问文件文本内容的操作创建（特别地，这需要为文件创建PSI）。并且，文档不与任何临时创建的虚拟文件关联，比如为了在对话框的文本编辑框中展示内容而建立的虚拟文件。

文档的生命周期?

文档 实例是VirtualFile的弱引用。因此，未修改的Document实例如果不再被任何对象引用，将会被GC回收。如果文档内容再次被访问，会再创建新的实例。使用持久的数据结构引用你的Document可能造成内存泄露。

如何创建文档?

如果你需要在硬盘伤创建新文件，你不会创建Document: 你应该创建一个PSI文件，然后获取它的Document.如果你需要创建一个不依赖任何东西的Document实例，可以使用EditorFactory.createDocument.

如何获取文档变化通知?

• Document.addDocumentListener 允许你接收指定Document实例的变化通知。
• EditorFactory.getEventMulticaster().addDocumentListener允许你接收所有打开的Document实例的变化通知。
• FileDocumentManager.addFileDocumentManagerListener 允许你接收所有Document从硬盘reload和save事件通知。

文档的工作细则?

事实上是在讨论读写规则。任何修改文档内容的操作必须通过CommandProcessor.getInstance().executeCommand()命令执行。executeCommand()可以嵌套执行，并且最外层的调用会被添加到撤销堆栈上。如果一条命令同时修改了多个文档，撤销操作默认弹出一个确认对话框供用户确认。

如果一个文档对应的文件是只读的（比如，没有从版本控制系统中检出），文件修改操作会失败。因此，在你修改一个文档之前，确保使用ReadonlyStatusHandler.getInstance(project).ensureFilesWritable()方法检出文件。

所有文档修改方法的字符串参数必须使用\n换行符。