javax.swing.text.html
类 HTMLDocument

java.lang.Object
  javax.swing.text.AbstractDocument
      javax.swing.text.DefaultStyledDocument
          javax.swing.text.html.HTMLDocument

所有已实现的接口：

Serializable, Document, StyledDocument

public class HTMLDocument
extends DefaultStyledDocument

对 HTML 进行建模的文档。此模型的目的是支持浏览和编辑。因此，默认情况下 HTML 文档所描述的结构不是精确一致的。默认情况下被建模的元素结构是通过 HTMLDocument.HTMLReader 类构建的，此类实现了解析器所期望的 HTMLEditorKit.ParserCallback 协议。要更改结构，可以创建 HTMLReader 的子类，并且重新实现 getReader(int) 方法以返回新的 reader 实现。有关创建默认结构的细节，请参考 HTMLReader 文档。其目的是使文档无丢失（non-lossy）（虽然重新生成 HTML 格式可能导致出现不同的格式）。

文档只对 HTML 建模，并且不尝试在其中存储视图属性。元素由 StyleContext.NameAttribute 属性标识，此属性应该始终有一个标识元素种类的 HTML.Tag 类型值。某些元素（例如注释）是合成的。HTMLFactory 使用此属性来确定要构建哪种视图。

此文档支持增量加载。TokenThreshold 属性控制在试图更新文档的元素结构之前要缓冲的解析数量。通过 EditorKit 来设置此属性，以便子类可以禁用它。

Base 属性根据解析哪些相对 URL 来确定 URL。默认情况下，如果属性值是 URL，则这将是 Document.StreamDescriptionProperty。如果遇到 <BASE> 标记，则基本 URL 将成为该标记所指定的 URL。因为基本 URL 是一个属性，因此毫无疑问可以直接设置它。

此文档的默认内容存储机制是一个间隙缓冲区 (GapContent)。通过使用带有 Content 实现的构造方法，可以提供某些替代方法。

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

AdditionalComments

public static final String AdditionalComments

文档属性键值。键值将是 String 的 Vector，这是正文中没有的注释。

另请参见：

常量字段值

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 的文档时所用解析器的 reader。实现它的目的是为了返回 HTMLDocument.HTMLReader 的一个实例。如果需要，子类可以重新实现此方法来更改文档获取结构的方式。（例如，处理自定义标记，或者从结构上表示字符样式元素。）

参数：

pos - 起始位置

返回：

解析器用于加载文档的 reader

getReader

public HTMLEditorKit.ParserCallback getReader(int pos,
                                              int popDepth,
                                              int pushDepth,
                                              HTML.Tag insertTag)

返回加载带有 HTML 的文档时所用解析器的 reader。实现它的目的是为了返回 HTMLDocument.HTMLReader 的一个实例。如果需要，子类可以重新实现此方法来更改文档获取结构的方式。（例如，处理自定义标记，或者从结构上表示字符样式元素。）

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

参数：

popDepth - 插入前要生成的 ElementSpec.EndTagTypes 的数量

pushDepth - 插入前但生成结束标记之后，应该生成的 ElementSpec.StartTagTypes 的数量（它具有 ElementSpec.JoinNextDirection 方向）

insertTag - 开始插入文档的首个标记

返回：

解析器用于加载文档的 reader

getBase

public URL getBase()

返回解析相对 URL 所根据的位置。默认情况下，如果文档是从 URL 加载的，则这将是文档的 URL。如果找到 BASE 标记并可以对其进行解析，则它将充当基本位置。

返回：

基本位置

setBase

public void setBase(URL u)

设置解析相对 URL 所根据的位置。默认情况下，如果文档是从 URL 加载的，则这将是文档的 URL。如果找到 BASE 标记并可以对其进行解析，则它将充当基本位置。

这还将 StyleSheet 的基本 URL 以及文档的基本 URL 设置为 u。

参数：

u - 所需的基本 URL

insert

protected void insert(int offset,
                      DefaultStyledDocument.ElementSpec[] data)
               throws BadLocationException

批量插入新元素。这是在文档中创建元素的方式。通过解析确定所需的结构，并创建作为标记（它描述了编辑）集合的规范，同时保留文档的写入锁定打开。然后 reader 以突发的形式调用此方法，以获得短时（也就是正在实际更改文档时）的写入锁定。

覆盖：

类 DefaultStyledDocument 中的 insert

参数：

offset - 起始偏移量

data - 元素数据

抛出：

BadLocationException - 如果给定的位置在关联文档中不是一个有效位置。

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)

由于插入文本而导致更新文档的结构。这将在写入锁定中发生。此实现仅解析换行处插入的内容，并构建元素缓冲区的指令集。

覆盖：

类 DefaultStyledDocument 中的 insertUpdate

参数：

chng - 文档更改的描述

attr - 属性

create

protected void create(DefaultStyledDocument.ElementSpec[] data)

替换具有给定元素规范的文档内容。如果加载是突发进行的，则在插入前调用此方法。如果在一次突发加载中完全加载文档，则这是唯一调用的方法。

