JavaTM Platform
Standard Ed. 6

javax.swing.text.html
类 HTMLEditorKit

java.lang.Object
  继承者 javax.swing.text.EditorKit
      继承者 javax.swing.text.DefaultEditorKit
          继承者 javax.swing.text.StyledEditorKit
              继承者 javax.swing.text.html.HTMLEditorKit
所有已实现的接口:
Serializable, Cloneable, Accessible

public class HTMLEditorKit
extends StyledEditorKit
implements Accessible

Swing JEditorPane 文本组件通过称为 EditorKit 的插件机制来支持不同种类的内容。因为 HTML 是很流行的内容格式,因此默认提供了某种支持。此类提供了 HTML version 3.2(带有某些扩展)的默认支持,并正在向 version 4.0 迁移。不支持 <applet> 标记,但为 <object> 标记提供了某种支持。

提供 HTML EditorKit 有几个目的,这些目的影响了 HTML 的建模方式。并从基本方法上影响了其设计。

支持编辑
有一点看起来相当明显,即 JEditorPane 的插件应该提供编辑支持,但实际上需要考虑几点设计因素。有相当数量的 HTML 文档没有正确遵守 HTML 规范。如果要编辑这些文档,则必须在某种程度上进行标准化,使其具有正确的形式。此外,用户不希望面对过多的结构编辑,因此使用传统的文本编辑动作优先于使用 HTML 文档中精确定义的 HTML 结构。

HTMLDocument 类提供了 HTML 的建模。其文档描述了建模 HTML 的细节。编辑支持主要不利用 text 包。

可扩展的/可伸缩的
为了最大化此工具包的使用,我们付诸了大量努力使其具有可扩展性。这里是一些特性。
  1. 解析器是可替换的。默认解析器是基于 DTD 的 Hot Java 解析器。可以使用不同的 DTD,或者可以使用一个完全不同的解析器。要更改解析器,请重新实现 getParser 方法。首次请求默认解析器时动态加载它,因此如果使用了另一个解析器,则永远不会加载类文件。默认解析器在此包下面一个单独的包中,这个包称为 parser。
  2. 解析器驱动由 HTMLDocument 所提供的 ParserCallback。要更改回调,请创建 HTMLDocument 子类,并重新实现 createDefaultDocument 方法以返回生成不同 reader 的文档。reader 控制文档的结构。虽然在默认情况下 Document 提供了 HTML 支持,但并不妨碍它支持替代元素结构所产生的非 HTML 标记。
  3. 默认的模型视图是作为 View 实现的层次结构提供的,所以我们可以轻松地自定义如何显示某个特定元素,或者通过提供新的 View 实现来添加新元素类型的功能。默认的视图集合由 HTMLFactory 类提供。可以轻松地更改此方法,方法是创建 HTMLFactory 的子类或替换 HTMLFactory 类,并重新实现 getViewFactory 方法以返回替代的工厂。
  4. View 实现主要是清除保持在视图中的 CSS 属性。这就能够在看似极不相同的相同模型上映射多个视图。这对于打印是非常有用的。出于显示目的,对于大多数的 HTML 属性,要将 HTML 属性转换为 CSS 属性。这有助于使 View 实现更为通用。

异步加载
较大的文档涉及大量的解析工作,并需要一定时间来加载。默认情况下,此工具包生成异步加载的文档(如果使用 JEditorPane.setPage 来加载)。这由文档的一个属性来控制。这可以通过重写 createDefaultDocument 方法来更改。批处理工作由 HTMLDocument.HTMLReader 类完成。实际的工作由 text 包中的 DefaultStyledDocumentAbstractDocument 类完成。

根据当前 LAF 进行自定义
HTML 提供了已知的特性集,但没有准确指定显示特征。Swing 具有其外观实现的 theme 机制。外观应该在 HTML 视图中提供显示特征。例如,视力较差的用户需要高对比度和比典型字体更大的字体。

StyleSheet 类提供了这种支持。通过设置 EditorKit 上的 StyleSheet 属性,可以对 HTML 的表示产生很大影响。

无丢失
EditorKit 能够读取和保存文档。通常用户最希望的是在两个操作之间没有数据丢失。HTMLEditorKit 的策略是保存未识别或不必要可见的内容,以便随后可以写出它们。因此,HTML 文档的模型应该包含读取文档时所发现的所有信息。由于需要支持编辑,因此这在某些方面受到限制(例如有时必须将不正确的文档标准化)。指导原则是不应该丢失信息,但可以合成某些信息来生成更正确的模型,或者重新安排信息。


嵌套类摘要
static class HTMLEditorKit.HTMLFactory
          用于构建 HTML 视图的工厂。
