富文本域全解析（转载）

引言

一直以来，Lotus Notes 的富文本域都是使用非常频繁的，几乎在任何 Domino 应用程序中，都会用到富文本域。Lotus Notes 富文本域的功能也非常强大，除了支持普通的文本以外，还支持图片、表格、嵌入对象、Http 链接、Notes 链接、附件等等众多的类型。但是有个问题一直长期困扰着 LotusScript 开发人员，那就是对 Notes 富文本域里面的各种类型的内容的灵活操作很困难，其实 Domino 在不断升级的过程中，已经增加了许多新的 LotusScript 类来操作 Notes 富文本域了，但是很多 LotusScript 开发人员对此并不熟悉。本文将介绍如何使用这些类来灵活操作富文本域。


操作 Notes 富文本域相关的 LotusScript 类

和操作 Notes 富文本域相关的 LotusScript 类包括：

* NotesRichTextNavigator 富文本域的导航器，用来访问富文本域中的各种元素；
* NotesRichTextRange 表示富文本域内容的一个范围，可以包括多个元素；
* NotesRichTextDocLink 表示富文本域内容的文档链接；
* NotesEmbeddedObject 表示嵌入式对象或者文件附件；
* NotesRichTextSection 表示富文本域中的一个区段；
* NotesRichTextTable 表示富文本域中的表格；
* NotesRichTextStyle 表示富文本的各种属性；
* NotesRichTextParagraphStyle 表示富文本段落的各种属性；
* NotesColorObject 表示一种颜色。


使用示例

下面我们通过一个程序来分析各个类的使用方法。

首先我们建立一个空白的 Domino 应用程序，然后建立一个名为“test”的表单，这个表单中只有一个名为“Body”的富文本域，然后在缺省视图里面建立一个 Action 名为“test”，代码如下。这段程序将生成一个文档，文档中包含一个富文本域，并在富文本域中生成各种元素。

清单 1. 生成各种元素

Sub Click(Source As Button)
    Dim s As New NotesSession
    Dim db As NotesDatabase
    Dim doc As NotesDocument
    Set db  =  s.CurrentDatabase
    Set doc = New NotesDocument(db)
    doc.Form = "test"
    Dim rtf As NotesRichTextItem 
    Set rtf = doc.CreateRichTextItem ("Body")

    '生成一个文本段落并设置其字体大小，颜色等属性
    Dim style As NotesRichTextStyle
    Set style = s.CreateRichTextStyle
    Dim pstyle As NotesRichTextParagraphStyle
    Set pstyle = s.CreateRichTextParagraphStyle
    Dim color As NotesColorObject
    Set color  = s.CreateColorObject
    style.FontSize = 20
    style.Bold = True
    pstyle.Alignment = ALIGN_LEFT
    pstyle.FirstLineLeftMargin = RULER_ONE_INCH
    Call color.SetRGB(123, 234, 123) 
    style.NotesColor = color.NotesColor
    Call rtf.AppendStyle(style)
    Call rtf.AppendParagraphStyle(pstyle)
    Call rtf.AppendText("这是一个文本段落，靠左对齐。")
    Call rtf.AddNewline(1)

    '生成一个数据库链接，链接到当前数据库
    Call rtf.AppendDocLink(db, "链接到当前数据库", "当前数据库")

    '生成一个包含一个表格的区段
    Call rtf.AppendStyle(style)
    Call rtf.BeginSection("这是一个区段", style, color, True)
    Call rtf.AppendText("这是区段的开始")
    Dim iRow,iCol,i,j As String
    iRow = 3
    iCol = 3
    style.NotesColor = COLOR_BLUE
    Call rtf.AppendStyle(style)
    '添加一个3X3的表格
    Call rtf.AppendTable(iRow%, iCol%)    
    Call rtf.AppendText("这是区段的结束")
    Call rtf.EndSection
    Dim nav As NotesRichTextNavigator
    Set nav = rtf.CreateNavigator
    Call nav.FindFirstElement(RTELEM_TYPE_TABLECELL) 
    style.FontSize=16
    style.Bold=False
    Call rtf.AppendStyle(style)
    For i = 1 To iRow
        For j = 1 To iCol
            Call rtf.BeginInsert(nav)
            Call rtf.AppendText("行 " & i& ", 列 " & j)
            Call rtf.EndInsert
            Call nav.FindNextElement(RTELEM_TYPE_TABLECELL)
        Next
    Next

    '添加一个附件
    Call rtf.EmbedObject(EMBED_ATTACHMENT, "", "C:\Documents and Settings\All Users\
        Documents\My Pictures\Sample Pictures\Water lilies.jpg")

    Call doc.Save(True,True)
End Sub

下面的图片是运行这个程序后生成的文档截图：

图 1. 程序生成文档图

[img]http://dl.iteye.com/upload/attachment/307987/416468c2-3f05-38e2-ae24-20844f5cb422.png[/img]
下面将分析一下这个程序中使用的一些方法。