覆盖：

类 DefaultStyledDocument 中的 create

参数：

data - 文档的新内容

setParagraphAttributes

public void setParagraphAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)

设置段落属性。

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

指定者：

接口 StyledDocument 中的 setParagraphAttributes

覆盖：

类 DefaultStyledDocument 中的 setParagraphAttributes

参数：

offset - 段落中的偏移量（必须至少为 0）

length - 受影响的字符数（必须至少为 0）

s - 属性

replace - 是替换现有属性，还是合并它们

getStyleSheet

public StyleSheet getStyleSheet()

获取具有特定于文档的显示规则（CSS）的 StyleSheet，其中这些规则是在 HTML 文档本身中指定的。

返回：

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 类型的元素。

覆盖：

类 AbstractDocument 中的 createLeafElement

参数：

parent - 父元素

a - 元素属性

p0 - 该范围的开始处（必须至少为 0）

p1 - 该范围的结尾处（必须至少为 p0）

返回：

新元素

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)

创建文档分支元素，它可以包含其他元素。实现它的目的是为了返回 HTMLDocument.BlockElement 类型的元素。

覆盖：

类 AbstractDocument 中的 createBranchElement

参数：

parent - 父元素

a - 属性

返回：

元素

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()

创建用于表示默认文档结构的根元素。

覆盖：

类 DefaultStyledDocument 中的 createDefaultRoot

返回：

基本元素

setTokenThreshold

public void setTokenThreshold(int n)

设置在试图更新文档元素结构之前要缓冲的标记数。

参数：

n - 要缓冲的标记数

getTokenThreshold

public int getTokenThreshold()

获取在试图更新文档元素结构之前要缓冲的标记数。默认值为 Integer.MAX_VALUE。

返回：

要缓冲的标记数

setPreservesUnknownTags

public void setPreservesUnknownTags(boolean preservesTags)

确定解析器如何处理未知标记。如果设置为 true，则将未知标记放入模型中，否则删除它们。

参数：

preservesTags - 如果应该将未知标记保存到模型中，则为 true，否则删除这些标记

另请参见：

HTML.Tag

getPreservesUnknownTags

public boolean getPreservesUnknownTags()

返回在遇到未知标记时所观察到的解析器行为。

返回：

如果解析时要保留未知标记，则返回 true

另请参见：

HTML.Tag

processHTMLFrameHyperlinkEvent

public void processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent e)

处理 HTML 框架中的文档所生成的 HyperlinkEvents。HyperlinkEvent 类型为 HTMLFrameHyperlinkEvent（正如参数所说明的）。除 HyperlinkEvent 中所包含的典型信息之外，此事件还包含对应于发生单击事件的框架的元素（源元素）和目标名称。目标名称有 4 个可能值：

• _self
• _parent
• _top
• 已命名的框架

如果目标是 _self，则该操作将更改 HTML.Attribute.SRC 属性的值，并触发 ChangedUpdate 事件。

如果目标是 _parent，则它删除父元素（父元素是 <FRAMESET> 元素），插入一个新的 <FRAME> 元素，并将其 HTML.Attribute.SRC 属性设置为一个等于目标 URL 的值，并触发 RemovedUpdate 和 InsertUpdate。

如果目标是 _top，则此方法不执行任何操作。在框架视图（即 FrameView）的实现中，要对 _top 进行处理。给定该 _top 意味着替换整个文档，在它要替换的文档外部进行这项处理是有意义的。

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

参数：

e - 事件

setParser

public void setParser(HTMLEditorKit.Parser parser)

设置将 html 插入现有文档的方法所使用的解析器，例如 setInnerHTML 和 setOuterHTML。

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 个插入事件后跟一个移除事件。

为了让它正确工作，文档必须具有一个 HTMLEditorKit.Parser 集。如果文档是通过 createDefaultDocument 方法从 HTMLEditorKit 创建的，那么就是这种情况。

参数：

elem - 其子元素将被替换的分支元素

htmlText - 要被解析并分配给 elem 的字符串

抛出：

IllegalArgumentException - 如果 elem 是一个叶元素

IllegalStateException - 如果尚未定义 HTMLEditorKit.Parser

BadLocationException

IOException

从以下版本开始：

1.3

setOuterHTML

public void setOuterHTML(Element elem,
                         String htmlText)
                  throws BadLocationException,
                         IOException

用指定为 HTML 字符串的内容替换父元素中的给定元素。

这将至少包括两个事件，n 个插入事件后跟一个移除事件。

当替换叶元素时，这将试图确保存在一个新行（如果需要的话）。这可能导致插入额外的元素。考虑下面的情况，如果要用 <img> 替换一个包含新行的字符元素，那么这将创建两个元素，一个用于图像，另一个用于新行。

如果最后试图替换元素，则最有可能以两个元素结尾，例如，setOuterHTML(getCharacterElement (getLength()), "blah") 将导致结尾处有两个叶元素，一个表示 'blah'，而另一个则表示结尾元素。