static class HTMLEditorKit.HTMLTextAction
          提供某些便捷方法的抽象 Action,这些便捷方法对于将 HTML 插入现有文档可能很有用。
static class HTMLEditorKit.InsertHTMLTextAction
          InsertHTMLTextAction 可用于将任意 HTML 字符串插入现有 HTML 文档。
static class HTMLEditorKit.LinkController
          此类用于观察关联组件并在适当的时候触发该组件上的超链接事件。
static class HTMLEditorKit.Parser
          解析器要支持的接口。
static class HTMLEditorKit.ParserCallback
          解析结果驱动这些回调方法。
 
从类 javax.swing.text.StyledEditorKit 继承的嵌套类/接口
StyledEditorKit.AlignmentAction, StyledEditorKit.BoldAction, StyledEditorKit.FontFamilyAction, StyledEditorKit.FontSizeAction, StyledEditorKit.ForegroundAction, StyledEditorKit.ItalicAction, StyledEditorKit.StyledTextAction, StyledEditorKit.UnderlineAction
 
从类 javax.swing.text.DefaultEditorKit 继承的嵌套类/接口
DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction
 
字段摘要
static String BOLD_ACTION
          粗体动作标识符
static String COLOR_ACTION
          Color 选择动作标识符(颜色作为参数传递)
static String DEFAULT_CSS
          用于设置标记视图的默认级联样式表 (Cascading Style Sheet) 文件。
static String FONT_CHANGE_BIGGER
          字体大小增大到下一个值的动作标识符
static String FONT_CHANGE_SMALLER
          字体大小减小到下一个值的动作标识符
static String IMG_ALIGN_BOTTOM
          将图像底部对齐。
static String IMG_ALIGN_MIDDLE
          将图像居中对齐。
static String IMG_ALIGN_TOP
          将图像顶部对齐。
static String IMG_BORDER
          将图像对齐到边框。
static String ITALIC_ACTION
          斜体动作标识符
static String LOGICAL_STYLE_ACTION
          逻辑样式选择动作标识符(逻辑样式作为参数传递)
static String PARA_INDENT_LEFT
          段落左缩进动作标识符
static String PARA_INDENT_RIGHT
          段落右缩进动作标识符
 
从类 javax.swing.text.DefaultEditorKit 继承的字段
backwardAction, beepAction, beginAction, beginLineAction, beginParagraphAction, beginWordAction, copyAction, cutAction, defaultKeyTypedAction, deleteNextCharAction, deleteNextWordAction, deletePrevCharAction, deletePrevWordAction, downAction, endAction, endLineAction, EndOfLineStringProperty, endParagraphAction, endWordAction, forwardAction, insertBreakAction, insertContentAction, insertTabAction, nextWordAction, pageDownAction, pageUpAction, pasteAction, previousWordAction, readOnlyAction, selectAllAction, selectionBackwardAction, selectionBeginAction, selectionBeginLineAction, selectionBeginParagraphAction, selectionBeginWordAction, selectionDownAction, selectionEndAction, selectionEndLineAction, selectionEndParagraphAction, selectionEndWordAction, selectionForwardAction, selectionNextWordAction, selectionPreviousWordAction, selectionUpAction, selectLineAction, selectParagraphAction, selectWordAction, upAction, writableAction
 
构造方法摘要
HTMLEditorKit()
          构造 HTMLEditorKit,创建 StyleContext,并加载样式表。
 
方法摘要
 Object clone()
          创建编辑器工具包的一个副本。
 Document createDefaultDocument()
          创建一个适合此编辑器类型的未初始化文本存储模型。
protected  void createInputAttributes(Element element, MutableAttributeSet set)
          将 element 的 AttributeSet 键/值复制到 set 中。
 void deinstall(JEditorPane c)
          工具包从 JEditorPane 移除时调用。
 AccessibleContext getAccessibleContext()
          返回与此编辑器工具包关联的 AccessibleContext。
 Action[] getActions()
          获取编辑器的命令列表。
 String getContentType()
          获取此工具包支持的 MIME 类型的数据。
 Cursor getDefaultCursor()
          返回默认光标。
 MutableAttributeSet getInputAttributes()
          获取该样式编辑动作的输入属性。
 Cursor getLinkCursor()
          返回要在超链接上使用的光标。
