模块  java.desktop
软件包  javax.swing.text.html

Class HTMLDocument

  • 实现的所有接口
    SerializableDocumentStyledDocument

    public class HTMLDocument
    extends DefaultStyledDocument
    一个模拟HTML的文档。 此模型的目的是支持浏览和编辑。 因此,默认情况下,HTML文档描述的结构不会完全复制。 默认情况下建模的元素结构由类HTMLDocument.HTMLReader构建,该类实现了解析器所期望的HTMLEditorKit.ParserCallback协议。 要更改结构,可以HTMLReader ,并重新实现方法getReader(int)以返回新的读取器实现。 有关创建的默认结构的详细信息,请参阅HTMLReader的文档。 目的是文档是无损的(尽管再现HTML格式可能导致不同的格式)。

    该文档仅模拟HTML,并且不会尝试在其中存储视图属性。 元素由StyleContext.NameAttribute属性标识,该属性应始终具有标识元素类型的类型HTML.Tag的值。 一些元素(例如注释)被合成。 HTMLFactory使用此属性来确定要构建的视图类型。

    本文档支持增量加载。 TokenThreshold属性控制在尝试更新文档的元素结构之前缓冲了多少解析。 此属性由EditorKit设置,以便子类可以禁用它。

    Base属性确定用于解析相对URL的URL。 默认情况下,如果属性的值是URL, Document.StreamDescriptionProperty 如果遇到<BASE>标记,则base将成为该标记指定的URL。 因为基本URL是属性,所以它当然可以直接设置。

    此文档的默认内容存储机制是间隙缓冲区( GapContent )。 可以使用实现Content的构造函数来提供替代Content

    修改HTMLDocument

    除了Document和StyledDocument提供的用于改变HTMLDocument的方法之外,HTMLDocument还提供了许多便利方法。 可以使用以下方法将HTML内容插入现有文档。

    以下示例说明了使用这些方法。 每个示例都假定HTML文档按以下方式初始化:

      JEditorPane p = new JEditorPane();
     p.setContentType("text/html");
     p.setText("..."); // Document text is provided below.
     HTMLDocument d = (HTMLDocument) p.getDocument(); 

    使用以下HTML内容:

      <html>
       <head>
         <title>An example HTMLDocument</title>
         <style type="text/css">
           div { background-color: silver; }
           ul { color: blue; }
         </style>
       </head>
       <body>
         <div id="BOX">
           <p>Paragraph 1</p>
           <p>Paragraph 2</p>
         </div>
       </body>
     </html> 

    修改HTML文档的所有方法都需要Element 可以使用方法getElement(Element e, Object attribute, Object value)从HTML文档获得元素。 它以深度优先顺序返回包含具有给定值的指定属性的第一个后代元素。 例如, d.getElement(d.getDefaultRootElement(), StyleConstants.NameAttribute, HTML.Tag.P)返回第一个段落元素。

    用于定位元素的便利捷径是方法getElement(String) ; 返回其ID属性与指定值匹配的元素。 例如, d.getElement("BOX")返回DIV元素。

    getIterator(HTML.Tag t)方法还可用于查找文档中所有出现的指定HTML标记。

    插入元素

    可以使用方法insertAfterStartinsertBeforeEnd在任何非叶元素的现有子元素之前或之后插入元素。 例如,如果eDIV元素,则d.insertAfterStart(e, "<ul><li>List Item</li></ul>")在第一个段落之前插入列表, d.insertBeforeEnd(e, "<ul><li>List Item</li></ul>")在最后一个段落之后插入列表。 DIV块成为新插入元素的父级。

    可以使用方法insertBeforeStartinsertAfterEnd在任何元素之前或之后插入兄弟元素。 例如,如果eDIV元件, d.insertBeforeStart(e, "<ul><li>List Item</li></ul>")所述前插入物的列表DIV元件,和d.insertAfterEnd(e, "<ul><li>List Item</li></ul>")插入后的列表DIV元件。 新插入的元素成为DIV元素的兄弟元素。

    替换元素

    可以使用方法setInnerHTMLsetOuterHTML替换元素及其所有后代。 例如,如果eDIV元素,则d.setInnerHTML(e, "<ul><li>List Item</li></ul>")将所有子段落替换为列表, d.setOuterHTML(e, "<ul><li>List Item</li></ul>")将替换DIV元素本身。 在后一种情况下,列表的父级是BODY元素。

    摘要

    下表显示了示例文档和上述各种方法的结果。

    HTML Content of example above Example insertAfterStart insertBeforeEnd insertBeforeStart insertAfterEnd setInnerHTML setOuterHTML

    Paragraph 1

    Paragraph 2

    • List Item

    Paragraph 1

    Paragraph 2

    Paragraph 1

    Paragraph 2

    • List Item
    • List Item

    Paragraph 1

    Paragraph 2

    Paragraph 1

    Paragraph 2

    • List Item
    • List Item
    • List Item

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

    另请参见:
    Serialized Form
    • 字段详细信息

      • AdditionalComments

        public static final String AdditionalComments
        文档属性键值。 键的值将是一个字符串向量,它是在正文中找不到的注释。
        另请参见:
        常数字段值
    • 构造方法详细信息

      • HTMLDocument

        public HTMLDocument()
        使用默认缓冲区大小和默认值StyleSheet构造HTML文档。 这是构造函数HTMLDocument(Content, StyleSheet)的便捷方法。
      • HTMLDocument

        public HTMLDocument​(StyleSheet styles)
        使用默认内容存储实现和指定的样式/属性存储机制构造HTML文档。 这是构造函数HTMLDocument(Content, StyleSheet)的便捷方法。
        参数
        styles - 款式
      • HTMLDocument

        public HTMLDocument​(AbstractDocument.Content c,
                            StyleSheet styles)
        使用给定的内容存储实现和给定的样式/属性存储机制构造HTML文档。
        参数
        c - 内容的容器
        styles - 样式
    • 方法详细信息

      • getReader

        public HTMLEditorKit.ParserCallback getReader​(int pos)
        获取解析器以便在使用HTML加载文档时使用。 实现此方法是为了返回HTMLDocument.HTMLReader的实例。 子类可以重新实现此方法,以根据需要更改文档的结构。 (例如,处理自定义标记,或在结构上表示字符样式元素。)
        参数
        pos - 起始位置
        结果
        解析器用来加载文档的阅读器
      • getReader

        public HTMLEditorKit.ParserCallback getReader​(int pos,
                                                      int popDepth,
                                                      int pushDepth,
                                                      HTML.Tag insertTag)
        返回用于使用HTML加载文档的解析器的阅读器。 实现此方法是为了返回HTMLDocument.HTMLReader的实例。 子类可以重新实现此方法,以根据需要更改文档的结构。 (例如,处理自定义标记,或在结构上表示字符样式元素。)

        这是getReader(int, int, int, HTML.Tag, TRUE)的便捷方法。

        参数
        pos - 起始位置
        popDepth - 插入前生成的 ElementSpec.EndTagTypes的数量
        pushDepth -数量 ElementSpec.StartTagTypes用的方向 ElementSpec.JoinNextDirection应该插入之前生成,但已经生成了结束标记后
        insertTag - 开始插入文档的第一个标记
        结果
        解析器用来加载文档的阅读器
      • getBase

        public URL getBase()
        返回解析相对URL的位置。 默认情况下,如果文档是从URL加载的,那么这将是文档的URL。 如果找到并且可以解析基本标记,则它将用作基本位置。
        结果
        基地位置
      • setBase

        public void setBase​(URL u)
        设置解析相对URL的位置。 默认情况下,如果文档是从URL加载的,那么这将是文档的URL。 如果找到并且可以解析基本标记,则它将用作基本位置。

        这也将StyleSheet的基础设置为u以及文档的基础。

        参数
        u - 所需的基本URL
      • insert

        protected void insert​(int offset,
                              DefaultStyledDocument.ElementSpec[] data)
                       throws BadLocationException
        批量插入新元素。 这是元素在文档中的创建方式。 解析确定需要什么结构,并将规范创建为一组描述编辑的令牌,同时使文档不受写锁定。 然后,读取器可以突发地调用该方法以获得更短持续时间的写锁定(即,当文档实际被改变时)。
        重写:
        insert在类 DefaultStyledDocument
        参数
        offset - 起始偏移量
        data - 元素数据
        异常
        BadLocationException - 如果给定位置不代表关联文档中的有效位置。
      • create

        protected void create​(DefaultStyledDocument.ElementSpec[] data)
        用给定的元素规范替换文档的内容。 如果以突发方式完成加载,则在插入之前调用此方法。 如果在一次突发中完全加载文档,则这是唯一被调用的方法。
        重写:
        create在类 DefaultStyledDocument
        参数
        data - 文档的新内容
      • setParagraphAttributes

        public void setParagraphAttributes​(int offset,
                                           int length,
                                           AttributeSet s,
                                           boolean replace)
        设置段落的属性。

        虽然大多数Swing方法都不是,但这种方法是线程安全的。 有关更多信息,请参阅Concurrency in Swing

        Specified by:
        setParagraphAttributes在界面 StyledDocument
        重写:
        setParagraphAttributes在类 DefaultStyledDocument
        参数
        offset - 段落的偏移量(必须至少为0)
        length - 受影响的字符数(必须至少为0)
        s - 属性
        replace - 是替换现有属性还是合并它们
      • getStyleSheet

        public StyleSheet getStyleSheet()
        使用HTML文档本身中指定的特定于文档的显示规则(CSS)获取 StyleSheet
        结果
        StyleSheet
      • getIterator

        public HTMLDocument.Iterator getIterator​(HTML.Tag t)
        获取指定HTML标记的迭代器。 这可以用于迭代包含的锚集,或迭代输入元素。
        参数
        t - 要求的 HTML.Tag
        结果
        给定HTML标记的 Iterator
        另请参见:
        HTML.Tag
      • createLeafElement

        protected Element createLeafElement​(Element parent,
                                            AttributeSet a,
                                            int p0,
                                            int p1)
        创建直接表示文本的文档叶元素(没有任何子元素)。 实现此方法是为了返回HTMLDocument.RunElement类型的元素。
        重写:
        createLeafElement在类 AbstractDocument
        参数
        parent - 父元素
        a - 元素的属性
        p0 - 范围的开头(必须至少为0)
        p1 - 范围的结尾(必须至少为p0)
        结果
        新元素
      • createBranchElement

        protected Element createBranchElement​(Element parent,
                                              AttributeSet a)
        创建一个文档分支元素,可以包含其他元素。 实现此方法是为了返回HTMLDocument.BlockElement类型的元素。
        重写:
        createBranchElement在课程 AbstractDocument
        参数
        parent - 父元素
        a - 属性
        结果
        元素
      • setTokenThreshold

        public void setTokenThreshold​(int n)
        在尝试更新文档元素结构之前设置要缓冲的标记数。
        参数
        n - 要缓冲的令牌数
      • getTokenThreshold

        public int getTokenThreshold()
        获取在尝试更新文档元素结构之前要缓冲的标记数。 默认值为Integer.MAX_VALUE
        结果
        要缓冲的令牌数
      • setPreservesUnknownTags

        public void setPreservesUnknownTags​(boolean preservesTags)
        确定解析器如何处理未知标记。 如果设置为true,则将未知标记放入模型中,否则将删除它们。
        参数
        preservesTags - 如果应在模型中保存未知标记, preservesTags true,否则将删除标记
        另请参见:
        HTML.Tag
      • getPreservesUnknownTags

        public boolean getPreservesUnknownTags()
        返回解析器遇到未知标记时观察到的行为。
        结果
        如果在解析时要保留未知标记,则为true
        另请参见:
        HTML.Tag
      • processHTMLFrameHyperlinkEvent

        public void processHTMLFrameHyperlinkEvent​(HTMLFrameHyperlinkEvent e)
        处理由HTML框架中的文档生成的HyperlinkEvents 如参数所示, HyperlinkEvent类型为HTMLFrameHyperlinkEvent 除了HyperlinkEvent包含的典型信息HyperlinkEvent ,此事件还包含与发生单击的框架(源元素)和目标名称对应的元素。 目标名称有4个可能的值:
        • _自
        • _parent
        • _最佳
        • 命名框架
        如果target是_self,则操作是更改HTML.Attribute.SRC属性的值并触发ChangedUpdate事件。

        如果目标是_parent,则它删除父元素(<FRAMESET>元素),并插入新的<FRAME>元素,并将其HTML.Attribute.SRC属性设置为具有等于目标URL的值,并触发RemovedUpdateInsertUpdate

        如果目标是_top,则此方法不执行任何操作。 在帧的视图的实现中,即FrameView ,处理_top的处理。 鉴于_top意味着替换整个文档,因此在文档之外处理它将替换它是有意义的。

        如果目标是命名框架,则在元素层次结构中搜索名称等于目标的元素,更新其HTML.Attribute.SRC属性并触发ChangedUpdate事件。

        参数
        e - 活动
      • setParser

        public void setParser​(HTMLEditorKit.Parser parser)
        设置将html插入现有文档的方法使用的解析器,例如setInnerHTMLsetOuterHTML

        HTMLEditorKit.createDefaultDocument将为您设置解析器。 如果您手动创建HTMLDocument ,请确保并相应地设置解析器。

        参数
        parser - 用于文本插入的解析器
        从以下版本开始:
        1.3
      • getParser

        public HTMLEditorKit.Parser getParser()
        返回将HTML插入现有文档时使用的解析器。
        结果
        用于文本插入的解析器
        从以下版本开始:
        1.3
      • setInnerHTML

        public void setInnerHTML​(Element elem,
                                 String htmlText)
                          throws BadLocationException,
                                 IOException
        用指定为HTML字符串的内容替换给定元素的子元素。

        这将被视为至少两个事件,n个插入后跟一个删除。

        请考虑以下结构( elem参数以粗体显示 )。

          <body>
               |
             <div>
              /  \
            <p>   <p> 

        调用setInnerHTML(elem, "<ul><li>")产生以下结构(新元素为蓝色 )。

          <body>
               |
             <div>
                 \
                 <ul>
                   \
                   <li> 

        参数elem不能是叶元素,否则抛出IllegalArgumentException 如果elemhtmlText参数为null ,则不会对文档进行任何更改。

        为使其正常工作,文档必须设置为HTMLEditorKit.Parser 如果文档是通过createDefaultDocument方法从HTMLEditorKit创建的,则会出现这种情况。

        参数
        elem - 将替换其子项的分支元素
        htmlText - 要解析并分配给 elem的字符串
        异常
        IllegalArgumentException - 如果 elem是一张树叶
        IllegalStateException - 如果尚未定义 HTMLEditorKit.Parser
        BadLocationException - 如果由于结构问题而无法更换
        IOException - 如果发生I / O异常
        从以下版本开始:
        1.3
      • setOuterHTML

        public void setOuterHTML​(Element elem,
                                 String htmlText)
                          throws BadLocationException,
                                 IOException
        将父元素中的给定元素替换为指定为HTML字符串的内容。

        这将被视为至少两个事件,n个插入后跟一个删除。

        当更换叶子时,这将尝试确保在需要时存在换行符。 这可能导致插入额外的元素。 考虑一下,如果要用<img>替换包含换行符的字符元素,这将创建两个元素,一个用于图像,另一个用于换行。

        如果你试图长度替换元素,你很可能会得到两个元素,例如setOuterHTML(getCharacterElement (getLength()), "blah")将在结尾处产生两个叶元素,一个代表'blah',另一个代表end元素。

        请考虑以下结构( elem参数以粗体显示 )。

          <body>
               |
             <div>
              /  \
            <p>   <p> 

        调用setOuterHTML(elem, "<ul><li>")产生以下结构(新元素为蓝色 )。

          <body>
              |
             <ul>
               \
               <li> 

        如果elemhtmlText参数为null ,则不会对文档进行任何更改。

        为使其正常工作,文档必须具有HTMLEditorKit.Parser集。 如果文档是通过createDefaultDocument方法从HTMLEditorKit创建的,则会出现这种情况。

        参数
        elem - 要替换的元素
        htmlText - 要解析和插入的字符串代替 elem
        异常
        IllegalStateException - 如果尚未设置HTMLEditorKit.Parser
        BadLocationException - 如果由于结构问题而无法更换
        IOException - 如果发生I / O异常
        从以下版本开始:
        1.3
      • insertAfterStart

        public void insertAfterStart​(Element elem,
                                     String htmlText)
                              throws BadLocationException,
                                     IOException
        在元素的开头插入指定为字符串的HTML。

        请考虑以下结构( elem参数以粗体显示 )。

          <body>
               |
             <div>
              /  \
            <p>   <p> 

        调用insertAfterStart(elem, "<ul><li>")产生以下结构(新元素为蓝色 )。

          <body>
                  |
                <div>
               /  |  \
            <ul> <p> <p>
             /
          <li> 

        insertBeforeStart方法不同,新元素成为指定元素的元素,而不是兄弟元素。

        参数elem不能是叶元素,否则抛出IllegalArgumentException 如果elemhtmlText参数为null ,则不会对文档进行任何更改。

        为使其正常工作,文档必须具有HTMLEditorKit.Parser设置。 如果文档是通过createDefaultDocument方法从HTMLEditorKit创建的,则会出现这种情况。

        参数
        elem - 作为新文本的根的分支元素
        htmlText - 要解析并分配给 elem的字符串
        异常
        IllegalArgumentException - 如果 elem是一片叶子
        IllegalStateException - 如果尚未在文档上设置HTMLEditorKit.Parser
        BadLocationException - 如果由于结构问题而无法插入
        IOException - 如果发生I / O异常
        从以下版本开始:
        1.3
      • insertBeforeEnd

        public void insertBeforeEnd​(Element elem,
                                    String htmlText)
                             throws BadLocationException,
                                    IOException
        在元素末尾插入指定为字符串的HTML。

        如果elem的子elem是叶子,并且elem.getEndOffset() - 1处的elem.getEndOffset() - 1是换行符,则会在换行符之前插入,以便在换行符之后没有文本。

        请考虑以下结构( elem参数以粗体显示 )。

          <body>
               |
             <div>
              /  \
            <p>   <p> 

        调用insertBeforeEnd(elem, "<ul><li>")产生以下结构(新元素为蓝色 )。

          <body>
                  |
                <div>
               /  |  \
             <p> <p> <ul>
                       \
                       <li> 

        insertAfterEnd方法不同,新元素成为指定元素的元素,而不是兄弟元素。

        参数elem不能是叶元素,否则抛出IllegalArgumentException 如果elemhtmlText参数为null ,则不会对文档进行任何更改。

        为使其正常工作,文档必须设置为HTMLEditorKit.Parser 如果文档是通过createDefaultDocument方法从HTMLEditorKit创建的,则会出现这种情况。

        参数
        elem - 要作为新文本的根的元素
        htmlText - 要解析并分配给 elem的字符串
        异常
        IllegalArgumentException - 如果 elem是一片叶子
        IllegalStateException - 如果尚未在文档上设置HTMLEditorKit.Parser
        BadLocationException - 如果由于结构问题而无法插入
        IOException - 如果发生I / O异常
        从以下版本开始:
        1.3
      • insertBeforeStart

        public void insertBeforeStart​(Element elem,
                                      String htmlText)
                               throws BadLocationException,
                                      IOException
        在给定元素的开头之前插入指定为字符串的HTML。

        请考虑以下结构( elem参数以粗体显示 )。

          <body>
               |
             <div>
              /  \
            <p>   <p> 

        调用insertBeforeStart(elem, "<ul><li>")产生以下结构(新元素为蓝色 )。

          <body>
                 /  \
              <ul> <div>
               /    /  \
             <li> <p>  <p> 

        insertAfterStart方法不同,新元素成为指定元素的兄弟 ,而不是子元素。

        如果elemhtmlText参数为null ,则不对文档进行任何更改。

        为使其正常工作,文档必须具有HTMLEditorKit.Parser集。 如果文档是通过createDefaultDocument方法从HTMLEditorKit创建的,则会出现这种情况。

        参数
        elem - 之前插入内容的元素
        htmlText - 要在 elem之前解析和插入的字符串
        异常
        IllegalStateException - 如果尚未在文档上设置HTMLEditorKit.Parser
        BadLocationException - 如果由于结构问题而无法插入
        IOException - 如果发生I / O异常
        从以下版本开始:
        1.3
      • insertAfterEnd

        public void insertAfterEnd​(Element elem,
                                   String htmlText)
                            throws BadLocationException,
                                   IOException
        在给定元素结束后插入指定为字符串的HTML。

        请考虑以下结构( elem参数以粗体显示 )。

          <body>
               |
             <div>
              /  \
            <p>   <p> 

        调用insertAfterEnd(elem, "<ul><li>")产生以下结构(新元素为蓝色 )。

          <body>
                 /  \
              <div> <ul>
               / \    \
             <p> <p>  <li> 

        insertBeforeEnd方法不同,新元素成为指定元素的兄弟 ,而不是子元素。

        如果elemhtmlText参数为null ,则不对文档进行任何更改。

        为使其正常工作,文档必须设置为HTMLEditorKit.Parser 如果文档是通过createDefaultDocument方法从HTMLEditorKit创建的,则会出现这种情况。

        参数
        elem - 之后插入内容的元素
        htmlText - 在 elem之后要解析和插入的字符串
        异常
        IllegalStateException - 如果尚未在文档上设置HTMLEditorKit.Parser
        BadLocationException - 如果由于结构问题而无法插入
        IOException - 如果发生I / O异常
        从以下版本开始:
        1.3
      • getElement

        public Element getElement​(String id)
        返回具有给定标识Attribute的元素。 如果找不到该元素,则返回null 请注意,此方法适用于Attribute而不是字符标记。 在以下HTML代码段中: <a id="HelloThere">属性为“id”,字符标记为“a”。 这是getElement(RootElement, HTML.Attribute.id, id)的便捷方法。 这不是线程安全的。
        参数
        id - 表示所需 Attribute的字符串
        结果
        与指定的元素 Attributenull ,如果它不能被发现,或 null如果 idnull
        从以下版本开始:
        1.3
        另请参见:
        HTML.Attribute
      • getElement

        public Element getElement​(Element e,
                                  Object attribute,
                                  Object value)
        返回包含属性e的子元素attribute ,值value ,如果value ,则null 这不是线程安全的。
        参数
        e - 搜索开始的根元素
        attribute - 所需的 Attribute
        value - 指定的 Attribute的值
        结果
        具有指定的 Attribute和指定的 valuenull如果找不到)
        从以下版本开始:
        1.3
        另请参见:
        HTML.Attribute