javax.swing
类 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

public class JEditorPane
extends JTextComponent

可编辑各种内容的文本组件。有关基础知识信息和使用编辑器窗格的示例，请参阅 The Java Tutorial 中的 Using Text Components 一节。

此组件使用 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。

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

     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 aka Unicode)。

有多种方式可获得使用 JEditorPane 时所用的字符集映射关系。

1. 一种方式是将字符集指定为 MIME 类型的参数。通过调用 setContentType 方法来建立此方式。如果通过 setPage 方法加载内容，则其内容类型已根据 URL 的规范进行了设置。如果直接加载文件，则期望在加载前就已设置内容类型。
2. 指定字符集的另一种方式是在该文档内指定。这需要在确定所需的字符集之前读取该文档。要处理此情况，需要 EditorKit.read 操作抛出将要被捕获的 ChangedCharSetException。然后使用新的 Reader 重新开始该 read 操作，该 Reader 使用 ChangedCharSetException（这是一个 IOException）中所指定的字符集。

换行

有关如何处理换行的讨论，请参阅 DefaultEditorKit。

警告： Swing 不是线程安全的。有关更多信息，请参阅 Swing's Threading Policy。

警告：此类的序列化对象与以后的 Swing 版本不兼容。当前序列化支持适用于短期存储，或适用于在运行相同 Swing 版本的应用程序之间进行 RMI（Remote Method Invocation，远程方法调用）。从 1.4 版本开始，已在 java.beans 包中添加了支持所有 JavaBeans^TM 长期存储的功能。请参见 XMLEncoder。

W3C_LENGTH_UNITS

public static final String W3C_LENGTH_UNITS

用于客户机属性的关键字，指示是否为 html 呈现使用 w3c 兼容的长度单位。

默认不启用此属性；要启用它，可将带有此名称的客户机 property 设置为 Boolean.TRUE。

从以下版本开始：

1.5

另请参见：

常量字段值

HONOR_DISPLAY_PROPERTIES

public static final String HONOR_DISPLAY_PROPERTIES

用于客户机属性的关键字，指示如果在样式化文本中未指定字体或前景色，那么是否使用该组件的默认字体和前景色。

根据外观的不同，该默认值有所不同；要启用该属性，可将带有此名称的客户机 property 设置为 Boolean.TRUE。

从以下版本开始：

1.5

另请参见：

常量字段值

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

addHyperlinkListener

public void addHyperlinkListener(HyperlinkListener listener)

为了通知所有的更改（例如选中和进入某个链接）而添加一个超链接侦听器。

参数：

listener - 侦听器

removeHyperlinkListener

public void removeHyperlinkListener(HyperlinkListener listener)

移除超链接侦听器。

参数：

listener - 侦听器

getHyperlinkListeners

public HyperlinkListener[] getHyperlinkListeners()

返回使用 addHyperlinkListener() 添加到此 JEditorPane 的所有 HyperLinkListener 的数组。

返回：

已添加的所有 HyperLinkListener，如果尚未添加侦听器，则返回一个空数组

从以下版本开始：

1.4

fireHyperlinkUpdate

public void fireHyperlinkUpdate(HyperlinkEvent e)

通知因对此事件类型的通知感兴趣而已注册的所有侦听器。如果支持超链接的内容类型当前处于激活状态并且使用了某个链接，则通常由当前已安装的 EditorKit 调用此方法。从后向前处理侦听器列表。

参数：

e - 事件

另请参见：

EventListenerList

setPage

public void setPage(URL page)
             throws IOException

设置当前要显示的 URL。设置该窗格的内容类型，并且如果该窗格的编辑器工具包是非 null 的，则创建一个新的默认文档并将 URL 读入该文档。如果该 URL 包含并引用了位置，则通过调用 scrollToReference 方法滚动到该位置。如果所需的 URL 就是当前所显示的，则不会重新加载该文档。要强行重新加载某个文档，必须清除该文档的流描述属性。以下代码显示了如何完成该任务：

   Document doc = jEditorPane.getDocument();
   doc.putProperty(Document.StreamDescriptionProperty, null);
 

如果所需的 URL 不是当前所显示的，则调用 getStream 方法，让子类控制所提供的流。

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

