Module  java.desktop
软件包  javax.swing

Class JEditorPane

  • All Implemented Interfaces:
    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教程”一节中的 Using Text Components中找到使用编辑器窗格的操作信息和示例。

    该组件使用EditorKit的实现来完成其行为。 它有效地转化为适当的文本编辑器，用于提供给他们的内容。 编辑器在任何给定时间绑定的内容类型由当前安装的EditorKit确定。 如果内容设置为新的URL，则其类型用于确定应用于加载内容的EditorKit 。

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

    纯文本/
    纯文本是默认的，不能识别给出的类型。 在这种情况下使用的工具包是DefaultEditorKit的扩展，它生成一个包装的纯文本视图。
    text / html的
    HTML文字。 在这种情况下使用的工具包是提供HTML 3.2支持的类javax.swing.text.html.HTMLEditorKit 。
    文/ 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框架嵌入在文档中，典型的响应将是更改当前文档的一部分。 以下代码片段是一种可能的超链接侦听器实现，它专门处理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将被捕获。 然后使用新的Reader读取读取，该Reader使用ChangedCharSetException （即IOException ）中指定的字符集。
    换行
    有关如何处理换行符的讨论，请参阅DefaultEditorKit 。

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

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

    从以下版本开始：
    1.2
    另请参见：
    Serialized Form

    • 字段详细信息

      • W3C_LENGTH_UNITS

        public static final String W3C_LENGTH_UNITS
        用于指示是否将w3c compliant长度单位用于html呈现的客户端属性的键。

        默认情况下未启用; 以使其能够将客户端property设置为Boolean.TRUE 。

        从以下版本开始：
        1.5
        另请参见：
        Constant Field Values

      • HONOR_DISPLAY_PROPERTIES

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

        默认值根据外观而异; 使其能够将客户端property设置为Boolean.TRUE 。

        从以下版本开始：
        1.5
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • JEditorPane

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

      • JEditorPane

        public JEditorPane​(URL initialPage)
            throws IOException
        根据输入的指定URL创建一个 JEditorPane 。
        参数
        initialPage - 网址
        异常
        IOException - 如果URL是 null或无法访问

      • JEditorPane

        public JEditorPane​(String url)
            throws IOException
        根据包含URL规范的字符串创建一个 JEditorPane 。
        参数
        url - URL
        异常
        IOException - 如果网址是 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

        @BeanProperty(bound=false)
