Module java.desktop
Package javax.swing

Class JEditorPane

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.text.JTextComponent
javax.swing.JEditorPane
所有已实现的接口:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
直接已知的子类:
JTextPane
@JavaBean(defaultProperty="UIClassID", description="A text component to edit various types of content.") public class JEditorPane extends JTextComponent
用于编辑各种内容的文本组件。您可以在使用文本组件中找到如何操作和示例，这是Java教程中的一个部分。

此组件使用EditorKit的实现来完成其行为。它会根据给定内容的类型有效地转变为适当类型的文本编辑器。编辑器当前绑定的内容类型由当前安装的EditorKit决定。如果将内容设置为新的URL，则其类型将用于确定应使用哪个EditorKit来加载内容。

默认情况下，已知以下类型的内容：

text/plain
纯文本，如果给定的类型未被识别，则为默认类型。在这种情况下，使用的工具包是DefaultEditorKit的扩展，它生成一个包装的纯文本视图。
text/html
HTML文本。在这种情况下使用的工具包是javax.swing.text.html.HTMLEditorKit类，提供HTML 3.2支持。
text/rtf
RTF文本。在这种情况下使用的工具包是javax.swing.text.rtf.RTFEditorKit类，提供有限的Rich Text Format支持。

有几种方法可以将内容加载到此组件中。

  1. 可以使用setText方法从字符串初始化组件。在这种情况下，将使用当前的EditorKit，并且内容类型将被期望为此类型。
  2. 可以使用read方法从Reader初始化组件。请注意，如果内容类型为HTML，则无法解析相对引用（例如用于图像等内容）除非使用了<base>标签或在HTMLDocument上设置了Base属性。在这种情况下，将使用当前的EditorKit，并且内容类型将被期望为此类型。
  3. 可以使用setPage方法从URL初始化组件。在这种情况下，内容类型将从URL确定，并且将设置该内容类型的注册EditorKit。

某些类型的内容可能通过生成超链接事件来提供超链接支持。如果HTML EditorKit是不可编辑的（已调用JEditorPane.setEditable(false);），则HTML EditorKit将生成超链接事件。如果文档中嵌入了HTML框架，则典型的响应将是更改当前文档的一部分。以下代码片段是可能的超链接监听器实现，它特别处理HTML框架事件，并简单显示任何其他激活的超链接。

     class Hyperactive implements HyperlinkListener {
 
         public void hyperlinkUpdate(HyperlinkEvent e) {
             if (e.getEventType() == HyperlinkEvent.EventType.ACTIVATED) {
                 JEditorPane pane = (JEditorPane) e.getSource();
                 if (e instanceof HTMLFrameHyperlinkEvent) {
                     HTMLFrameHyperlinkEvent  evt = (HTMLFrameHyperlinkEvent)e;
                     HTMLDocument doc = (HTMLDocument)pane.getDocument();
                     doc.processHTMLFrameHyperlinkEvent(evt);
                 } else {
                     try {
                         pane.setPage(e.getURL());
                     } catch (Throwable t) {
                         t.printStackTrace();
                     }
                 }
             }
         }
     }

有关自定义如何呈现text/html的信息，请参阅W3C_LENGTH_UNITS和HONOR_DISPLAY_PROPERTIES

某些文档中的与文化相关的信息通过称为字符编码的机制处理。字符编码是字符集的成员（字母、表意文字、数字、符号或控制功能）到特定数值代码的明确映射。它表示文件的存储方式。示例字符编码包括ISO-8859-1、ISO-8859-5、Shift-jis、Euc-jp和UTF-8。当文件传递给用户代理（JEditorPane）时，它将转换为文档字符集（ISO-10646也称为Unicode）。

有多种方法可以使JEditorPane进行字符集映射。

  1. 一种方法是将字符集作为MIME类型的参数指定。这将通过调用setContentType方法来建立。如果内容由setPage方法加载，则内容类型将根据URL的规范设置。如果文件直接加载，则预期在加载之前已设置内容类型。
  2. 另一种指定字符集的方法是在文档本身中指定。这要求在确定所需字符集之前读取文档。为了处理这一点，预期EditorKit.read操作会抛出一个ChangedCharSetException，将被捕获。然后使用在ChangedCharSetException（它是一个IOException）中指定的字符集重新启动读取。