为了让它正确工作，文档必须具有一个 HTMLEditorKit.Parser 集。如果文档是通过 createDefaultDocument 方法从 HTMLEditorKit 创建的，那么就是这种情况。

参数：

elem - 其子元素要被替换的分支元素

htmlText - 要被解析并分配给 elem 的字符串

抛出：

IllegalStateException - 如果尚未设置 HTMLEditorKit.Parser

BadLocationException

IOException

从以下版本开始：

1.3

insertAfterStart

public void insertAfterStart(Element elem,
                             String htmlText)
                      throws BadLocationException,
                             IOException

将指定为字符串的 HTML 插入元素的起始处。

为了让它正确工作，文档必须具有一个 HTMLEditorKit.Parser 集。如果文档是通过 createDefaultDocument 方法从 HTMLEditorKit 创建的，那么就是这种情况。

参数：

elem - 分支元素，它要作为新文本的根元素

htmlText - 要被解析并分配给 elem 的字符串

抛出：

IllegalStateException - 如果尚未在文档上设置 HTMLEditorKit.Parser

BadLocationException

IOException

从以下版本开始：

1.3

insertBeforeEnd

public void insertBeforeEnd(Element elem,
                            String htmlText)
                     throws BadLocationException,
                            IOException

将指定为字符串的 HTML 插入元素的结尾处。

如果 elem 的子元素是叶元素，并且 elem.getEndOffset() - 1 位置处的字符是一个新行符，则将内容插入到新行符的前面，以便新行符的后面没有文本。

为了让它正确工作，文档必须具有一个 HTMLEditorKit.Parser 集。如果文档是通过 createDefaultDocument 方法从 HTMLEditorKit 创建的，那么就是这种情况。

参数：

elem - 元素，它要作为新文本的根元素

htmlText - 要被解析并分配给 elem 的字符串

抛出：

IllegalStateException - 如果尚未在文档上设置 HTMLEditorKit.Parser

BadLocationException

IOException

从以下版本开始：

1.3

insertBeforeStart

public void insertBeforeStart(Element elem,
                              String htmlText)
                       throws BadLocationException,
                              IOException

将指定为字符串的 HTML 插入给定元素的起始处之前。

为了让它正确工作，文档必须具有一个 HTMLEditorKit.Parser 集。如果文档是通过 createDefaultDocument 方法从 HTMLEditorKit 创建的，那么就是这种情况。

参数：

elem - 元素，它要作为新文本的根元素

htmlText - 要被解析并分配给 elem 的字符串

抛出：

IllegalStateException - 如果尚未在文档上设置 HTMLEditorKit.Parser

BadLocationException

IOException

从以下版本开始：

1.3

insertAfterEnd

public void insertAfterEnd(Element elem,
                           String htmlText)
                    throws BadLocationException,
                           IOException

将指定为字符串的 HTML 插入给定元素的起始处之后。

为了让它正确工作，文档必须具有一个 HTMLEditorKit.Parser 集。如果文档是通过 createDefaultDocument 方法从 HTMLEditorKit 创建的，那么就是这种情况。

参数：

elem - 元素，它要作为新文本的根元素

htmlText - 要被解析并分配给 elem 的字符串

抛出：

IllegalStateException - 如果尚未在文档上设置 HTMLEditorKit.Parser

BadLocationException

IOException

从以下版本开始：

1.3

getElement

public Element getElement(String id)

返回具有给定 id Attribute 的元素。如果未找到元素，则返回 null。注意，此方法处理的是 Attribute，而不是 字符串标记。在下面的 HTML 片段中：<a id="HelloThere">，属性是 'id'，字符串标记是 'a'。这是 getElement(RootElement, HTML.Attribute.id, id) 的一个便捷方法。它不是线程安全的。

参数：

id - 表示所需 Attribute 的字符串

返回：

具有指定 Attribute 的元素，如果未找到，则返回 null，如果 id 为 null，则返回 null

从以下版本开始：

1.3

另请参见：

HTML.Attribute

getElement

public Element getElement(Element e,
                          Object attribute,
                          Object value)

返回 e（它包含具有值 value 的属性 attribute）的子元素，如果未找到，则返回 null。它不是线程安全的。

参数：

e - 根元素，从它开始进行搜索

attribute - 所需的 Attribute

value - 指定 Attribute 的值

返回：

具有指定 Attribute 和指定 value 的元素，如果未找到，则返回 null

从以下版本开始：

1.3

另请参见：

HTML.Attribute

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)

通知所有需要此事件类型的通知的已注册侦听器。使用传入此触发方法的参数延后创建事件实例。

覆盖：

类 AbstractDocument 中的 fireChangedUpdate

参数：

e - 事件

另请参见：

EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)

通知所有需要此事件类型的通知的已注册侦听器。使用传入此触发方法的参数延后创建事件实例。

覆盖：

类 AbstractDocument 中的 fireUndoableEditUpdate

参数：

e - 事件

另请参见：

EventListenerList

版权所有 2008 Sun Microsystems, Inc. 保留所有权利。请遵守GNU General Public License, version 2 only。