文本文档结构

From Apache OpenOffice Wiki
Jump to: navigation, search
doc OOo


Book.png

文本文档主要包含以下四种类型的信息:

  • 实际文本
  • 用于设置字符、段落和页面格式的模板
  • 非文本元素,如表格、图形和绘图对象
  • 文本文档的全局设置

本节重点介绍文本及关联的格式选项。

段落和段落部分

文本文档的核心包含一系列段落。由于既没有命名这些段落,也没有为其创建索引,因此无法直接访问各个段落。不过,可以借助 API 简介中介绍的 Enumeration 对象按顺序遍历这些段落。这样,就可以编辑段落了。

不过,在使用 Enumeration 对象时,要注意一种特殊情况:它不仅返回段落,而且还返回表格(严格地讲,在 OpenOffice.org Writer 中,表格就是一种特殊类型的段落)。因此,在访问返回的对象之前,应检查返回的对象是支持用于段落的 com.sun.star.text.Paragraph 服务,还是支持用于表格的 com.sun.star.text.TextTable 服务。

以下示例将通过循环遍历文本文档的内容,并在每个实例中使用消息通知用户,相关对象是段落还是表格。

Dim Doc As Object
Dim Enum As Object
Dim TextElement As Object
 
' Create document object   
Doc = StarDesktop.CurrentComponent
' Create enumeration object 
Enum = Doc.Text.createEnumeration
' loop over all text elements
 
While Enum.hasMoreElements
  TextElement = Enum.nextElement
 
  If TextElement.supportsService("com.sun.star.text.TextTable") Then
    MsgBox "The current block contains a table."
  End If
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    MsgBox "The current block contains a paragraph."
  End If
 
Wend

本示例创建了一个 Doc 文档对象,该对象引用当前的 OpenOffice.org 文档。然后,本示例借助 Doc 创建了一个 Enumeration 对象,该对象遍历文本的各个部分(段落和表格),并将当前元素赋值给 TextElement 对象。本示例使用 supportsService 方法检查 TextElement 是段落还是表格。

段落

com.sun.star.text.Paragraph 服务授予对段落内容的访问权限。可以使用 String 属性检索和修改段落中的文本:

Dim Doc As Object
Dim Enum As Object
Dim TextElement As Object
 
Doc = StarDesktop.CurrentComponent
Enum = Doc.Text.createEnumeration
 
While Enum.hasMoreElements
  TextElement = Enum.nextElement
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    TextElement.String = Replace(TextElement.String, "you", "U") 
    TextElement.String = Replace(TextElement.String, "too", "2")
    TextElement.String = Replace(TextElement.String, "for", "4") 
  End If
 
Wend

本示例打开当前的文本文档,并借助 Enumeration 对象遍历该文档。它在所有段落中使用 TextElement.String 属性访问相关段落,并将 you、too 和 for 字符串替换为 U、2 和 4 字符。用于替换的 Replace 函数不属于 OpenOffice.org Basic 的标准语言范畴。这是搜索和替换中介绍的示例函数的一个实例。

Documentation note.png 此处介绍的用于访问文本段落的过程内容与 VBA 中使用的 Paragraphs 列表类似,后者是由 RangeDocument 对象提供的。在 VBA 中,通过编号来访问段落(例如,通过 Paragraph(1) 调用),而在 OpenOffice.org Basic 中,应使用上面介绍的 Enumeration 对象。

OpenOffice.org Basic 中没有与 VBA 中提供的 Characters, SentencesWords 列表直接对应的内容。不过,您可以切换到 TextCursor,并通过它在字符、句子和词级别进行浏览。

段落部分

上一示例可以根据需要更改文本,但有时可能会破坏格式。

这是因为段落是由各个子对象组成的。每个子对象都包含自己的格式设置信息。例如,如果段落中心包含以粗体打印的词,则在 OpenOffice.org 中要用三个段落部分来表示:粗体类型前面的部分,然后是粗体词,最后是粗体类型后面的部分(又变为正常字体)。

如果现在使用段落的 String 属性更改段落文本,则 OpenOffice.org 将首先删除旧的段落部分,然后插入新的段落部分。这样一来,旧段落部分的格式就会丢失。

为防止出现这种情况,用户可以访问关联的段落部分,而不是整个段落。段落提供了自己的 Enumeration 对象以实现此目的。以下示例将使用一个双循环,来遍历文本文档的所有段落及其包含的段落部分,并应用上一示例中的替换过程:

