如何使用编辑器窗格和文本窗格

原文： https://docs.oracle.com/javase/tutorial/uiswing/components/editorpane.html

两个 Swing 类支持样式文本： JEditorPane 及其子类 JTextPane 。 JEditorPane类是 Swing 样式文本组件的基础，并提供了一种机制，您可以通过该机制添加对自定义文本格式的支持。如果您想要无样式文本，请使用文本区域。

您可以通过运行 TextSamplerDemo 来查看正在使用的编辑器窗格和文本窗格。这是TextSamplerDemo示例的图片。

An application that provides a sample of each Swing text component

单击“启动”按钮以使用 Java™Web Start （下载 JDK 7 或更高版本）运行 TextSamplerDemo。或者，要自己编译并运行示例，请参考示例索引。

Launches the TextSamplerDemo Application

TextSamplerDemo示例几乎没有开始演示编辑器窗格和文本窗格的功能。但是，右上角的编辑器窗格显示了一个方便易用的功能：它显示从 URL 加载的不可编辑的帮助信息。右下角的文本窗格演示了您可以轻松地将图像甚至组件直接嵌入到文本窗格中。

Note:

如果您需要一个成熟的帮助系统，请查看 javahelp 项目。

Swing 文本 API 功能强大且非常庞大，我们可以将整本书专门用于编辑窗格和文本窗格。本节介绍了它们的功能，提供了您可能想要使用哪些功能的提示，并指出了其他信息来源。

您可以在不了解 Swing 文本系统的情况下完成的一项任务是显示 URL 中的文本。以下是来自 TextSamplerDemo.java 的代码，它创建了一个不可编辑的编辑器窗格，显示使用 HTML 标记格式化的文本。

  1. JEditorPane editorPane = new JEditorPane();
  2. editorPane.setEditable(false);
  3. java.net.URL helpURL = TextSamplerDemo.class.getResource(
  4.                                 "TextSamplerDemoHelp.html");
  5. if (helpURL != null) {
  6.     try {
  7.         editorPane.setPage(helpURL);
  8.     } catch (IOException e) {
  9.         System.err.println("Attempted to read a bad URL: " + helpURL);
  10.     }
  11. } else {
  12.     System.err.println("Couldn't find file: TextSamplerDemoHelp.html");
  13. }
  15. //Put the editor pane in a scroll pane.
  16. JScrollPane editorScrollPane = new JScrollPane(editorPane);
  17. editorScrollPane.setVerticalScrollBarPolicy(
  18.                 JScrollPane.VERTICAL_SCROLLBAR_ALWAYS);
  19. editorScrollPane.setPreferredSize(new Dimension(250, 145));
  20. editorScrollPane.setMinimumSize(new Dimension(10, 10));

代码使用默认构造器创建编辑器窗格，然后调用setEditable(false)，以便用户无法编辑文本。接下来，代码创建URL对象，并使用它调用setPage方法。

setPage方法打开 URL 指向的资源，并计算出文本的格式（示例中为 HTML）。如果文本格式已知，编​​辑器窗格将使用 URL 中找到的文本初始化自身。标准编辑器窗格可以理解纯文本，HTML 和 RTF。请注意，页面可能是异步加载的，这会使 GUI 保持响应，但这意味着在调用setPage返回后，您不应指望完全加载的数据。

