文本文档结构
文本文档主要包含以下四种类型的信息:
- 实际文本
- 用于设置字符、段落和页面格式的模板
- 非文本元素,如表格、图形和绘图对象
- 文本文档的全局设置
本节重点介绍文本及关联的格式选项。
段落和段落部分
文本文档的核心包含一系列段落。由于既没有命名这些段落,也没有为其创建索引,因此无法直接访问各个段落。不过,可以借助 API 简介中介绍的 Enumeration 对象按顺序遍历这些段落。这样,就可以编辑段落了。
不过,在使用 Enumeration 对象时,要注意一种特殊情况:它不仅返回段落,而且还返回表格(严格地讲,在 Apache OpenOffice 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 文档对象,该对象引用当前的 Apache OpenOffice 文档。然后,本示例借助 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 函数不属于 Apache OpenOffice Basic 的标准语言范畴。这是搜索和替换中介绍的示例函数的一个实例。
此处介绍的用于访问文本段落的过程内容与 VBA 中使用的 Paragraphs 列表类似,后者是由 Range 和 Document 对象提供的。在 VBA 中,通过编号来访问段落(例如,通过 Paragraph(1) 调用),而在 Apache OpenOffice Basic 中,应使用上面介绍的 Enumeration 对象。 |
Apache OpenOffice Basic 中没有与 VBA 中提供的 Characters, Sentences 和 Words 列表直接对应的内容。不过,您可以切换到 TextCursor,并通过它在字符、句子和词级别进行浏览。
段落部分
上一示例可以根据需要更改文本,但有时可能会破坏格式。
这是因为段落是由各个子对象组成的。每个子对象都包含自己的格式设置信息。例如,如果段落中心包含以粗体打印的词,则在 Apache OpenOffice 中要用三个段落部分来表示:粗体类型前面的部分,然后是粗体词,最后是粗体类型后面的部分(又变为正常字体)。
如果现在使用段落的 String 属性更改段落文本,则 Apache OpenOffice 将首先删除旧的段落部分,然后插入新的段落部分。这样一来,旧段落部分的格式就会丢失。
为防止出现这种情况,用户可以访问关联的段落部分,而不是整个段落。段落提供了自己的 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 属性来修改每个段落部分的内容。所做的更改与上一示例中对段落的更改相同。不过,由于段落部分是直接编辑的,因此在替换字符串时会保留段落部分的格式设置信息。
格式设置
可以使用多种方法设置文本格式。最简单的方法是,直接为文本序列指定格式属性。这称为直接格式设置。直接格式设置尤其适用于较短的文档,因为用户可以使用鼠标指定格式。例如,可以使用粗体类型突出显示文本中的某个词,或者将其放在行中间。
除了直接格式设置以外,还可以使用模板设置文本格式。这称为间接格式设置。通过使用间接格式设置,用户可以为相关文本部分指定预定义的模板。如果以后要更改文本版式,用户只需更改模板即可。Apache OpenOffice 将更改所有使用该模板的文本部分的描述方式。
字符属性
针对单个字符的格式属性称为字符属性。这些属性包括粗体类型和字体类型。允许设置字符属性的对象必须支持 com.sun.star.style.CharacterProperties 服务。Apache OpenOffice 可以识别支持该服务的各种服务。其中包括上文中介绍的用于段落的 com.sun.star.text.Paragraph 服务以及用于段落部分的 com.sun.star.text.TextPortion 服务。
com.sun.star.style.CharacterProperties 服务不提供任何接口,而是提供一系列属性,可通过这些属性定义和调用字符属性。Apache OpenOffice 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 中的段落属性。
Apache OpenOffice 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 标记。
字符和段落属性的默认值
直接格式设置的优先级始终高于间接格式设置。换句话说,使用模板设置格式比直接在文本中设置格式的优先级低。
很难确定文档的某个部分的格式是直接还是间接设置的。Apache OpenOffice 提供的符号栏显示了常用的文本属性,如字体类型、粗细和大小。但没有明确说明相应设置是基于模板,还是基于文本中的直接格式设置。
Apache OpenOffice 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
- 属性不明确。例如,在查询段落的粗体类型属性时,如果段落既包括粗体的词,又包括正常字体的词,则会出现这种状态。
以下示例说明了如何在 Apache OpenOffice 中编辑格式属性。本示例将在文本中搜索通过直接格式设置设为粗体类型的段落部分。如果找到相应的段落部分,本示例将使用 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). |