换行符
有关如何处理换行符的讨论，请参见DefaultEditorKit。

警告: Swing不是线程安全的。有关更多信息，请参见Swing的线程策略。

警告: 此类的序列化对象将不兼容未来的Swing版本。当前的序列化支持适用于短期存储或在运行相同版本Swing的应用程序之间的RMI。从1.4版本开始，已将所有JavaBeans的长期存储支持添加到java.beans包中。请参阅XMLEncoder。

自从:
1.2

  • Field Details

    • W3C_LENGTH_UNITS

      public static final String W3C_LENGTH_UNITS
      用于指示是否在HTML渲染中使用符合w3c标准长度单位的客户端属性的键。

      默认情况下，此功能未启用；要启用它，请将具有此名称的客户端属性设置为Boolean.TRUE。

      自版本:
      1.5
      另请参阅:

    • HONOR_DISPLAY_PROPERTIES

      public static final String HONOR_DISPLAY_PROPERTIES
      用于指示如果在样式文本中未指定字体或前景色，则是否使用组件的默认字体和前景色的客户端属性的键。

      默认值根据外观和感觉而变化；要启用它，请将具有此名称的客户端属性设置为Boolean.TRUE。

      自版本:
      1.5
      另请参阅:

  • Constructor Details

    • JEditorPane

      public JEditorPane()
      创建一个新的JEditorPane。文档模型设置为null。

    • JEditorPane

      public JEditorPane(URL initialPage) throws IOException
      基于指定URL的输入创建一个JEditorPane。
      参数:
      initialPage - URL
      抛出:
      IOException - 如果URL为null或无法访问

    • JEditorPane

      public JEditorPane(String url) throws IOException
      基于包含URL规范的字符串创建一个JEditorPane。
      参数:
      url - URL
      抛出:
      IOException - 如果URL为null或无法访问

    • JEditorPane

      public JEditorPane(String type, String text)
      创建一个已初始化为给定文本的JEditorPane。这是一个方便的构造函数，调用setContentType和setText方法。
      参数:
      type - 给定文本的MIME类型
      text - 要初始化的文本；可以为null
      抛出:
      NullPointerException - 如果type参数为null

  • Method Details

    • addHyperlinkListener

      public void addHyperlinkListener(HyperlinkListener listener)
      添加超链接监听器以通知任何更改，例如当选择并输入链接时。
      参数:
      listener - 监听器

    • removeHyperlinkListener

      public void removeHyperlinkListener(HyperlinkListener listener)
      移除超链接监听器。
      参数:
      listener - 监听器

    • getHyperlinkListeners

      @BeanProperty(bound=false) public HyperlinkListener[] getHyperlinkListeners()
      返回添加到此JEditorPane的所有HyperLinkListener的数组。
      返回:
      所有已添加的HyperLinkListener或空数组（如果未添加任何监听器）
      自版本:
      1.4

    • fireHyperlinkUpdate

      public void fireHyperlinkUpdate(HyperlinkEvent e)
      通知所有已注册对此事件类型感兴趣的所有监听器。通常由当前安装的EditorKit调用，如果当前活动的内容类型支持超链接并且有链接活动，则会调用此方法。监听器列表按照从后到前的顺序处理。
      参数:
      e - 事件
      另请参阅:

    • setPage

      @BeanProperty(expert=true, description="the URL used to set content") public void setPage(URL page) throws IOException
      设置当前正在显示的URL。设置面板的内容类型，并且如果面板的编辑器工具包非null，则会创建一个新的默认文档并将URL读取到其中。如果URL包含引用位置，则将调用scrollToReference方法滚动到该位置。如果所需的URL是当前正在显示的URL，则不会重新加载文档。要强制重新加载文档，需要清除文档的流描述属性。以下代码显示了如何执行此操作： 
         Document doc = jEditorPane.getDocument();
   doc.putProperty(Document.StreamDescriptionProperty, null);
      如果所需的URL不是当前显示的URL，则将调用getStream方法，以便子类控制提供的流。

      这可能是同步加载或异步加载，具体取决于EditorKit返回的文档。如果Document是AbstractDocument类型，并且由AbstractDocument.getAsynchronousLoadPriority返回的值大于或等于零，则将使用该优先级在单独的线程上加载页面。

      如果文档是同步加载的，它将在安装到编辑器之前填充流，这将绑定并触发属性更改事件。如果抛出IOException，部分加载的文档将被丢弃，文档或页面属性更改事件都不会触发。如果文档成功加载并安装，UI将为其构建一个视图，然后根据需要滚动，然后触发页面属性更改事件。

      如果文档是异步加载的，文档将立即安装到编辑器中，使用setDocument调用，这将触发文档属性更改事件，然后将创建一个线程，开始执行实际加载。在这种情况下，直接调用此方法不会触发页面属性更改事件，而是在执行加载的线程完成时触发。它也将在事件分派线程上触发。由于调用线程无法在其他线程出现故障时抛出IOException，因此无论加载是否成功，其他线程完成时都会触发页面属性更改事件。

      参数:
      page - 页面的URL
      抛出:
      IOException - 对于null或无效的页面规范，或从读取流中引发的异常
      另请参阅:

    • read

      public void read(InputStream in, Object desc) throws IOException
      从流初始化。如果工具包设置为HTMLEditorKit类型，并且desc参数是HTMLDocument，则调用HTMLEditorKit来启动读取。否则，调用加载模型为纯文本的超类方法。
      参数:
      in - 要读取的流
      desc - 描述流的对象
      抛出:
      IOException - 由用于初始化的流引发
      另请参阅:

    • getStream

      protected InputStream getStream(URL page) throws IOException
      获取给定URL的流，该流将由setPage方法加载。默认情况下，这只是打开URL并返回流。这可以重新实现为执行有用的操作，如从缓存中获取流，监视流的进度等。

      预计此方法会具有副作用，即建立内容类型，因此设置适合用于加载流的适当EditorKit。

      如果流是http连接，则将遵循重定向，并将生成的URL设置为Document.StreamDescriptionProperty，以便可以正确解析相对URL。

      参数:
      page - 页面的URL
      返回:
      将要加载的URL的流
      抛出:
      IOException - 如果发生I/O问题

    • scrollToReference

      public void scrollToReference(String reference)
      将视图滚动到给定引用位置（即正在显示的URL的URL.getRef方法返回的值）。默认情况下，此方法仅知道如何在HTMLDocument中定位引用。实现调用scrollRectToVisible方法来实现实际滚动。如果需要为除HTML之外的文档类型滚动到引用位置，则应重新实现此方法。如果组件不可见，则此方法不起作用。
      参数:
      reference - 要滚动到的命名位置

    • getPage

      public URL getPage()
      获取当前正在显示的URL。如果在创建文档时未指定URL，则将返回null，并且相对URL将不会被解析。
      返回:
      URL，如果没有则返回null

    • setPage

      public void setPage(String url) throws IOException
      设置当前正在显示的URL。
      参数:
      url - 用于显示的URL
      抛出:
      IOException - 对于null或无效的URL规范

    • getUIClassID

      @BeanProperty(bound=false) public String getUIClassID()
      获取UI的类ID。
      覆盖:
      getUIClassID 在类 JComponent中
      返回:
      字符串"EditorPaneUI"
      另请参阅:

    • createDefaultEditorKit

      protected EditorKit createDefaultEditorKit()
      创建组件首次创建时的默认编辑器工具包（PlainEditorKit）。
      返回:
      编辑器工具包

    • getEditorKit

      public EditorKit getEditorKit()
      获取当前安装的用于处理内容的工具包。如果需要，将调用createDefaultEditorKit来设置默认值。
      返回:
      编辑器工具包

    • getContentType

      public final String getContentType()
      获取此编辑器当前设置为处理的内容类型。这是指与当前安装的EditorKit相关联的类型。
      返回:
      内容类型，如果未设置编辑器工具包则为null

    • setContentType

      @BeanProperty(bound=false, description="the type of content") public final void setContentType(String type)
      设置此编辑器处理的内容类型。这将调用getEditorKitForContentType，然后如果可以成功定位编辑器工具包，则调用setEditorKit。这主要是一个方便的方法，可以用作直接调用setEditorKit的替代方法。

      如果在内容类型规范的参数中指定了字符集定义，则在使用相关EditorKit加载输入流时将使用它。例如，如果类型指定为text/html; charset=EUC-JP，则将使用为text/html注册的EditorKit加载内容，并且提供给EditorKit的Reader将使用EUC-JP字符集进行转换为unicode。如果类型未被识别，则将使用为纯文本text/plain注册的EditorKit加载内容。

      参数:
      type - 非null的内容编辑支持的MIME类型
      抛出:
      NullPointerException - 如果type参数为null
      参见:

    • setEditorKit

      @BeanProperty(expert=true, description="the currently installed kit for handling content") public void setEditorKit(EditorKit kit)
      设置当前安装的用于处理内容的工具包。这是建立编辑器内容类型的绑定属性。首先卸载任何旧的工具包，然后如果工具包非null，则安装新的工具包，并为其创建一个默认文档。每当调用setEditorKit时，总是会触发一个PropertyChange事件（"editorKit"）。

      注意：这会导致更改模型的副作用，因为EditorKit是特定类型内容建模的来源。此方法将导致代表调用者调用setDocument，以确保内部状态的完整性。

      参数:
      kit - 所需的编辑器行为
      参见:

    • getEditorKitForContentType

      public EditorKit getEditorKitForContentType(String type)
      获取用于给定类型内容的编辑器工具包。当请求一个与当前安装类型不匹配的类型时，将调用此方法。如果组件没有为给定类型注册EditorKit，则将尝试从默认EditorKit注册表中创建一个EditorKit。如果失败，则假定所有文本文档都可以表示为纯文本，将使用PlainEditorKit。

      可以重新实现此方法以使用其他类型注册表。例如，可以重新实现以使用Java Activation Framework。

      参数:
      type - 内容类型
      返回:
      编辑器工具包，如果没有为给定类型注册任何内容，则返回null

    • setEditorKitForContentType

      public void setEditorKitForContentType(String type, EditorKit k)
      直接设置用于给定类型的编辑器工具包。外观实现可能会与createEditorKitForContentType一起使用，以为具有外观偏见的内容类型安装处理程序。
      参数:
      type - 非null的内容类型
      k - 要设置的编辑器工具包

    • replaceSelection

      public void replaceSelection(String content)
      用给定字符串表示的新内容替换当前选定的内容。如果没有选择，则相当于插入给定文本。如果没有替换文本（即内容字符串为空或null），则相当于删除当前选择。替换文本将具有当前为输入定义的属性。如果组件不可编辑，则发出哔声并返回。
      覆盖:
      replaceSelection 在类 JTextComponent
      参数:
      content - 用于替换选择的内容。此值可以为null

    • createEditorKitForContentType

      public static EditorKit createEditorKitForContentType(String type)
      从默认编辑器工具包注册表中创建给定类型的处理程序。如果需要，将创建注册表。如果尚未加载注册类，则将尝试动态加载给定类型的工具包原型。如果该类型已使用ClassLoader注册，则将使用该ClassLoader来加载原型。如果没有注册ClassLoader，则将使用Class.forName来加载原型。

      一旦成功定位原型EditorKit实例，将对其进行克隆并返回克隆。

      参数:
      type - 内容类型
      返回:
      编辑器工具包，如果没有为给定类型注册任何内容，则返回null

    • registerEditorKitForContentType

      public static void registerEditorKitForContentType(String type, String classname)
      建立type到classname的默认绑定。当实际需要时，将稍后动态加载该类，并且可以在尝试使用之前安全地更改以避免加载不需要的类。当使用此方法注册时，将使用Class.forName加载原型EditorKit。
      参数:
      type - 非null的内容类型
      classname - 待加载的类

    • registerEditorKitForContentType

      public static void registerEditorKitForContentType(String type, String classname, ClassLoader loader)
      建立type到classname的默认绑定。当实际需要时，将使用给定的ClassLoader稍后动态加载该类，并且可以在尝试使用之前安全地更改以避免加载不需要的类。
      参数:
      type - 非null的内容类型
      classname - 待加载的类
      loader - 用于加载名称的ClassLoader

    • getEditorKitClassNameForContentType

      public static String getEditorKitClassNameForContentType(String type)
      返回类型type当前注册的EditorKit类名。
      参数:
      type - 非null的内容类型
      返回:
      包含type的EditorKit类名的String
      自:
      1.3

    • getPreferredSize

      public Dimension getPreferredSize()
      返回JEditorPane的首选大小。JEditorPane的首选大小与超类的首选大小略有不同。如果视口的大小变小到小于组件的最小大小，则用于跟踪宽度或高度的可滚动定义将变为false。默认视口布局将给出首选大小，这在跟踪滚动时是不希望的。在这种情况下，将正常首选大小调整为最小大小。这允许HTML表格缩小到其最小大小，然后以其最小大小布局，拒绝进一步缩小。
      覆盖:
      getPreferredSize 在类 JComponent
      返回:
      包含首选大小的Dimension
      参见:

    • setText

      @BeanProperty(bound=false, description="the text of this component") public void setText(String t)
      将此TextComponent的文本设置为指定内容，该内容应符合此编辑器的内容类型的格式。例如，如果类型设置为text/html，则应以HTML格式指定字符串。

      此实现将删除当前文档的内容，并通过使用当前EditorKit解析给定字符串来替换它们。这通过不更改模型的语义来实现超类的行为，同时支持当前设置在此组件上的内容类型。假设先前的内容相对较小，并且先前的内容没有副作用。这两个假设可能被违反并导致不良结果。为避免这种情况，请创建一个新文档，getEditorKit().createDefaultDocument()，并用新文档替换现有的Document。然后，您可以确保先前的Document不会有任何残留状态。

      1. 保留现有模型意味着将拆除旧视图并创建新视图，而替换文档将避免拆除旧视图。
      2. 某些格式（如HTML）可以将内容安装到文档中，这可能会意外地影响未来的内容。HTML可以嵌入样式信息，这可能会意外地影响下一个安装的内容。
      覆盖:
      setText 在类 JTextComponent
      参数:
      t - 要设置的新文本；如果为null，则旧文本将被删除
      参见:

    • getText

      public String getText()
      以此编辑器的内容类型为基础返回TextComponent中包含的文本。如果在尝试检索文本时抛出异常，则将返回null。此实现将调用JTextComponent.write并使用StringWriter。
      覆盖：
      getText 在类 JTextComponent中
      返回：
      文本
      参见：

    • getScrollableTracksViewportWidth

      @BeanProperty(bound=false) public boolean getScrollableTracksViewportWidth()
      如果视口应始终强制此Scrollable的宽度与视口的宽度匹配，则返回true。
      指定者：
      getScrollableTracksViewportWidth 在接口 Scrollable中
      覆盖：
      getScrollableTracksViewportWidth 在类 JTextComponent中
      返回：
      如果视口应强制Scrollable的宽度与其自身匹配，则返回true，否则返回false

    • getScrollableTracksViewportHeight

      @BeanProperty(bound=false) public boolean getScrollableTracksViewportHeight()
      如果视口应始终强制此Scrollable的高度与视口的高度匹配，则返回true。
      指定者：
      getScrollableTracksViewportHeight 在接口 Scrollable中
      覆盖：
      getScrollableTracksViewportHeight 在类 JTextComponent中
      返回：
      如果视口应强制Scrollable的高度与其自身匹配，则返回true，否则返回false

    • paramString

      protected String paramString()
      返回此JEditorPane的字符串表示形式。此方法仅用于调试目的，返回的字符串的内容和格式可能因实现而异。返回的字符串可能为空，但不能为null。
      覆盖：
      paramString 在类 JTextComponent中
      返回：
      此JEditorPane的字符串表示形式

    • getAccessibleContext

      @BeanProperty(bound=false) public AccessibleContext getAccessibleContext()
      获取与此JEditorPane关联的AccessibleContext。对于编辑器窗格，AccessibleContext采用AccessibleJEditorPane的形式。如有必要，将创建一个新的AccessibleJEditorPane实例。
      指定者：
      getAccessibleContext 在接口 Accessible中
      覆盖：
      getAccessibleContext 在类 JTextComponent中
      返回：
      作为此JEditorPane的AccessibleContext的AccessibleJEditorPane