protected  HTMLEditorKit.Parser getParser()
          获取要用于读取 HTML 流的解析器。
 StyleSheet getStyleSheet()
          获取当前正用于呈现 HTML 元素的样式集。
 ViewFactory getViewFactory()
          获取一个适合供由此包所产生的任何模型来产生视图的工厂。
 void insertHTML(HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag insertTag)
          将 HTML 插入现有文档。
 void install(JEditorPane c)
          将工具包安装到 JEditorPane 中时调用。
 boolean isAutoFormSubmission()
          指示是否自动处理 html 表单提交,或只是激发 FormSubmitEvent
 void read(Reader in, Document doc, int pos)
          插入来自给定流的内容。
 void setAutoFormSubmission(boolean isAuto)
          指定是否自动处理 html 表单提交,或只是激发 FormSubmitEvent
 void setDefaultCursor(Cursor cursor)
          设置默认光标。
 void setLinkCursor(Cursor cursor)
          设置要在链接上使用的光标。
 void setStyleSheet(StyleSheet s)
          设置要用于呈现各种 HTML 元素的样式集。
 void write(Writer out, Document doc, int pos, int len)
          以适合此类内容处理程序的格式,将文档中的内容写入给定流。
 
从类 javax.swing.text.StyledEditorKit 继承的方法
getCharacterAttributeRun
 
从类 javax.swing.text.DefaultEditorKit 继承的方法
createCaret, read, write
 
从类 java.lang.Object 继承的方法
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

DEFAULT_CSS

public static final String DEFAULT_CSS
用于设置标记视图的默认级联样式表 (Cascading Style Sheet) 文件。

另请参见:
常量字段值

BOLD_ACTION

public static final String BOLD_ACTION
粗体动作标识符

另请参见:
常量字段值

ITALIC_ACTION

public static final String ITALIC_ACTION
斜体动作标识符

另请参见:
常量字段值

PARA_INDENT_LEFT

public static final String PARA_INDENT_LEFT
段落左缩进动作标识符

另请参见:
常量字段值

PARA_INDENT_RIGHT

public static final String PARA_INDENT_RIGHT
段落右缩进动作标识符

另请参见:
常量字段值

FONT_CHANGE_BIGGER

public static final String FONT_CHANGE_BIGGER
字体大小增大到下一个值的动作标识符

另请参见:
常量字段值

FONT_CHANGE_SMALLER

public static final String FONT_CHANGE_SMALLER
字体大小减小到下一个值的动作标识符

另请参见:
常量字段值

COLOR_ACTION

public static final String COLOR_ACTION
Color 选择动作标识符(颜色作为参数传递)

另请参见:
常量字段值

LOGICAL_STYLE_ACTION

public static final String LOGICAL_STYLE_ACTION
逻辑样式选择动作标识符(逻辑样式作为参数传递)

另请参见:
常量字段值

IMG_ALIGN_TOP

public static final String IMG_ALIGN_TOP
将图像顶部对齐。

另请参见:
常量字段值

IMG_ALIGN_MIDDLE

public static final String IMG_ALIGN_MIDDLE
将图像居中对齐。

另请参见:
常量字段值

IMG_ALIGN_BOTTOM

public static final String IMG_ALIGN_BOTTOM
将图像底部对齐。

另请参见:
常量字段值

IMG_BORDER

public static final String IMG_BORDER
将图像对齐到边框。

另请参见:
常量字段值
构造方法详细信息

HTMLEditorKit

public HTMLEditorKit()
构造 HTMLEditorKit,创建 StyleContext,并加载样式表。

方法详细信息

getContentType

public String getContentType()
获取此工具包支持的 MIME 类型的数据。此工具包支持 text/html 类型。

覆盖:
DefaultEditorKit 中的 getContentType
返回:
类型

getViewFactory

public ViewFactory getViewFactory()
获取一个适合供由此包所产生的任何模型来产生视图的工厂。

覆盖:
StyledEditorKit 中的 getViewFactory
返回:
工厂

createDefaultDocument

public Document createDefaultDocument()
创建一个适合此编辑器类型的未初始化文本存储模型。

覆盖:
StyledEditorKit 中的 createDefaultDocument
返回:
模型

read