如果同步加载文档，则先使用流填充文档，然后通过调用 setDocument 将其安装到编辑器中，而该调用将激发属性更改事件。如果抛出 IOException，则丢弃部分加载的文档，并且不激发文档和页面属性更改事件。如果成功加载并安装了该文档，则由 UI 为其建立一个视图，如有必要，接着滚动该 UI，之后激发页面属性更改事件。

如果异步加载该文档，则立即通过调用 setDocument （这会激发文档属性更改事件）将该文档安装到编辑器中，然后创建一个线程，而该线程将开始执行实际的加载工作。在这种情况下，直接调用此方法不会激发页面属性更改事件，而在线程加载结束时会激发该事件。在事件调度线程上也会激发该事件。因为调用线程无法在其他线程上出现失败事件的情况下抛出 IOException，所以在其他线程完成任务时（不管加载是否成功）将激发页面属性更改事件。

参数：

page - 页面的 URL

抛出：

IOException - 对于 null 或无效的页面规范，或者来自所读取的流的异常

另请参见：

getPage()

read

public void read(InputStream in,
                 Object desc)
          throws IOException

此方法根据流进行初始化。如果工具包被设置为 HTMLEditorKit 类型，并且 desc 参数是 HTMLDocument，则此方法调用 HTMLEditorKit 来初始化读取。否则它调用以纯文本的方式加载模型的超类方法。

参数：

in - 从中读取的流

desc - 描述流的对象

抛出：

IOException - 由用于初始化的流抛出

另请参见：

JTextComponent.read(java.io.Reader, java.lang.Object), JTextComponent.setDocument(javax.swing.text.Document)

getStream

protected InputStream getStream(URL page)
                         throws IOException

获取给定 URL 的流，该 URL 是将要由 setPage 方法加载的。默认情况下，这只是简单地打开该 URL 并返回流。可重新实现此方法以执行有用的任务，例如从缓存中获取流、监视该流的进程等等。

期望此方法具有的副作用是：建立该内容类型，从而设置加载流所要使用的合适的 EditorKit。

如果该流为 http 链接，那么接着会进行重定向，并将得到的 URL 设置为 Document.StreamDescriptionProperty，这样即可正确地解析相关的 URL。

参数：

page - 页面 URL

抛出：

IOException

scrollToReference

public void scrollToReference(String reference)

将视图滚动到给定的参考位置（也就是正在显示的 URL 的 UL.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

public String getUIClassID()

获得该 UI 的类 ID。

覆盖：

类 JComponent 中的 getUIClassID

返回：

字符串 "EditorPaneUI"

另请参见：

JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createDefaultEditorKit

protected EditorKit createDefaultEditorKit()

首次创建组件时，创建默认的编辑器工具包 (PlainEditorKit)。

返回：

编辑器工具包

getEditorKit

public EditorKit getEditorKit()

获取用于处理内容的、当前已安装的工具包。如有必要，可调用 createDefaultEditorKit 来安装默认的工具包。

返回：

编辑器工具包

getContentType

public final String getContentType()

获得设置此编辑器当前要处理的内容类型。将其定义为与当前已安装的 EditorKit 相关联的类型。

返回：

内容类型，如果没有编辑器工具包集，则返回 null

setContentType

public final void setContentType(String type)

设置此编辑器所处理的内容类型。如果可以成功地找到编辑器工具包，则调用 getEditorKitForContentType，然后调用 setEditorKit。作为直接调用 setEditorKit 的一种替代方式，这是可用的最便捷的方法。

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

参数：

type - 支持内容编辑的非 null mime 类型

抛出：

NullPointerException - 如果 type 参数为 null

另请参见：

getContentType()

setEditorKit

public void setEditorKit(EditorKit kit)

设置当前为处理内容而安装的工具包。这是建立编辑器内容类型的绑定 (bound) 属性。首先卸载所有旧的工具包，然后如果 kit 不为 null，则安装新的工具包并为其创建默认文档。调用 setEditorKit 时始终激发 PropertyChange 事件 ("editorKit")。

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

参数：

kit - 所需的编辑器行为

另请参见：

getEditorKit()

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)

用由给定字符串表示的新内容替换当前选中的内容。如果没有选中的内容，那么此操作就等效于插入给定文本。如果没有替换文本（也就是 content 字符串为空或为 null），那么就等效于移除当前的选择。替换文本具有当前为输入所定义的各种属性。如果该组件是不可编辑的，则发出蜂鸣声并返回。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参见 How to Use Threads。

