All Known Subinterfaces:

StyledDocument

所有已知实现类：

AbstractDocument ， DefaultStyledDocument ， HTMLDocument ， PlainDocument
```
public interface Document
```
Document是用于文本的容器，用作swing文本组件的模型。此接口的目标是从非常简单的需求（纯文本文本字段）扩展到复杂需求（例如，HTML或XML文档）。

内容

在最简单的级别，文本可以建模为线性字符序列。为了支持国际化，Swing文本模型使用unicode个字符。文本组件中显示的字符序列通常称为组件的内容。

要引用序列中的位置，使用的坐标是两个字符之间的位置。如下图所示，文本文档中的位置可以称为位置或偏移。这个位置是从零开始的。

在该示例中，如果文档的内容是序列“The quick brown fox”，如上图所示，则单词“The”之前的位置为0，并且单词“The”之后的位置和之前的位置它后面的空格是3.序列“The”中的整个字符序列称为范围。

以下方法可以访问构成内容的字符数据。
结构体

文本很少被简单地表示为无特征内容。相反，文本通常具有与其相关联的某种结构。究竟建模的结构取决于特定的Document实现。它可能就像没有结构（即简单的文本字段）一样简单，或者它可能类似于下图。

结构单元（即树的节点）由Element接口引用。每个元素都可以使用一组属性进行标记。这些属性（名称/值对）由AttributeSet接口定义。

以下方法可以访问文档结构。
- getDefaultRootElement()
- getRootElements()
突变

所有文档都需要能够添加和删除简单文本。通常，通过键盘或鼠标的手势插入和移除文本。插入或移除对文档结构的影响完全取决于文档的实现。

以下方法与文档内容的变异有关：
通知

必须将有关Document突变传达给感兴趣的观察员。更改通知遵循为JavaBeans指定的事件模型准则。在JavaBeans事件模型中，一旦调度了事件通知，就必须在事件源发生任何进一步的突变之前通知所有侦听器。此外，不保证交货顺序。

通知作为两个单独的事件提供， DocumentEvent和UndoableEditEvent 。如果通过其api对Document进行突变， DocumentEvent发送到所有已注册的DocumentListeners 。如果Document实现支持撤消/重做功能， UndoableEditEvent将UndoableEditEvent发送到所有已注册的UndoableEditListener 。如果撤消了可撤消的编辑，则应从文档触发DocumentEvent以指示它已再次更改。但是，在这种情况下，应该没有生成UndoableEditEvent因为该编辑实际上是更改的来源，而不是通过其api对Document进行的突变。

参考上图，假设左侧显示的组件改变了由蓝色矩形表示的文档对象。该文档通过将DocumentEvent分派给两个组件视图并将UndoableEditEvent发送到监听逻辑来响应，该逻辑维护历史缓冲区。

现在假设右边显示的组件改变了同一个文档。同样，文档将DocumentEvent调度到两个组件视图，并将UndoableEditEvent发送到维护历史缓冲区的侦听逻辑。

如果然后回滚历史缓冲区（即最后一个UndoableEdit撤消），则向两个视图发送DocumentEvent，导致它们都反映文档的撤消变异（即删除正确组件的变异）。如果历史记录缓冲区再次回滚另一个更改，则会向两个视图发送另一个DocumentEvent，导致它们将未撤消的突变反映到文档中 - 即删除左侧组件的突变。

与观察文件突变有关的方法是：
字段

文档实现通常在运行时具有一些与它们相关联的属性集。两个众所周知的属性是StreamDescriptionProperty ，可用于描述Document来源，以及TitleProperty ，可用于命名Document 。与属性相关的方法是：
- getProperty(java.lang.Object)
- putProperty(java.lang.Object, java.lang.Object)
有关Document类的更多信息，请参阅The Swing Connection ，最特别是文章The Element Interface 。
另请参见：

DocumentEvent ， DocumentListener ， UndoableEditEvent ， UndoableEditListener ， Element ， Position ， AttributeSet

字段汇总

字段
变量和类型	字段	描述
`static String`	`StreamDescriptionProperty`	用于初始化文档的流描述的属性名称。
`static String`	`TitleProperty`	文档标题的属性名称（如果有）。

方法摘要

所有方法实例方法抽象方法
变量和类型	方法	描述
`void`	`addDocumentListener(DocumentListener listener)`	注册给定的观察者，以便在对文档进行更改时开始接收通知。
`void`	`addUndoableEditListener(UndoableEditListener listener)`	当对文档进行可撤消编辑时，注册给定观察者以开始接收通知。
`Position`	`createPosition(int offs)`	此方法允许应用程序在字符内容序列中标记位置。
`Element`	`getDefaultRootElement()`	返回视图应基于的根元素，除非提供了一些用于将视图分配给元素结构的其他机制。
`Position`	`getEndPosition()`	返回表示文档末尾的位置。
`int`	`getLength()`	返回文档中当前内容的字符数。
`Object`	`getProperty(Object key)`	获取与文档关联的属性。
`Element[]`	`getRootElements()`	返回定义的所有根元素。
`Position`	`getStartPosition()`	返回表示文档开头的位置。
`String`	`getText(int offset, int length)`	获取文档给定部分中包含的文本。
`void`	`getText(int offset, int length, Segment txt)`	获取文档给定部分中包含的文本。
`void`	`insertString(int offset, String str, AttributeSet a)`	插入一串内容。
`void`	`putProperty(Object key, Object value)`	将属性与文档关联。
`void`	`remove(int offs, int len)`	删除文档内容的一部分。
`void`	`removeDocumentListener(DocumentListener listener)`	从通知列表中取消注册给定的观察者，以便它不再接收更改更新。
`void`	`removeUndoableEditListener(UndoableEditListener listener)`	从通知列表中取消注册给定的观察者，以便它不再接收更新。
`void`	`render(Runnable r)`	如果模型支持异步更新，则允许在存在并发的情况下安全地呈现模型。

- 字段详细信息
  - StreamDescriptionProperty
```
static final String StreamDescriptionProperty
```
    用于初始化文档的流描述的属性名称。如果从流初始化文档并且已知有关流的任何内容，则应使用此方法。
    
    另请参见：
    
    常数字段值
  - TitleProperty
```
static final String TitleProperty
```
    文档标题的属性名称（如果有）。
    
    另请参见：
    
    常数字段值
- 方法详细信息
  - getLength
```
int getLength()
```
    返回文档中当前内容的字符数。
    
    结果
    
    字符数> = 0
  - addDocumentListener
```
void addDocumentListener(DocumentListener listener)
```
    注册给定的观察者，以便在对文档进行更改时开始接收通知。
    
    参数
    
    listener - 注册的观察员
    
    另请参见：
    
    removeDocumentListener(javax.swing.event.DocumentListener)
  - removeDocumentListener
```
void removeDocumentListener(DocumentListener listener)
```
    从通知列表中取消注册给定的观察者，以便它不再接收更改更新。
    
    参数
    
    listener - 注册的观察员
    
    另请参见：
    
    addDocumentListener(javax.swing.event.DocumentListener)
  - addUndoableEditListener
```
void addUndoableEditListener(UndoableEditListener listener)
```
    当对文档进行可撤消编辑时，注册给定观察者以开始接收通知。
    
    参数
    
    listener - 注册的观察员
    
    另请参见：
    
    UndoableEditEvent
  - removeUndoableEditListener
```
void removeUndoableEditListener(UndoableEditListener listener)
```
    从通知列表中取消注册给定的观察者，以便它不再接收更新。
    
    参数
    
    listener - 注册观察员
    
    另请参见：
    
    UndoableEditEvent
  - getProperty
```
Object getProperty(Object key)
```
    获取与文档关联的属性。
    
    参数
    
    key - 非 null属性键
    
    结果
    
    属性
    
    另请参见：
    
    putProperty(Object, Object)
  - putProperty
```
void putProperty(Object key,
                 Object value)
```
    将属性与文档关联。提供的两个标准属性键是： StreamDescriptionProperty和TitleProperty 。还可以定义其他属性，例如作者。
    
    参数
    
    key - 非 null属性键
    
    value - 属性值
    
    另请参见：
    
    getProperty(Object)
  - remove
```
void remove(int offs,
            int len)
     throws BadLocationException
```
    删除文档内容的一部分。这将导致DocumentEvent.EventType.REMOVE类型的DocumentEvent被发送到已注册的DocumentListeners，除非抛出异常。通过调用DocumentListeners上的removeUpdate方法，通知将发送给侦听器。
    为了确保在并发性方面的合理行为，在突变发生后调度事件。这意味着，在发送删除通知时，文档已更新，并且createPosition创建的任何标记已更改。对于移除，移除范围的末尾将向下折叠到范围的开头，并且移除范围中的任何标记都会向下折叠到范围的开头。
    
    如果文档结构因删除而更改，则生成的DocumentEvent中还将包含为响应更改而插入和删除元素的详细信息。由文档的实现来决定结构应如何响应删除而改变。
    
    如果Document支持undo / redo，还将生成UndoableEditEvent。
    
    参数
    
    offs - 从开头的偏移量> = 0
    
    len - 要删除的字符数> = 0
    
    异常
    
    BadLocationException - 删除范围的某些部分不是文档的有效部分。异常中的位置是遇到的第一个不良位置。
    
    另请参见：
    
    DocumentEvent ， DocumentListener ， UndoableEditEvent ， UndoableEditListener
  - insertString