* NotesSession.CreateRichTextStyle：创建一个 NotesRichTextStyle 对象。
* NotesSession.CreateRichTextParagraphStyle：创建一个 NotesRichTextParagraphStyle 对象。
* NotesSession.CreateColorObject：创建一个 NotesColorObject 对象。

需要注意的是 NotesRichTextStyle，NotesRichTextParagraphStyle 和 NotesColorObject 这三种对象是不能用 New 来创建的，因为这三个类没有 New() 方法，只能通过 NotesSession 来创建。
* NotesRichTextItem.AppendStyle：在当前位置插入一个格式对象，该位置以后的格式都使用这种格式，直到插入了另外一个格式。
* NotesRichTextItem.AppendParagraphStyle：在当前位置插入一个段落格式对象，该位置以后的段落格式都使用这种格式，直到插入了另外一个段落格式。
* NotesRichTextItem.BeginSection：在富文本域中插入一个区段。
* NotesRichTextItem.EndSection：区段结束，必须和 BeginSection 配对使用。

在两个方法之间可以通过各种 append 方法添加各种元素。插入区段的时候，区段总是在富文本域的最后。还需要注意的是不能创建一个包含富文本域中已有的元素的区段，通过 BeginSection 方法创建的区段总是空的，区段的内容需要通过程序自己添加。
* NotesRichTextItem.CreateNavigator：创建一个富文本域导航器对象 NotesRichTextNavigator。

创建一个富文本域导航器只能使用这种方法，NotesRichTextNavigator 也没有 new 方法。也可以 NotesRichTextRange.Navigator 属性来得到一个 NotesRichTextNavigator 对象。
* NotesRichTextNavigator 类是用来灵活访问操作富文本域里的内容的最重要的一个类，通过它的一些方法，可以方便的访问到各种富文本域中的元素。

导航器对象 NotesRichTextNavigator 会维护一个当前位置，任何在富文本域中的 get 或者 find 的操作都可能会改变这个当前位置。导航总发生在同一种类型的元素中，主要通过 find 和 get 两类方法来访问相应的元素，找到需要的元素后，再通过 get 方法来取得这个元素。下表列出了这些方法。


表 1. 方法列表
方法名 描述
FindFirstElement 将当前位置移动到指定类型的第一个元素
FindNextElement 将当前位置移动到指定类型的下一个元素
FindLastElement 将当前位置移动到指定类型的最后一个元素
FindNthElement 将当前位置移动到指定类型的第 n 个元素
FindFirstString 将当前位置移动到第一个指定字符串的开头
FindNextString 将当前位置移动到下一个指定字符串的开头
GetElement 返回当前位置的元素
GetFirstElement 返回第一个指定类型的元素
GetLastElement 返回最后一个指定类型的元素
GetNextElement 返回下一个指定类型的元素
GetNthElement 返回第 n 个指定类型的元素

NotesRichTextItem.BeginInsert：将插入位置从富文本域结尾处改为指定元素的开始或者结尾处。

NotesRichTextItem.EndInsert：将插入位置重置到富文本域的结尾处，需要和 BeginInsert 配对使用。

在两个方法之间可以通过各种 append 方法添加各种元素。我们来看看 BeginInsert 的具体使用方法：

Call notesRichTextItem.BeginInsert( element, [ after ] )

参数说明

element：可以是 NotesEmbeddedObject, NotesRichTextDocLink, NotesRichTextNavigator, NotesRichTextRange, NotesRichTextSection, 或者 NotesRichTextTable，表示该对象的位置 . 如果是 NotesRichTextNavigator 则表示此 NotesRichTextNavigator 对象所表示的当前位置。

After：布尔型可选参数，True 表示插入位置在元素的末尾，False（缺省值）表示插入位置在元素的开头。

通过上面的简单的例子，我们可以看到如何利用 LotusScript 来操作富文本域，下面我们通过另外一个例子来展示如何利用 LotusScript 来实现一个简单的类似 Word 中将一段文本和表格互相转换的功能，主要展示的是如何利用 NotesRichTextRange 类来操作富文本域中的文本段落。

首先建一个表单 test，表单中创建一个 Body 的富文本域，然后创建一个表单操作名为 Text2Table，完成将文本转化为表格的功能。代码如下：

清单 2 将文本转化为表格

