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

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

Interface Document

Field Summary

方法摘要

字段详细信息

StreamDescriptionProperty

TitleProperty

方法详细信息

getLength

addDocumentListener

removeDocumentListener

addUndoableEditListener

removeUndoableEditListener

getProperty

putProperty

remove

insertString

getText

getText

getStartPosition

getEndPosition

createPosition

getRootElements

getDefaultRootElement

render