Dim Doc As Object
Dim Enum1 As Object
Dim Enum2 As Object
Dim TextElement As Object
Dim TextPortion As Object
 
Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration
 
' loop over all paragraphs
While Enum1.hasMoreElements
  TextElement = Enum1.nextElement
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    Enum2 = TextElement.createEnumeration
    ' loop over all sub-paragraphs 
 
    While Enum2.hasMoreElements
      TextPortion = Enum2.nextElement
      MsgBox "'" & TextPortion.String & "'"
      TextPortion.String = Replace(TextPortion.String, "you", "U") 
      TextPortion.String = Replace(TextPortion.String, "too", "2")
      TextPortion.String = Replace(TextPortion.String, "for", "4") 
    Wend
 
  End If
Wend

本示例通过双循环来遍历文本文档。外层循环处理文本段落。内层循环处理这些段落中的段落部分。本示例代码使用字符串的 String 属性来修改每个段落部分的内容。所做的更改与上一示例中对段落的更改相同。不过,由于段落部分是直接编辑的,因此在替换字符串时会保留段落部分的格式设置信息。

格式设置

可以使用多种方法设置文本格式。最简单的方法是,直接为文本序列指定格式属性。这称为直接格式设置。直接格式设置尤其适用于较短的文档,因为用户可以使用鼠标指定格式。例如,可以使用粗体类型突出显示文本中的某个词,或者将其放在行中间。

除了直接格式设置以外,还可以使用模板设置文本格式。这称为间接格式设置。通过使用间接格式设置,用户可以为相关文本部分指定预定义的模板。如果以后要更改文本版式,用户只需更改模板即可。OpenOffice.org 将更改所有使用该模板的文本部分的描述方式。

Documentation note.png 在 VBA 中,对象的格式设置属性通常分布在一系列子对象中(例如 Range.FontRange.BordersRange.ShadingRange.ParagraphFormat)。这些属性是通过层叠表达式(例如 Range.Font.AllCaps)进行访问的。另一方面,在 OpenOffice.org Basic 中,可通过相关对象(TextCursor、Paragraph 等)直接访问这些格式设置属性。以下两节简要介绍了 OpenOffice.org 中提供的字符和段落属性。
Documentation note.png 每个对象(Paragraph、TextCursor 等)中都包含格式设置属性,可以直接应用这些属性。

字符属性

针对单个字符的格式属性称为字符属性。这些属性包括粗体类型和字体类型。允许设置字符属性的对象必须支持 com.sun.star.style.CharacterProperties 服务。OpenOffice.org 可以识别支持该服务的各种服务。其中包括上文中介绍的用于段落的 com.sun.star.text.Paragraph 服务以及用于段落部分的 com.sun.star.text.TextPortion 服务。

com.sun.star.style.CharacterProperties 服务不提供任何接口,而是提供一系列属性,可通过这些属性定义和调用字符属性。OpenOffice.org API 参考中提供了所有字符属性的完整列表。以下列表介绍了最重要的属性:

CharFontName (String)
选定字体类型的名称。
CharColor (Long)
文本颜色。
CharHeight (Float)
字符高度,以磅 (pt) 为单位。
CharUnderline (Constant group)
下划线类型(与 com.sun.star.awt.FontUnderline 一致的常量)。
CharWeight (Constant group)
字体粗细(与 com.sun.star.awt.FontWeight 一致的常量)。
CharBackColor (Long)
背景颜色。
CharKeepTogether (Boolean)
禁止自动换行。
CharStyleName (String)
字符模板的名称。

段落属性

不针对单个字符而是针对整个段落的格式设置信息称为段落属性。这包括段落与页面边缘之间的距离以及行间距。可通过 com.sun.star.style.ParagraphProperties 服务提供段落属性。

甚至可以通过各种对象提供段落属性。所有支持 com.sun.star.text.Paragraph 服务的对象还支持 com.sun.star.style.ParagraphProperties 中的段落属性。

OpenOffice.org API 参考中提供了段落属性的完整列表。最常用的段落属性有:

ParaAdjust (enum)
垂直文本方向(与 com.sun.star.style.ParagraphAdjust 一致的常量)。
ParaLineSpacing (struct)
行间距(与 com.sun.star.style.LineSpacing 一致的结构)。
ParaBackColor (Long)
背景颜色。
ParaLeftMargin (Long)
左边距,以百分之一毫米为单位。
ParaRightMargin (Long)
右边距,以百分之一毫米为单位。
ParaTopMargin (Long)
上边距,以百分之一毫米为单位。
ParaBottomMargin (Long)
下边距,以百分之一毫米为单位。
ParaTabStops (Array of struct)
制表符的类型和位置(具有 com.sun.star.style.TabStop 类型结构的数组)。
ParaStyleName (String)
段落模板的名称。

示例:简单的 HTML 导出

以下示例说明了如何使用格式设置信息。本示例将循环访问一个文本文档,并创建一个简单的 HTML 文件。为此,将在相应 HTML 元素 <P> 中记录每个段落。在导出以粗体类型显示的段落部分时,将使用 HTML 元素 <B> 标记这些部分。

Dim FileNo As Integer, Filename As String, CurLine As String
Dim Doc As Object   
Dim Enum1 As Object, Enum2 As Object
Dim TextElement As Object, TextPortion As Object
 
Filename = "c:\text.html"
FileNo = Freefile
Open Filename For Output As #FileNo   
Print #FileNo, "<HTML><BODY>"
Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration
 
' loop over all paragraphs
While Enum1.hasMoreElements
 TextElement = Enum1.nextElement
 
 If TextElement.supportsService("com.sun.star.text.Paragraph") Then
   Enum2 = TextElement.createEnumeration
   CurLine = "<P>"
 
    ' loop over all paragraph portions
   While Enum2.hasMoreElements
     TextPortion = Enum2.nextElement
 
     If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN
       CurLine = CurLine & "<B>" & TextPortion.String & "</B>"
      Else
        CurLine = CurLine & TextPortion.String
      End If
 
     Wend
 
    ' output the line
     CurLine = CurLine & "</P>"
     Print #FileNo, CurLine
   End If
 
 Wend
 
' write HTML footer 
Print #FileNo, "</BODY></HTML>"
Close #FileNo

本示例的基本结构基于前面讨论的遍历文本段落部分的示例,但添加了用于编写 HTML 文件的函数以及一个测试代码,该代码检查相应文本部分的字体粗细,并为粗体类型的段落部分提供相应的 HTML 标记。

字符和段落属性的默认值

直接格式设置的优先级始终高于间接格式设置。换句话说,使用模板设置格式比直接在文本中设置格式的优先级低。

很难确定文档的某个部分的格式是直接还是间接设置的。OpenOffice.org 提供的符号栏显示了常用的文本属性,如字体类型、粗细和大小。但没有明确说明相应设置是基于模板,还是基于文本中的直接格式设置。

OpenOffice.org Basic 提供了 getPropertyState 方法,程序员可以使用该方法检查某个属性的格式是如何设置的。该方法将属性名称作为参数,并返回一个常量,以提供有关格式来源的信息。可能会出现 com.sun.star.beans.PropertyState 枚举中定义的以下响应:

com.sun.star.beans.PropertyState.DIRECT_VALUE
直接在文本中定义属性(直接格式设置)
com.sun.star.beans.PropertyState.DEFAULT_VALUE
通过模板定义属性(间接格式设置)
com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE
属性不明确。例如,在查询段落的粗体类型属性时,如果段落既包括粗体的词,又包括正常字体的词,则会出现这种状态。

以下示例说明了如何在 OpenOffice.org 中编辑格式属性。本示例将在文本中搜索通过直接格式设置设为粗体类型的段落部分。如果找到相应的段落部分,本示例将使用 setPropertyToDefault 方法删除直接格式设置,并为这些段落部分指定 MyBold 字符模板。

Dim Doc As Object
Dim Enum1 As Object
Dim Enum2 As Object
Dim TextElement As Object
Dim TextPortion As Object
 
Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration
 
' loop over all paragraphs
While Enum1.hasMoreElements
  TextElement = Enum1.nextElement
 
 If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    Enum2 = TextElement.createEnumeration
    ' loop over all paragraph portions
 
 While Enum2.hasMoreElements
      TextPortion = Enum2.nextElement
 
      If TextPortion.CharWeight = _
        com.sun.star.awt.FontWeight.BOLD AND _
        TextPortion.getPropertyState("CharWeight") = _
        com.sun.star.beans.PropertyState.DIRECT_VALUE Then
        TextPortion.setPropertyToDefault("CharWeight")
        TextPortion.CharStyleName = "MyBold" 
      End If
    Wend
  End If
Wend
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools