Document (Java Platform SE 8 )

All Known Subinterfaces:

StyledDocument

所有已知实现类：

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

内容

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

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

在这个例子中，如上图所示，如果文档的内容是序列“快速棕色狐狸”，则位于“The”之前的位置为0，位于“The”之后的位置后面的空格是3。序列“The”中的整个字符序列被称为范围。

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

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

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

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

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

以下方法与文件内容的突变有关：
通知

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

通知作为两个单独的事件提供， DocumentEvent和UndoableEditEvent 。如果通过其api向Document进行突变， DocumentEvent向所有注册的DocumentListeners发送DocumentListeners 。如果Document实现支持撤消/重做功能，那么UndoableEditEvent将被发送到所有注册的UndoableEditListener 。如果可撤消的编辑被撤销，则应从文档中触发DocumentEvent以指示它已重新更改。然而，在这种情况下，应该没有UndoableEditEvent 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

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`StreamDescriptionProperty` 用于初始化文档的流的描述的属性名称。
`static String`	`TitleProperty` 文件标题的属性名称，如果有的话。

方法摘要

所有方法接口方法抽象方法
Modifier and Type	Method and Description
`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
```
    用于初始化文档的流的描述的属性名称。如果文档是从流初始化的，并且关于流的所有内容都是已知的，则应该使用这一点。
    
    另请参见：
    
    Constant Field Values
  - TitleProperty
```
static final String TitleProperty
```
    文件标题的属性名称，如果有的话。
    
    另请参见：
    
    Constant Field Values
- 方法详细信息
  - 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中包含要更改的元素插入和删除的详细信息。由文件的实施决定结构如何改变以应对删除。
    
    如果文档支持撤消/重做，则还将生成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发送到已注册的DocumentLister，除非抛出异常。 DocumentEvent将通过在DocumentListener上调用insertUpdate方法来传递。生成的DocumentEvent的偏移量和长度将指示实际对文档进行了哪些更改。
    
    如果文档结构因插入而更改，则会在生成的DocumentEvent中包含要更改的元素插入和删除的详细信息。文件的执行取决于结构如何响应插入而改变。
    
    如果文档支持撤消/重做，则还将生成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，则在段中返回的数据将是所请求的整个长度，并且根据数据的存储方式可以复制或不复制。如果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

Field Summary

方法摘要

字段详细信息

StreamDescriptionProperty

TitleProperty

方法详细信息

getLength

addDocumentListener

removeDocumentListener

addUndoableEditListener

removeUndoableEditListener

getProperty

putProperty

remove

insertString

getText

getText

getStartPosition

getEndPosition

createPosition

getRootElements

getDefaultRootElement

render