public HyperlinkListener[] getHyperlinkListeners​()
        返回使用addHyperlinkListener（）添加到此JEditorPane的所有 HyperLinkListener的数组。
        结果
        所有添加的 HyperLinkListener或一个空数组，如果没有添加听众
        从以下版本开始：
        1.4

      • fireHyperlinkUpdate

        public void fireHyperlinkUpdate​(HyperlinkEvent e)
        通知所有在此事件类型上通知有兴趣的听众。 这通常由当前安装的EditorKit调用，如果支持超链接的内容类型当前处于活动状态，并且具有链接的活动。 侦听器列表被最后处理。
        参数
        e - 事件
        另请参见：
        EventListenerList

      • 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返回的值，则该页面将使用该优先级加载到单独的线程上。

        如果文档被同步加载，则在安装到编辑器之前，它将被填入流中，并调用setDocument ，该对象被绑定并将触发属性更改事件。 如果抛出IOException ，部分加载的文档将被丢弃，文档或页面属性更改事件都将被触发。 如果文档已成功加载并安装，UI将会为其构建一个视图，然后在必要时将其滚动，然后页面属性更改事件将被触发。

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

        参数
        page - 网页的URL
        异常
        IOException - 对于 null或无效页面规范，或正在读取的流中的异常
        另请参见：
        getPage()

      • 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不会被解析。
        结果
        该网址，或 null如果没有

      • setPage

        public void setPage​(String url)
             throws IOException
        设置显示的当前URL。
        参数
        url - 显示的网址
        异常
        IOException - 对于 null或无效的URL规范

      • 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加载输入流时将使用该EditorKit 。 例如，如果类型被指定为text/html; charset=EUC-JP ，则使用EditorKit注册的text/html加载内容，并将提供给EditorKit的Reader加载到文档中将使用EUC-JP字符集来转换为unicode。 如果类型无法识别，内容将采用加载EditorKit纯文本注册， text/plain 。

        参数
        type - 非 null mime类型的内容编辑支持
        异常
        NullPointerException - 如果 type参数是 null
        另请参见：
        getContentType()

      • setEditorKit

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

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

        参数
        kit - 所需的编辑器行为
        另请参见：
        getEditorKit()

      • getEditorKitForContentType

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

        此方法可以重新实现，以使用其他类型的注册表。 例如，这可以重新实现为使用Java激活框架。

        参数
        type - 非 null内容类型
        结果
        编辑工具包

      • setEditorKitForContentType

        public void setEditorKitForContentType​(String type,
                                       EditorKit k)
        直接设置用于给定类型的编辑器工具包。 外观实现可能会与createEditorKitForContentType结合使用， 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的默认绑定。 该类将在实际需要时稍后动态加载，并且可以在尝试使用之前安全地更改，以避免加载不需要的类。 EditorKit的原型将用这种方法注册时加载Class.forName 。
        参数
        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)
        返回当前注册的 EditorKit的类型的类名 type 。
        参数
        type - 非 null内容类型
        结果
        一个 String包含 EditorKit类名 type
        从以下版本开始：
        1.3

      • getPreferredSize

        public Dimension getPreferredSize​()
        返回JEditorPane的首选大小。 JEditorPane的首选大小与超类的首选大小略有不同。 如果视口的大小已经变得小于组件的最小尺寸，则跟踪宽度或高度的可滚动定义将变为false。 默认的视口布局将给出首选的大小，而在可滚动跟踪的情况下不需要。 在这种情况下， 正常的优选尺寸被调整到最小尺寸。 这样可以让HTML表格缩小到最小尺寸，然后将其放在最小尺寸上，拒绝进一步缩小。
        重写：
        getPreferredSize在 JComponent
        结果
        一个包含首选大小的 Dimension
        另请参见：
        JComponent.setPreferredSize(java.awt.Dimension) ， ComponentUI

      • setText

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

        这是为了删除当前文档的内容，并通过使用当前的EditorKit解析给定的字符串来替换它们。 这通过不改变模型来提供超类的语义，同时支持当前在此组件上设置的内容类型。 假设以前的内容相对较小，并且以前的内容没有副作用。 这两个假设都可能被违反并导致不合需要的结果。 为避免这种情况，请创建一个新的文档， getEditorKit().createDefaultDocument() ，并用现有的Document替换新文档。 那么你以后会放心Document将不会有任何Document状态。

        1. 将现有的模式置于原位意味着旧视图将被拆除，并创建一个新视图，替换文档将避免旧视图的拆除。
        2. 某些格式（如HTML）可以将东西安装到文档中，这些内容可能会影响未来的内容。 HTML可以嵌入嵌入的样式信息，这将影响未来安装的下一个内容。

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

        重写：
        setText在 JTextComponent
        参数
        t - 要设置的新文本; 如果null旧文本将被删除
        另请参见：
        getText()

      • getText

        public String getText​()
        根据此编辑器的内容类型返回此TextComponent中包含的文本。 如果在尝试检索文本时抛出异常，将返回null 。 实现此方法来调用JTextComponent.write用StringWriter 。
        重写：
        getText在 JTextComponent
        结果
        文本
        另请参见：
        setText(java.lang.String)

      • paramString

        protected String paramString​()
        返回此JEditorPane的字符串表示JEditorPane 。 该方法仅用于调试目的，并且返回的字符串的内容和格式可能因实现而异。 返回的字符串可能为空，但可能不是null 。
        重写：
        paramString中的 JTextComponent
        结果
        这是 JEditorPane的字符串表示