Sub Click(Source As Button)
    Dim s As New NotesSession
    Dim ws As New NotesUIWorkspace
    Dim uidoc As NotesUIDocument
    Set uidoc = ws.CurrentDocument
    Dim doc As NotesDocument
    Set doc = uidoc.Document
    Dim rtf As NotesRichTextItem
    Set rtf = doc.GetFirstItem("Body")
    '设定分隔符为空格
    delimiter$ =  " "
    rowcount% = 0
    colcount% =  0
    Dim rtnav As NotesRichTextNavigator
    Set rtnav = rtf.CreateNavigator
    Dim rtrange As NotesRichTextRange
    Dim rows() 
    Dim paraArray As Variant
    Dim paraStr As String
    Dim firstTime As Boolean
    firstTime = True

    If rtnav.FindFirstElement(RTELEM_TYPE_TABLECELL) Then
        Msgbox "表格已经存在!"
        Exit Sub
    End If
    If rtnav.FindFirstElement(RTELEM_TYPE_TEXTPARAGRAPH) Then
        Set rtrange = rtf.CreateRange
        Do
            '设置文本范围的开始为rtnav所指向的位置
            Call rtrange.SetBegin(rtnav)
            '取得该位置的文本段落
            paraStr = rtrange.TextParagraph
            paraArray = Split(paraStr)
            '通过firstTime来判断文本段落的格式是否能转化为表格
            If firstTime Then
                colcount% = Ubound(paraArray)
                firstTime = False
            Else
                If colcount% <> Ubound(paraArray) Then
                    Msgbox "文本无法转化为表格！"
                    Exit Sub
                End If
            End If
            '定义动态数组来保存所有的文本段落
            Redim Preserve rows(rowcount%)
            rows(rowcount%) = paraArray
            rowcount% = rowcount% + 1
        Loop While rtnav.FindNextElement(RTELEM_TYPE_TEXTPARAGRAPH)
    Else
        Messagebox "富文本域中没有文本"
        Exit Sub
    End If
    '将富文本域值清空
    rtf.Values = ""
    rowcount% = rowcount% - 1
    '插入表格，并将保存的文本依次插入相应的表格单元
    Dim row As Variant
    Call rtf.AppendTable(rowcount%+1, colcount%+1)
    Call rtnav.FindFirstElement(RTELEM_TYPE_TABLECELL)
    For i% = 0 To rowcount%
        row = rows(i%)
        For j% = 0 To colcount%
            Call rtf.BeginInsert(rtnav)
            Call rtf.AppendText(row(j%))
            Call rtf.EndInsert
            Call rtnav.FindNextElement(RTELEM_TYPE_TABLECELL)
        Next
    Next
    '保存文档并重新打开以刷新
    Call doc.Save(True, True)
    Call uidoc.Close(True)
    Call ws.EditDocument(False,doc)

End Sub

再建立一个表单操作名为 Table2Text，完成将表格转化为文本的功能。代码如下：

清单 3 将表格转化为文本

Sub Click(Source As Button)
    Dim s As New NotesSession
    Dim ws As New NotesUIWorkspace
    Dim uidoc As NotesUIDocument
    Set uidoc = ws.CurrentDocument
    Dim doc As NotesDocument
    Set doc = uidoc.Document
    Dim rtf As NotesRichTextItem
    Set rtf = doc.GetFirstItem("Body")

    delimiter$ =  " "
    Dim rtnav As NotesRichTextNavigator
    Set rtnav = rtf.CreateNavigator
    Dim rtrange As NotesRichTextRange
    Set rtrange = rtf.CreateRange
    Dim tbl As NotesRichTextTable
    Dim rowcount As Integer
    Dim colcount As Integer

    If rtnav.FindFirstElement(RTELEM_TYPE_TABLE) Then
        Set tbl = rtnav.GetElement
        rowcount = tbl.RowCount - 1
        colcount = tbl.ColumnCount - 1
        Redim data(rowcount, colcount)
        For i% = 0 To rowcount
            For j% = 0 To colcount
                Call rtnav.FindNextElement(RTELEM_TYPE_TABLECELL)
                Call rtrange.SetBegin(rtnav)
                If j% = colcount Then
                    Call rtf.AppendText(rtrange.TextParagraph )
                Else
                    Call rtf.AppendText(rtrange.TextParagraph & delimiter$)
                End If
            Next
            If i% < rowcount Then
                '生成新的段落
                Call rtf.AddNewline(1)
            End If
        Next
    Else
        Messagebox "富文本域中没有表格"
        Exit Sub
    End If

    Call tbl.Remove
    Call doc.Save(True, True)
    Call uidoc.Close(True)
    Call ws.EditDocument(False,doc)    
End Sub

运行结果如下图：

图 2. 文本格式
[img]http://dl.iteye.com/upload/attachment/307989/f11a0c82-f82b-335c-9131-0cfa43fb7c91.png[/img]

图 3. 表格格式
[img]http://dl.iteye.com/upload/attachment/307991/463ba6ac-8958-3125-b05e-09db6456fbc6.png[/img]

回页首

总结

通过以上本文的介绍和示例及代码分析，相信读者对如何操作 Notes 富文本域已经有了了解，我们可以看到 LotusScript 的强大功能，通过灵活运用适当的类，可以完成很多我们认为不能完成的功能，希望本文对读者有所启发和帮助。