深入讲解 Lotus Notes 中 RichTextEditor 组件的开发应用.doc

深入讲解 Lotus Notes 中 RichTextEditor 组件的开发应用郭 云, 软件工程师, IBM郭云，IBM 中国开发中心软件工程师，对 Web 应用和 UI 开发有浓厚兴趣，目前致力于 Lotus collaboration software 开发。刘 君悦, 软件工程师, IBM刘君悦, IBM中国开发中心软件工程师，对Web应用和嵌入式系统开发有浓厚兴趣，目前致力于RCP/Web Collaboration Software开发。吴 哲, 软件工程师, IBM吴哲，IBM 软件开发中心软件工程师，负责 Lotus Notes/Expeditor 的 Embedded browser 的开发工作，对 Web 应用开发有浓厚兴趣。 简介：RichTextEditor 是 Lotus Notes 中集成的一个基于 DOM 的富文本编辑器组件，与 web 有天然的集成，具有卓越的性能，在 Notes 及相关产品中得到广泛应用。本文将深入介绍该组件的特性、开发、应用及定制功能，深入浅出的讲解如何基于 Lotus RichTextEditor 组件来开发具有高性能，功能齐全，定制丰富的文本编辑器，满足不同用户在工作中的实际需要。标记本文！发布日期：2011 年 11 月 22 日 级别：初级 访问情况 ：8395 次浏览 评论：1(查看|添加评论 - 登录) 平均分 (0个评分)为本文评分RichTextEditor 简介及特性概览RichTextEditor 简介RichTextEditor 是 Lotus Notes 中集成的一个基于 DOM 的，用于处理 web 文档的富文本编辑器组件。其本质上是一个可编辑的浏览器，通过浏览器提供的丰富的 DOM API 来实现复杂的编辑操作。 该组件具体的架构是：上层依赖于 Java 实现的 DOM Browser，下层则是基于成熟的浏览器内核内嵌技术，如 Windows 平台下是基于 IE 引擎，Linux 和 Mac 平台下是基于 Firefox/XULRunner 引擎。架构图参见图 1。图 1. RTE 架构图从上图我们也可以看出，RichTextEditor 组件是构建在 Eclipse 的平台之上的，同时也是由 IE（DOMBrowser.ie/RTE.ie）和 XULRunner（DOMBrowser.xulrunner/RTE.xulrunner）两个不同分支来具体实现的，并通过 RTE 组件将两者集成在一起，对外提供统一的 UI 和接口。底层的这些具体实现细节对 RTE 的应用开发用户来说是透明的。RichTextEditor 的特性概览RichTextEditor 兼具了普通编辑器的功能（如：修改字体大小，粗体，斜体，前景色，后景色，undo，redo，列表，表格等）和 web 编辑器的功能（如 : 编辑状态和浏览状态自如切换等）。除此之外，还提供了一些特殊功能，如： 丰富的 DOM 事件处理功能 Bidi 功能 Toolbar UI 定制 右键菜单定制 Cut/Paste 定制功能 鼠标当前位置字体状态实时监控功能 拖拽支持 Link 控件的导航监听功能 全文拼写检查功能 实时拼写检查功能（支持 29 种语言）RichTextEditor 的应用基于 RichTextEditor 的 web 特性，目前 RichTextEditor 组件已经在 Notes 及 Notes 的客户产品中广泛应用。回页首编程实现定制扩展这一章节将通过编程的方式来实现对编辑器的定制和扩展。主要通过以下几个方面来具体阐述：创建一个基本的 RTE 编辑器，及后台定制RichTextEditor 采用了工厂模式（Factory Pattern）来创建一个 RTE 的实例对象： RichTextEditorFactory.createRichTextEditorInstance(Composite parent, int compositeStyle, int toolBarStyle, int rteStyle); 其中的参数 :parent 参数和 compositeStyle 参数同创建其他的 SWT widget 一样，用来设置 RTE 的父窗口和创建风格 ; toolBarStyle 参数用来设置 RTE 内置的工具栏的风格，有下列值及其组合值可以使用，详细的分类参见图 2。 （1）RichTextEditor.TOOLBAR_STYLE_NONE - 不创建工具栏（2）RichTextEditor.TOOLBAR_STYLE_ALL - 创建完整的工具栏（3）RichTextEditor.TOOLBAR_STYLE_FUNCTIONBAR - 创建功能项子工具栏（包括下述的 7 个参数） RichTextEditor.TOOLBAR_STYLE_FILE - 创建文件打印功能的工具项 RichTextEditor.TOOLBAR_STYLE_EDIT - 创建编辑功能的工具项（包含 copy，cut，paste 操作） RichTextEditor.TOOLBAR_STYLE_UNREDO - 创建撤销恢复的工具项（包含 undo，redo 操作） RichTextEditor.TOOLBAR_STYLE_COLOR - 创建颜色处理工具项（包含字体颜色处理和背景颜色处理操作） RichTextEditor.TOOLBAR_STYLE_INSERT - 创建插入操作工具项（包含插入超链接，插入表格，插入水平线操作） RichTextEditor.TOOLBAR_STYLE_DIRECTION - 创建 bidi 工具项（包含整个文档） RichTextEditor.TOOLBAR_STYLE_SPELLCHECKER - 创建拼写检查工具项（包含界面拼写检查及实时拼写检查操作）（4）RichTextEditor.TOOLBAR_STYLE_STYLEBAR - 创建风格项子工具栏（包含下述的 6 个参数） RichTextEditor.TOOLBAR_STYLE_FORMAT - 创建修改段落格式工具项 RichTextEditor.TOOLBAR_STYLE_FONT - 创建修改字体格式工具项（包含字体样式及字体大小修改操作） RichTextEditor.TOOLBAR_STYLE_TEXTSTYLE - 创建修改文本格式工具项（包含粗体，斜体，下划线操作） RichTextEditor.TOOLBAR_STYLE_ALIGN - 创建文本对齐工具项（包含居左，居中，居右对齐） RichTextEditor.TOOLBAR_STYLE_LIST - 创建列表工具项（包含数字列表和符号列表格式） RichTextEditor.TOOLBAR_STYLE_INDENTATION - 创建缩进工具项图 2. RTE Toolbar style 对应图rteStyle 参数用来设置 RTE 的自身的一些特殊 style（如：创建的 RTE 是编辑状态还是只读状态，以及用来设置 RTE 的后台支持浏览器）。有下列值可以使用 ( 其中前两个参数和后两个参数之间可以相互组合使用 )： RichTextEditor.RTE_STYLE_DEFAULT - 创建编辑状态的 RTE RichTextEditor.RTE_STYLE_READONLY - 创建只读状态的 RTE RichTextEditor.RTE_STYLE_XULRUNNER - 创建基于 XULRUnner 的 RTE RichTextEditor.RTE_STYLE_IE - 创建基于 IE 的 RTE开发人员可以通过清单 1 的代码来创建一个基本的 RTE 实例，其运行结果图如图 3 所示。清单 1. 创建一个基本的 RTE 实例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_ALL, RichTextEditor.RTE_STYLE_DEFAULT); rte.lockToolBar(false ); / 设置子工具栏可以随意拖拽图 3. 清单 1 运行结果图正如我们在第一节描述的，在 Windows 平台下 RichTextEditor 的后台浏览器有两种选择 IE 或者 XULRunner。那么用户如何设定是用 IE 还是 XULRunner 呢？有两种方式来设置： 通过编程的方式来设定，适用于开发人员。开发人员在创建 RTE 实例时，通过设置 createRichTextEditorInstance（）方法的最后一个参数 rteStyle 来实现，示例代码参见清单 2。 通过 Preference 来设定，适用于终端用户。在没有显式设定的情况下 ( 也就是创建 RTE 实例的时候用的是 RichTextEditor.RTE_STYLE_DEFAULT 或者 RichTextEditor.RTE_STYLE_READONLY 参数 )，终端用户可以通过设定 Eclipse preference “com.ibm.rcp.rte/RTEBasedBrowser=IE”或者 “com.ibm.rcp.rte/RTEBasedBrowser=XULRunner”来设置是用 IE 还是 XULRunner提示： 那么如果这两种方式都应用的情况下，二者的优先顺序是：编程方式优先与 Preference 方式。 清单 2. 创建一个基于 XULRunner 的只读模式的 RTE 实例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_ALL, RichTextEditor.RTE_STYLE_READONLY | RichTextEditor.RTE_STYLE_XULRUNNER ) ; rte .setUrl( ); UI 定制 ( 包括风格定制和 toolbar 定制 )RichTextEditor 的 UI 在不同运行环境下，表现风格是不同的。分为标准 SWT 风格和 SWTex 风格。上面所列的图 3 即就是 SWTex 风格的界面。下图 4 为 SWT 风格界面。图 4. SWT 风格的 RTE 界面之所以有两种风格的界面存在，是跟运行时 RCP 系统中 load 的 plugin 状态相关的。如果当前运行系统中 load 了 com.ibm.rcp.swtexplugin，那么 RTE 的运行界面就是运用 com.ibm.rcp.swtexplugin 里定义的控件来画的，运行结果就是 SWTex 风格的，否则即为 SWT 风格的，就是直接运用 org.eclipse.swtplugin 里的控件画出来的。开发用户可以根据自己的需要，在开发自己的 RTE 应用程序的时候考虑是否加载 com.ibm.rcp.swtexplugin 来得到不同风格的 RTE Ui 界面。关于 toolbar 定制，我们在上一节中详细介绍了 RichTextEditor接口中提供的关于 toolbar style 的参数信息。这一节将通过一些代码片段来介绍一下具体的用法。清单 3 使用 RichTextEditor.TOOLBAR_STYLE_NONE创建了一个没有 toolbar 的 RTE 实例。清单 3. 创建一个没有工具栏的 RTE 实例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.BORDER, RichTextEditor. TOOLBAR_STYLE_NONE， RichTextEditor.RTE_STYLE_DEFAULT| RichTextEditor.RTE_STYLE_XULRUNNER); 清单 4 采用 RichTextEditor.TOOLBAR_STYLE_FUNCTIONBAR和 RichTextEditor.TOOLBAR_STYLE_STYLEBAR创建了一个拥有全部工具栏的 RTE 实例，实际结果跟只用一个 RichTextEditor.TOOLBAR_STYLE_ALL的效果一样。清单 4. 创建一个有全部工具栏的 RTE 实例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory. createRichTextEditorInstance(shell, SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_FUNCTIONBAR | RichTextEditor.TOOLBAR_STYLE_STYLEBAR, RichTextEditor.RTE_STYLE_DEFAULT|RichTextEditor.RTE_STYLE_XULRUNNER); 当然开发人员还可以根据需要自由组合 FUNCTIONBAR 子项和 STYLEBAR 子项下的所有 style 来显示不同 toolbar item。右键菜单定制前面介绍过，RichTextEditor实际上就是一个处于编辑状态的浏览器，因此编辑器中的内容实际上就是 html 文本。这样 W3C 的文档事件处理函数就可以应用到 RTE 文档上。在 RichTextEditor接口中提供一个方法：addDocumentEventListener(String type, EventListener eventListener)来实现该功能。其中 type 参数为 W3C 事件类型，包含“contextmenu”，“focus”，“blur”等，更多的类型信息，用户可以参考 W3C 官方网站上的 Document 事件处理文档。开发人员可以通过“contextmenu” 事件类型来进行 RTE 编辑器的右键菜单定制。清单 5 是一个实现了超链接（link node）控件右键菜单示例。实际开发中，用户可以根据自己的实际需要来判断当前鼠标所处位置是什么结点，然后针对不同的结点画出不同的菜单。清单 5. 右键菜单定制示例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_FUNCTIONBAR|RichTextEditor.TOOLBAR_STYLE_STYLEBAR, RichTextEditor.RTE_STYLE_DEFAULT| RichTextEditor.RTE_STYLE_XULRUNNER); ContextMenuListener eventListener = new ContextMenuListener(); rte.addDocumentEventListener(contextmenu, eventListener);清单 6. ContextMenuListener 代码示例class ContextMenuListener implements EventListener public void handleEvent(Event e) Element elem = (Element) e.getTarget(); String href=findHREF(elem); if (href != null) /Create context menu for Link element Menu menu = new Menu(Control)rte).getShell(); MenuItem menuItem = new MenuItem(menu, SWT.NONE); menuItem.setText(A Link element.); menuItem = new MenuItem(menu, SWT.NONE); menuItem.setText(href); menu.setVisible(true); private String findHREF(Element elem) if (elem != null ) Attr attr = null ; try String tag = elem.getTagName(); / Ensure element has an href attribute if (tag.equalsIgnoreCase(A) attr = elem.getAttributeNode(href); else if (tag.equalsIgnoreCase(AREA) attr = elem.getAttributeNode(href); catch (Exception e) e.printStackTrace(); if (attr != null ) / href attribute found. String href = attr.getValue(); return href; else / no href found yet. recuse to parent Node p = elem.getParentNode(); if (p instanceof Element) findHREF(Element) p); return null ; 图 5. 清单 5 运行结果界面cut/paste 定制RichTextEditor接口中提供了 2 个方法来实现 cut和 paste操作的定制，方法分别是：addCutListener(RTEEventListener lis)和 addPasteListener(RTEEventListener lis)。用户需要定义相应的 RTEEventListener的 public void handleEvent(RTEEvent e)处理函数来实现自己特殊的剪切和粘贴操作（如：在 cut 动作之后调整一下文本格式，或者根据剪贴板里的内容不同，根据自己的需要进行类型转换之后 粘贴等等）。需要强调的一点是回调函数 handleEvent的调用时间点对于 cut 和 paste 操作来说是不同的： cut - handleEvent 是在执行完 cut 动作之后调用 paste handleEvent 是在执行 paste 动作之前调用清单 7 是一个定制的 paste 操作，实现了根据剪切板内容类型不同（Rich Text Format，HTML Format或者纯文本格式）进行内容转换（分别用 RTFTransfer，HTMLTransfer 和 TextTransfer 来进行转换），然后将转换内容插入到编辑器中的代码示例。清单 7. paste 操作定制示例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.PUSH| SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_ALL, RichTextEditor.RTE_STYLE_DEFAULT); rte.addPasteListener(new RTEEventListener() public void handleEvent(RTEEvent e) Clipboard cb = new Clipboard(Display.getCurrent(); String typeNames = cb.getAvailableTypeNames(); String content = null ; for (int i = 0; i typeNames.length; i+) if (Rich Text Format.equalsIgnoreCase(typeNamesi) / convert to Rich Text Format content = (String) cb.getContents(RTFTransfer.getInstance(); break ; else if (HTML Format.equalsIgnoreCase(typeNamesi) / convert to HTML Format content = (String) cb.getContents(HTMLTransfer.getInstance(); break ; if (content = null ) / convert to Plain Text Format content = (String) cb.getContents(TextTransfer.getInstance(); rte.insertText(null，content); cb.dispose(); / dispose the Clipboard instance ); Tips: Clipboard对象为系统资源，使用完之后一定要记得将其 dispose 掉，否则有内存泄露。Link 控件行为定制Link 控件在 web 编辑器里，应该是最常用的控件了。在编辑器里，终端用户可以通过点击工具栏上的 Insert Link 按钮来插入一个 Link 对象，开发用户可以通过 RichTextEditor 的 insertHTMLElementAtCursor（HTMLLinkElement）或者 insertHTMLElement（parent，HTMLLinkElement）方法来插入一个 Link 对象。详细的关于 RTE 里的插入操作，请参考下面的“编程实现插入操作”一节，这节将讲述对于 RTE 里已有的 Link 控件进行行为定制操作。众所周知，处于编辑状态的 link 控件是不能够被打开的，所以这节所述的定制是指处于浏览状态的 link 控件行为定制。在 RTE 浏览模式（Readonly mode）下，默认情况即不做任何定制的情况下，link 控件只能在当前编辑器中打开，如果想要将 link 在新的窗口，在新的浏览器里打开，或者在当前系统默认的外部浏览器（如：IE，Firefox 或者 Chrome 等）中打开，就需要自己定制。实现 com.ibm.rcp.rte.NavigationEventListener 的 navigate(NavigationEvent e) 方法来进行定制，然后通过 addNavigationListener(NavigationEventListener navigationListener) 将自己实现的 NavigationEventListener 添加到 RTE 中。清单 8 是一个简单的将 link 在一个系统默认的浏览器中打开的例子。在作者自己的机器上，默认的浏览器是 IE，所以点击该例子中的 link 控件，IE 浏览器将会启动，并且加载所点击的 url。清单 8. Link 定制示例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.PUSH| SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_ALL, RichTextEditor.RTE_STYLE_DEFAULT); rte.setReadOnly(true ); rte.addNavigationListener(new NavigationEventListener() public void navigate(NavigationEvent e) /* Use com.ibm.rcp.ui.browser.launcher.BrowserLauncher to launch * the url in external browser. */ BrowserLauncher.getLauncher().launchURLasExternal(e.url); ); Tips：BrowserLauncher是 Lotus Notes中的另外一个组件，使用它必须在当前 plugin的 MENIFEST.MF文件中将 com.ibm.rcp.ui.browser.launcher 添加到 Require-Bundle 列表里。BiDi 定制BiDi（Bidirection）功能在国际化的产品中是必须要实现的，因为对于希伯来语、阿拉伯语和乌尔都语等，它们的最大特点就是允许双向文本，也就是说，他们的本土语言书写顺序是从右往左显示，而其中的英文单词或商标符号则是从左向右显示。RichTextEditor 对 BiDi 有很好的支持，提供了如下方法来进行 BiDi 操作： public void bidi()； -可以在从左到右和从右到左顺序间来回切换 public void setDirection(int value)； -设置当前编辑器的书写顺序，有如下两种参数可用： o RichTextEditor.LEFT_TO_RIGHTo RichTextEditor.RIGHT_TO_LEFT public int getDirection()； -得到当前编辑器的书写顺序这些方法比较简单就不编程示例了，感兴趣的读者可以自己编程试验。拼写检查定制在 RichTextEditor 中提供了两种拼写检查供用户使用。一种是弹出对话框式的手动进行全文拼写检查，另一种是自动的实时拼写检查，对出错的词用红色下划线标出，并在右键菜单里提供一些可用操作如：提供 3-5 个相近的词以供替换参考，或者直接忽略，或者自动纠错等。RichTextEditor 接口提供的方法分别是 public void doCheckSpelling()和 public boolean enableBackgroundSpellchecking(boolean enable)。这两种拼写检查在 RTE 的 toolbar 中都有实现，End User 可以根据需要点击使用。开发用户可以根据需要自己定制，定制的关键是对何种语言进行拼写检查，通过这个方法 public void setSpellCheckerLocale(String sLocaleCode)来进行设置。如清单 9 所示，设置对阿拉伯语进行实时拼写检查。清单 9. 拼写检查代码示例 Shell shell = new Shell(Display.getCurrent(); rte = RichTextEditorFactory.createRichTextEditorInstance(shell, SWT.PUSH| SWT.BORDER, RichTextEditor.TOOLBAR_STYLE_ALL, RichTextEditor.RTE_STYLE_DEFAULT); rte.setDirection(RichTextEditor.RIGHT_TO_LEFT); / 设置从右到左书写顺序 rte.setSpellCheckerLocale(ar); / 设置拼写检查语言 rte.enableBackgroundSpellchecking(true ); / 启动全文实时拼写检查图 6. RTE 拼写检查界面注：拼写检查是需要有字典和引擎来支持的。RTE 里的拼写检查引擎和字典是来自于 Lotus Notes 中的另一个组件：com.ibm.rcp.textanalyzer。Textanalyzer 组件是有 30 种语言的字典和一些专业术语的词典（如：医药词典等）的支持。编程实现插入操作RichTextEditor 提供了丰富的 API 以供编程来灵活地编辑文本：插入文字，图片，表格，链接，水平线等。1. 插入文字使用 insertText(HTMLElement parent, String text)方法来插入文字，其中的 parent 参数为文字插入的位置，parent 为 null，那么文字则插入在当前鼠标位置，或者当前选中的位置 。另外 appendText(String text) 方法用来在文件末尾插入文字。清单 10. 插入文字代码示例 / 插入文字到鼠标当前位置 rte.insertText(null，Insert text into RTE.); / 插入文字到整个文件的末尾 HTMLElement elem = rte.getHtmlDocument().getBody(); rte.insertText(elem, Append text at the end of body.); / 也是插入文字到整个文件的末尾 rte.appendText(Append text at the end of body， too.); 2.插入链接和图片 RichTextEditor 提供了 2 个 API 来向编辑器里动态插入包括链接，图片在内的几乎所有的 HTMLElement。 insertHTMLElement(Element parent, Element elem) 方法用于插入 element 到指定的 parent 结点下。 insertHTMLElementAtCursor(Element element) 方法用于插入 element 到当前鼠标位置。清单 11. 插入 HTMLElement 代码示例 / 在鼠标当前位置插入链接 Element linkElem = rte.createHTMLElement(a); linkElem.setAttribute(href, ); linkElem.appendChild(rte.getHtmlDocument().createTextNode(IBM Link); rte.insertHTMLElementAtCursor(linkElem); / 在指定位置插入图片 Element imgElem = rte.createHTMLElement(img); imgElem.setAttribute(src, file:/C:/ibm1.jpg); HTMLElement body = rte.getHtmlDocument().getBody(); rte.insertHTMLElement(body, imgElem); 对于其他的 HTMLElement 元素，开发用户可以使用同样的代码来进行操作，只需要替换不同的 HTML 标签名，并设置所需的属性即可。3.插入表格及表格编辑RichTextEditor 中的表格处理 ( 包括插入和编辑 ) 可以使用以下几个方法来完成： insertTable(HTMLElement parent, int rows, int cols) - 插入表格，parent 参数用于指定表格插入的位置，当 parent=null 时，表格插入到当前鼠标位置，rows 参数指需要创建的表格的行数，cols 参数指需要创建的表格的列数。 InsertTableColumnRight() - 在鼠标所在列的右边新插入一列 insertTableColumnLeft() - 在鼠标所在列的左边新插入一列 insertTableRowAbove() - 在鼠标所在行的上边新插入一行 insertTableRowBelow() - 在鼠标所在行的下边新插入一行 deleteTableRow() - 删除当前鼠标所在行 deleteTableColumn()- 删除当前鼠标所在列需要注意的一点是表格的编辑都是针对当前鼠标所在位置进行处理的，如果在鼠标不在表格范围内的情况下进行表格编辑，会有 NPE（NullPointerException）的 exception 抛出，编程的时候应该要捕获一下这个 exception。清单 12. 表格处理代码示例 / 在鼠标当前位置插入一个 5 行 4 列的表格 rte.insertTable(null, 5, 4); / 添加一个 button 来在鼠标当前行下面新插一行 Button bAddNewRow = new Button(parent, SWT.NONE); bAddNewRow.setText(“InsertRowBelow”); bAddNewRow.addSelectionListener(new Selectio