覆盖：

类 JTextComponent 中的 replaceSelection

参数：

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 的内容类型

从以下版本开始：

1.3

getPreferredSize

public Dimension getPreferredSize()

返回该 JEditorPane 的首选大小。JEditorPane 的首选大小与超类的首选大小稍微有所不同。如果视口 (viewport) 的大小已经小于组件的最低大小，则用于跟踪宽度或高度的可滚动定义将变为 false。默认的视口布局将给出首选大小，并且该大小在可滚动定义正在进行跟踪的情况下是不需要的。在这种情况下，将正常的 首选大小调整为最低大小。这就允许将 HTML 表缩小为其最低大小，然后以其最低大小进行布局，而不再做进一步的缩小。

覆盖：

类 JComponent 中的 getPreferredSize

返回：

包含首选大小的 Dimension

另请参见：

JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

setText

public void setText(String t)

将此 TextComponent 的文本设置为指定内容，预期以此编辑器的内容类型格式提供该内容。例如，如果将类型设置为 text/html，则应按照 HTML 指定该字符串。

实现此方法可移除当前文档的内容，并通过使用当前的 EditorKit 分析给定字符串来替换该内容。这提供了超类的语义，方法是不更改模型，同时支持当前在此组件上所设置的内容类型。前提是以前的内容相对较少，并且以前的内容没有副作用。可以违反这两个前提，但这会导致不需要的结果。为了避免发生此情况，可用 getEditorKit().createDefaultDocument() 创建一个新文档，并用该新文档替换现有的 Document。然后就可以确保以前的 Document 没有任何遗留的状态。

1. 保留现有的模型意味着去除旧的视图，并创建一个新视图，而替换文档则可避免去除旧的视图。
2. 某些格式（如 HTML）可将各种内容放入文档，而这些内容可以影响以后的内容。HTML 可以具有嵌入的样式信息，这将意外地影响后面安装的内容。

加载带有字符串的此组件的另一种方式是创建一个 StringReader 并调用 read 方法。在这种情况下，使用字符串内容初始化模型后将替换该模型。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参阅 How to Use Threads。

覆盖：

类 JTextComponent 中的 setText

参数：

t - 要设置的新文本；如果为 null，则删除旧的文本

另请参见：

getText()

getText

public String getText()

根据此编辑器的内容类型返回此 TextComponent 中所包含的文本。如果试图检索文本的同时抛出异常，则返回 null。实现此方法以调用带有 StringWriter 的 JTextComponent.write 。

覆盖：

类 JTextComponent 中的 getText

返回：

文本

另请参见：

setText(java.lang.String)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

如果某个视口始终应该强迫此 Scrollable 的宽度符合该视口的宽度，则返回 true。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportWidth

覆盖：

类 JTextComponent 中的 getScrollableTracksViewportWidth

返回：

如果某个视口始终应该强迫 Scrollable 的宽度符合其宽度，则返回 true；否则返回 false

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()

如果某个视口始终应该强迫此 Scrollable 的高度符合该视口的高度，则返回 true。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportHeight

覆盖：

类 JTextComponent 中的 getScrollableTracksViewportHeight

返回：

如果某个视口始终应该强迫 Scrollable 的高度符合其高度，则返回 true；否则返回 false

paramString

protected String paramString()

返回此 JEditorPane 的字符串表示形式。此方法仅在进行调试的时候使用，对于各个实现，所返回字符串的内容和格式可能有所不同。返回的字符串可能为空，但不可能为 null。

覆盖：

类 JTextComponent 中的 paramString

返回：

此 JEditorPane 的字符串表示形式

getAccessibleContext

public AccessibleContext getAccessibleContext()

获取与此 JEditorPane 关联的 AccessibleContext。对于编辑器窗格，AccessibleContext 采用 AccessibleJEditorPane 的形式。必要时创建新的 AccessibleJEditorPane 实例。

指定者：

接口 Accessible 中的 getAccessibleContext

覆盖：

类 JTextComponent 中的 getAccessibleContext

返回：

AccessibleJEditorPane，充当此 JEditorPane 的 AccessibleContext

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。