要使用编辑器窗格和文本窗格，您需要了解文本系统，文本组件功能中对此进行了描述。关于编辑器窗格和文本窗格的几个事实分散在该部分中。在这里，我们再次列出事实并提供更多细节。这里的信息应该可以帮助您理解编辑器窗格和文本窗格之间的区别，以及何时使用哪些窗格。

  • An editor pane or a text pane can easily be loaded with text from a URL using the setPage method. The JEditorPane class also provides constructors that let you initialize an editor pane from a URL. The JTextPane class has no such constructors. See Using an Editor Pane to Display Text From a URL for an example that uses this feature to load an uneditable editor pane with HTML-formatted text.

    请注意，使用setPage方法时，文档和编辑器工具包可能会更改。例如，如果编辑器窗格包含纯文本（默认值），并且您使用 HTML 加载它，则文档将更改为HTMLDocument实例，编辑器工具包将更改为HTMLEditorKit实例。如果您的程序使用setPage方法，请确保调整代码以对窗格的文档和编辑器工具包实例进行可能的更改（在新文档上重新注册文档监听器，等等）。

  • 默认情况下，编辑器窗格知道如何读取，编写和编辑纯文本，HTML 和 RTF 文本。文本窗格继承此功能，但会施加某些限制。文本窗格坚持其文档实现StyledDocument接口。 HTMLDocument和RTFDocument都是StyledDocuments，因此 HTML 和 RTF 在文本窗格中按预期工作。如果您加载带有纯文本的文本窗格，则文本窗格的文档不是您所期望的PlainDocument，而是DefaultStyledDocument。

  • 要支持自定义文本格式，请实现可以读取，写入和编辑该格式文本的编辑器工具包。然后调用registerEditorKitForContentType方法将套件注册到JEditorPane类。通过以这种方式注册编辑器工具包，程序中的所有编辑器窗格和文本窗格将能够读取，写入和编辑新格式。但是，如果新编辑器工具包不是StyledEditorKit，则文本窗格将不支持新格式。
  • 如前所述，文本窗格要求其文档实现StyledDocument接口。 Swing 文本包提供了此接口的默认实现DefaultStyledDocument，它是文本窗格默认使用的文档。文本窗格还要求其编辑器工具包是StyledEditorKit（或子类）的实例。请注意StyleEditorKit的read和write方法使用纯文本。
  • 通过其样式文档和样式编辑器工具包，文本窗格为命名样式和逻辑样式提供支持。 JTextPane类本身包含许多方法，用于处理简单地调用其文档或编辑器工具包中的方法的样式。
  • 通过JTextPane类中提供的 API，您可以在文本窗格中嵌入图像和组件。您也可以在编辑器窗格中嵌入图像，但只能将图像包含在 HTML 或 RTF 文件中。

以下是TextSamplerDemo示例中的代码，用于创建和初始化文本窗格。

  1. String[] initString =
  2.         { /* ...  fill array with initial text  ... */ };
  4. String[] initStyles =
  5.         { /* ...  fill array with names of styles  ... */ };
  7. JTextPane textPane = new JTextPane();
  8. StyledDocument doc = textPane.getStyledDocument();
  9. addStylesToDocument(doc);
  11. //Load the text pane with styled text.
  12. try {
  13.     for (int i=0; i < initString.length; i++) {
  14.         doc.insertString(doc.getLength(), initString[i],
  15.                          doc.getStyle(initStyles[i]));
  16.     }
  17. } catch (BadLocationException ble) {
  18.     System.err.println("Couldn't insert initial text into text pane.");
  19. }

简而言之，此代码将初始文本硬编码为数组，并创建并硬编码几个*样式 _ - 表示不同段落和字符格式的对象 - 到另一个数组中。接下来，代码循环遍历数组，将文本插入文本窗格，并指定用于插入文本的样式。

虽然这是一个有趣的例子，简明地演示了JTextPane的几个特性，但“真实世界”程序不太可能以这种方式初始化文本窗格。相反，程序将使用编辑器窗格来保存文档，然后将其用于初始化文本窗格。

本节列出了一些与文本和编辑器窗格相关的 API。 JEditorPane 及其子类 JTextPane 的许多最有用的方法都是从JTextComponent类继承而来的。您可以在文本组件 API 中找到JTextComponent的 API 表。另请参见 JComponent 类，它描述了从JComponent继承的 API。

方法或构造器 描述
JEditorPane（URL）

JEditorPane（String） | 创建一个加载了指定 URL 文本的编辑器窗格。 | | setPage（URL） setPage（String） | 使用指定 URL 处的文本加载编辑器窗格（或文本窗格）。 | | URL getPage（） | 获取编辑器窗格（或文本窗格）当前页面的 URL。 |

方法或构造器 描述
JTextPane（）

JTextPane（StyledDocument） | 创建文本窗格。可选参数指定文本窗格的模型。 | | StyledDocument getStyledDocument setStyledDocument（StyledDocument） | 获取或设置文本窗格的模型。 |

要开始使用文本，您可能希望运行这些程序并检查其代码以查找与您要执行的操作类似的操作。

例 在哪里描述 笔记
TextSamplerDemo 使用文本组件 使用每个 Swing 文本组件。
TextComponentDemo 文本组件功能 提供自定义文本窗格。说明了许多文本组件功能，例如撤消和重做，文档过滤器，文档监听器，插入符更改监听器以及如何将编辑操作与菜单和击键相关联。
TreeDemo 如何使用树木 使用编辑器窗格显示从 HTML 文件加载的帮助。

学习使用使用 JavaFX UI 控件编辑 JavaFX 中的 HTML 文本：HTML 编辑器教程。