```
void insertString(int offset,
                  String str,
                  AttributeSet a)
           throws BadLocationException
```
    插入一串内容。这将导致DocumentEvent.EventType.INSERT类型的DocumentEvent被发送到已注册的DocumentListers，除非抛出异常。 DocumentEvent将通过调用DocumentListener上的insertUpdate方法来传递。生成的DocumentEvent的偏移量和长度将指示实际对Document进行的更改。
    
    如果Document结构因插入而更改，则生成的DocumentEvent中还将包含为响应更改而插入和删除Elements的详细信息。由文档的实现决定结构应如何响应插入而改变。
    
    如果Document支持undo / redo，还将生成UndoableEditEvent。
    
    参数
    
    offset - 插入内容的文档偏移量> = 0.在给定位置或之后跟踪更改的所有位置都将移动。
    
    str - 要插入的字符串
    
    a - 与插入的内容关联的属性。如果没有属性，则此值可能为null。
    
    异常
    
    BadLocationException - 给定的插入位置不是文档中的有效位置
    
    另请参见：
    
    DocumentEvent ， DocumentListener ， UndoableEditEvent ， UndoableEditListener
  - getText
```
String getText(int offset,
               int length)
        throws BadLocationException
```
    获取文档给定部分中包含的文本。
    
    参数
    
    offset - 表示所需文本开头的文档偏移量> = 0
    
    length - 所需字符串的长度> = 0
    
    结果
    
    文本，长度> = 0的字符串
    
    异常
    
    BadLocationException - 给定范围的某些部分不是文档的有效部分。异常中的位置是遇到的第一个不良位置。
  - getText
```
void getText(int offset,
             int length,
             Segment txt)
      throws BadLocationException
```
    获取文档给定部分中包含的文本。
    如果txt参数上的partialReturn属性为false，则Segment中返回的数据将是请求的整个长度，可能是也可能不是副本，具体取决于数据的存储方式。如果partialReturn属性为true，则仅返回可在不创建副本的情况下返回的文本量。对于扫描文档的大部分内容的情况，使用部分返回将提供更好的性能。以下是使用部分返回访问整个文档的示例：
    
    int nleft = doc.getDocumentLength(); Segment text = new Segment(); int offs = 0; text.setPartialReturn(true); while (nleft > 0) { doc.getText(offs, nleft, text); // do someting with text nleft -= text.count; offs += text.count; }
    参数
    
    offset - 表示文本所需开头的文档偏移量> = 0
    
    length - 所需字符串的长度> = 0
    
    txt - 要返回文本的Segment对象
    
    异常
    
    BadLocationException - 给定范围的某些部分不是文档的有效部分。异常中的位置是遇到的第一个不良位置。
  - getStartPosition
```
Position getStartPosition()
```
    返回表示文档开头的位置。返回的位置可以计入跟踪更改并保持位于文档的开头。
    
    结果
    
    这个职位
  - getEndPosition
```
Position getEndPosition()
```
    返回表示文档末尾的位置。返回的位置可以计入跟踪更改并保持位于文档的末尾。
    
    结果
    
    这个职位
  - createPosition
```
Position createPosition(int offs)
                 throws BadLocationException
```
    此方法允许应用程序在字符内容序列中标记位置。然后，该标记可用于跟踪内容中的插入和删除时的更改。策略是插入始终发生在当前位置之前（最常见的情况），除非插入位置为零，在这种情况下插入被强制到跟随原始位置的位置。
    
    参数
    
    offs - 距文档开头的偏移量> = 0
    
    结果
    
    这个职位
    
    异常
    
    BadLocationException - 如果给定位置不代表关联文档中的有效位置
  - getRootElements
```
Element[] getRootElements()
```
    返回定义的所有根元素。
    通常只有一个文档结构，但该接口支持在文本数据上构建任意数量的结构投影。该文档可以具有多个根元素以支持多个文档结构。一些例子可能是：
    
    文字方向。
    
    词汇标记流。
    
    解析树木。
    
    转换为本机格式以外的格式。
    
    修改规范。
    
    注释。
    结果
    
    根元素
  - getDefaultRootElement
```
Element getDefaultRootElement()
```
    返回视图应基于的根元素，除非提供了一些用于将视图分配给元素结构的其他机制。
    
    结果
    
    根元素
  - render
```
void render(Runnable r)
```
    如果模型支持异步更新，则允许在存在并发的情况下安全地呈现模型。给定的runnable将以允许它在执行runnable时安全地读取模型而不进行任何更改的方式执行。可运行本身可能不会发生任何突变。
    
    参数
    
    r - 用于渲染模型的 Runnable

Interface Document

字段汇总

方法摘要

字段详细信息

StreamDescriptionProperty

TitleProperty

方法详细信息

getLength

addDocumentListener

removeDocumentListener

addUndoableEditListener

removeUndoableEditListener

getProperty

putProperty

remove

insertString

getText

getText

getStartPosition

getEndPosition

createPosition

getRootElements

getDefaultRootElement

render