public void read(Reader in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException
插入来自给定流的内容。如果 doc 是 HTMLDocument 的一个实例,则这将读取 HTML 3.2 文本。将 HTML 插入非空文档时必须插入到正文 Element 的内部,如果未插入正文中,则抛出一个异常。当插入非空文档时,正文外部的所有标记(头、标题)将被删除。

覆盖:
DefaultEditorKit 中的 read
参数:
in - 要从其读取的流
doc - 插入的目标
pos - 在文档中放置内容的位置
抛出:
IOException - 如果发生任何 I/O 错误
BadLocationException - 如果 pos 代表文档中的无效位置
RuntimeException - (最终将为 BadLocationException)如果 pos 无效

insertHTML

public void insertHTML(HTMLDocument doc,
                       int offset,
                       String html,
                       int popDepth,
                       int pushDepth,
                       HTML.Tag insertTag)
                throws BadLocationException,
                       IOException
将 HTML 插入现有文档。

参数:
doc - 内容将要插入的文档
offset - HTML 插入位置的偏移量
popDepth - 插入前要生成的 ElementSpec.EndTagTypes 的数量
pushDepth - 插入前但生成结束标记之后,应该生成的 ElementSpec.StartTagTypes 的数量(它具有 ElementSpec.JoinNextDirection 方向)
insertTag - 开始插入文档的首个标记
抛出:
RuntimeException - (最终将为 BadLocationException)如果 pos 无效
BadLocationException
IOException

write

public void write(Writer out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException
以适合此类内容处理程序的格式,将文档中的内容写入给定流。

覆盖:
DefaultEditorKit 中的 write
参数:
out - 要写入的流
doc - 写入的源
pos - 在文档中获取内容的位置
len - 写出量
抛出:
IOException - 如果发生任何 I/O 错误
BadLocationException - 如果 pos 代表文档中的无效位置

install

public void install(JEditorPane c)
将工具包安装到 JEditorPane 中时调用。

覆盖:
StyledEditorKit 中的 install
参数:
c - JEditorPane

deinstall

public void deinstall(JEditorPane c)
工具包从 JEditorPane 移除时调用。这可用于取消对任何所关联侦听器的注册。

覆盖:
StyledEditorKit 中的 deinstall
参数:
c - JEditorPane

setStyleSheet

public void setStyleSheet(StyleSheet s)
设置要用于呈现各种 HTML 元素的样式集。这些样式是根据 CSS 规范指定的。工具包所生成的每个文档将拥有表的一个副本,它可以向此副本添加特定的文档样式。默认情况下,所有 HTMLEditorKit 实例共享所指定的 StyleSheet。如果需要,应该重新实现它以便提供更细的粒度。


getStyleSheet

public StyleSheet getStyleSheet()
获取当前正用于呈现 HTML 元素的样式集。默认情况下加载 DEFAULT_CSS 所指定的资源,所有 HTMLEditorKit 实例均共享此资源。


getActions

public Action[] getActions()
获取编辑器的命令列表。此命令列表受超类支持,该超类是通过样式操作的本地定义的命令集合扩展的。

覆盖:
StyledEditorKit 中的 getActions
返回:
命令列表

createInputAttributes

protected void createInputAttributes(Element element,
                                     MutableAttributeSet set)
element 的 AttributeSet 键/值复制到 set 中。此操作不复制组件、图标或者元素名称属性。子类可能希望修改此处要复制什么,不复制什么。确保首先移除 set 中的所有属性。

这在插入符移到一个不同位置时调用。

覆盖:
StyledEditorKit 中的 createInputAttributes

getInputAttributes

public MutableAttributeSet getInputAttributes()
获取该样式编辑动作的输入属性。

覆盖:
StyledEditorKit 中的 getInputAttributes
返回:
属性集

setDefaultCursor

public void setDefaultCursor(Cursor cursor)
设置默认光标。

从以下版本开始:
1.3

getDefaultCursor

public Cursor getDefaultCursor()
返回默认光标。

从以下版本开始:
1.3

setLinkCursor

public void setLinkCursor(Cursor cursor)
设置要在链接上使用的光标。

从以下版本开始:
1.3

getLinkCursor

public Cursor getLinkCursor()
返回要在超链接上使用的光标。

从以下版本开始:
1.3

isAutoFormSubmission

public boolean isAutoFormSubmission()
指示是否自动处理 html 表单提交,或只是激发 FormSubmitEvent

返回:
如果自动处理 html 表单提交,则返回 true;否则返回 false。
从以下版本开始:
1.5
另请参见:
setAutoFormSubmission(boolean)

setAutoFormSubmission

public void setAutoFormSubmission(boolean isAuto)
指定是否自动处理 html 表单提交,或只是激发 FormSubmitEvent。默认情况下设置为 true。

从以下版本开始:
1.5
另请参见:
isAutoFormSubmission, FormSubmitEvent

clone

public Object clone()
创建编辑器工具包的一个副本。

覆盖:
StyledEditorKit 中的 clone
返回:
副本
另请参见:
Cloneable

getParser

protected HTMLEditorKit.Parser getParser()
获取要用于读取 HTML 流的解析器。可以重新实现此方法以提供不同的解析器。默认情况下此实现是动态加载的,以避免加载默认解析器(如果没有使用它)的开销。默认解析器是使用 HTML 3.2 DTD 的 HotJava 解析器。


getAccessibleContext

public AccessibleContext getAccessibleContext()
返回与此编辑器工具包关联的 AccessibleContext。

指定者:
接口 Accessible 中的 getAccessibleContext
返回:
与此编辑器工具包关联的 AccessibleContext
从以下版本开始:
1.4

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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