CKEditor插件开发.doc

CKEditor 插件开发 星期二 7 27 2010 发布在 Tutorial 评论 From 根据 comment 有修 改 CKeditor API CKEditor 是目前市场上比较灵活的在线 WYSIWYG 编辑器之一 它灵活的设计 开放的 API 和详细的 文档使得用户扩展功能非常容易 本文尝试勾勒出 CKEditor 插件开发的基础 包含了增加按钮 对话框 和执行命令 源代码的结构 在开始之前 感性的认知一下 CKEditor 源码的组织形式是很有用的 CKEditor 固有的一些文件被组织 到 ckeditor source 目录里 核心的功能 诸如 DOM 元素操作 事件处理 初始化脚本和一些环境设 置被包含在 ckeditor source core 文件夹内 而其它的一些功能 比如格式化 拷贝和粘贴 图片和链 接 都被实现为插件形式放在 ckeditor source plugins 文件夹内 每个文件夹表示一个插件 并且在 每个文件夹内 有一个 plugin js 的文件包含了该插件需要用到的代码 你可以看到源代码被组织成不同的文件 为了减少 HTTP 请求 CKEditor 把不同的文件压缩并打包到 ckeditor js 和 ckeditor basic js 里 这种方式是运行编辑器的默认方式 在开发的过程中 你会希望通 过 ckedtior source js 来代替 ckeditor js 的执行 现在 创建 ckeditor source plugins footnote 目录 并在目录里创建 plugin js 文件 配置插件 为了开始开发你的插件 你需要首先注册你的插件 这样 CKEditor 才能载入它 在 ckeditor config js 里 增加 config extraPlugins footnote 此配置将会告诉编辑器在 footnote 目录下载入 plugin js 基本的 plugin js 结构如下 CKEDITOR plugins add footnote init function editor plugin code goes here 按钮 CKEditor 中主要的功能的实现基本都是通过命令的形式 命令由事件 函数调用或者点击某个工具栏的 按钮触发 下列代码增加了一个 Footnote 的按钮和 footnote 的命令 CKEDITOR plugins add footnote init function editor var pluginName footnote CKEDITOR dialog add pluginName this path dialogs footnote js editor addCommand pluginName new CKEDITOR dialogCommand pluginName editor ui addButton Footnote label Footnote or Citation command pluginName editor ui addButton 函数声明包含了两个参数 按钮名字和按钮定义 在按钮定义中可能的属性还包含 label 当鼠标位于按钮之上时所出现的文字提示 className 按钮的 css 类名 默认为 cke button 命令名称 click 当点击按钮后所调用的函数 默认为 执行由 命令键值 指定的命令 command 将在按钮点击之后执行的命令 上述代码利用了 CKEDTIOR dialogCommand 该函数将在下面的对话章节中介绍 在添加了一个 按钮后 你需要把 Footnote 增加到 config js 的工具栏的定义中 把该按钮放到工具栏的合适的位 置 之后 你就能看到一个空的按钮出现在工具栏里 按钮图片 最简单的增加按钮图片的办法是利用属性 icon 代码如下 CKEDITOR plugins add myplugin init function editor plugin code goes here editor ui addButton myplugin label myplugin command FCKCommand myplugin icon CKEDITOR plugins getPath myplugin myplugin png 命令 CKEditor 以命令的方式提供了大部分的功能 命令和函数之间的不同是 命令是有 ON OFF 和未启用 状态的 定义一个命令 editor addCommand 函数声明了两个参数 命令名字和命令的对象定义 可能的命令定义的属性包含 exec 最小形式 定义的对象拥有一个 exec 方法 该方法会在命令执行时执行 modes 命令能被执行的模式 默认为 wysiwyg 1 有效的模式是 wysiwyg source editorFocus 在执行命令时 是否给予编辑器焦点 默认 true state 命令的状态 默认 CKEDITOR TRISTATE OFF canUndo 该命令是否会和 redo undo 系统挂钩 async 在异步功能 例如 ajax 中被用到 在执行完命令后 afterCommandExec 事件将不会 被自动触发 它将期望程序员能够手工触发该事件 执行命令 触发命令是很简单的 通过 editor execCommand commandName 命令状态 命令有三个状态 ON OFF 和 DISABLED 状态能够通过 setState 进行设置 例如 editor getCommand commandName setState state 状态值将会是 CKEDITOR TRISTATE ON CKEDITOR TRISTATE OFF CKEDITOR TRISTATE DISABLED 中的一个 当设置为未启用的时候 按钮将会表现为灰色 并且通过 execCommand 执行的命令将无效 当设置为 on 的时候 按钮就会被高亮 当命令的状态改变的时候 命令将会触发一个 state 事件 对话框 对话框是一些插件的核心 为了使用该对话框 他们必须首先在 plugin js 中注册 包括定义 通过调用 CKEDITOR dialog add 如下 CKEDITOR dialog add pluginName this path dialogs pluginName js 之后 如果你想通过点击一个按钮触发这个对话框 你可以通过使用 CKEDITOR dialogCommand 来 简单的完成这项工作 editor addCommand pluginName new CKEDITOR dialogCommand pluginName 对话框定义 按约定 有关对话框的代码将会被放到 dialogs js 中 和按钮和命令类似 对话框也是通过定义一些属 性和方法来定义的 下面的代码展示了一个标准的 js 的模板 function var exampleDialog function editor return title title in string minWidth number of pixels minHeight number of pixels buttons array of button definitions onOk function onLoad function onShow function onHide function onCancel function resizable none width height or both contents content definition basically the UI of the dialog CKEDITOR dialog add insertHTML function editor return exampleDialog editor 定义里有以下一些属性 方法 Buttons 该属性定义了对话框底部可用的按钮 它是一个 CKEDITOR dialog buttonDefinition 对象的数组 默 认的值是 CKEDITOR dialog okButton CKEDITOR dialog cancelButton 为了增加你自己的按 钮 你须要写下按钮的定义 并把它加到该数组里 例如 buttons type button id someButtonID note this is not the CSS ID attribute label Button onClick function action on clicking the button CKEDITOR dialog okButton CKEDITOR dialog cancelButton 效果如下 对话框事件对话框事件 onOK onLoad onShow onHide onCancel 事件在不同的情况下会被触发 onLoad 在对话框第一 次打开的时候被触发 可以用来针对该对话框做一些初始化 onShow 在对话框显示的时候被触发 onLoad 和 onShow 的不同之处在于 onLoad 将只触发一次 而不管对话框被打开或关掉多少次 而同 时 onShow 将在对话框每次显示的时候被触发 这是因为在按下 ok 或 cancel 的时候 对话框将被隐藏 触发 onHide 而不是完全的卸载 onOk 和 onCancel 将在 ok 或 cancel 按钮被按下的时候触发 Resizable 该属性用来描述对话框是否可以被调整大小 可能的值包含 CKEDITOR DIALOG RESIZE NONE CKEDITOR DIALOG RESIZE WIDTH CKEDITOR DIALOG RESIZE HEIGHT and CKEDITOR DIALOG RESIZE BOTH Default is CKEDITOR DIALOG RESIZE NONE 对话框的 UI 对话框的用户接口是对话框属性定义的内容 对话框的 UI 部分会首先被组织为几个页面 每个页面表示 了对话框的一个 tab 页 在每个页面中 输入元素 按钮 文本输入 文本区域 单选 下拉 多选和文件 都 将被辅助性的结构元素 vbox hbox 和 label 组织起来 通过写这些 UI 元素的定义 你将不须要写任何 html 代码而完成对这些 UI 的行为和外表的定义 当然 替代使用这些所提供的对象来构建用户界面的方 法是依然选择用原始的 HTML 代码去实现 html 的 UI 元素 对话框的页面对话框的页面 内容域是一个 contentDefinition 的数组 每个定义代表了一个对话框的 tab 页 下面是一个模板 contents id page1 not CSS ID attribute label Page1 accessKey P elements elements id page2 label Page2 accessKey Q elements elements 结果如下 UI 元素元素 在定义了 tab 页面之后 你可以通过传递一个 uiElements 的数组作为 contentDefinition 的元素来定义 每个 tab 页的 UI 那里右两种类型的 uiElements 结构型的和输入型的 结构型元素 vbox 和 hbox 使用表格来放置元素的位置 结构型的元素可以镶嵌从而形成复杂的结构 当输入的 uiElements 拥有一 些比较重要的特征的时候这会使得他们比 DOM 输入元素更有用 结构型元素结构型元素 elements type hbox widths 100px 100px 100px children type html html Cell1 type html html Cell2 type vbox children type html html Cell3 type html html Cell4 输入型元素输入型元素 输入型元素有很多的属性和方法可用 更多的细节请参考 uiElement 文档 同时这里也有一些比较重要 的 id 必须的 注意这不是 css 的 id 属性 但是是被 CKEditor 所使用的标识符 CKEditor 将会 自动设置 css id 属性但和这个 id 无关 为了得到此对象所表示的元素 你可以使用 getContentElement 例如 如果你想得到 uiElement 内部的某个 uiElement 你可以使用 this getDialog getContentElement pageIdName elementIdName pageIdName is the ID for page containing the element type 必须的 是以下的其中一个 text password textarea checkbox button select file fileButton html label 和输入元素同时显示的文本标签 labelLayout horizontal 横向 或 vertical 纵向 当设置为纵向的时候 标签会在元素的顶 部 on events 函数或事件 第一个字符必须大写 事件可以是 DOM 事件 例如 onChange onClick 等 就像 onShow onHide 和 onLoad 这些在对话框被激活的时候调用的事件一样 validate 函数用来验证输入元素的值 例如为了验证值不为空 你可以使用 validate CKEDITOR dialog validate notEmpty ErrorMessage 如果域是空的 那么错误消息将在你点击 ok 按钮的时候弹出 内置的验证器包含 regex regex msg notEmpty msg integer msg regex d number msg regex d d equals value msg notEqual value msg setup 函数会在父对话框的 setupContent 方法被调用时执行 能够被用来初始化一些域的值 例如当编辑一个文档中已存图片域的时候 你可能希望初始化该图片的宽度 这里有个例子 onShow function onShow function for the dialog definition other code var elem this getParentEditor getSelection getSelectedElement get the current selected element this setupContent elem this function will call all the setup function for all uiElements other code contents id InfoTab label Info Tab elements input element for the width type text id widthInput label Width labelLayout horizontal setup function element this setValue element getAttribute width commit 函数在父对话框的 commitContent 方法被调用的时候执行 例如 它能在 ok 按钮 被按下时变更图片的大小 上下文菜单 上下文菜单是你在 CKEditor 中右键所弹出的菜单 就像 CKEditor 的其它特征一样 它也很容易被定制 下面的代码展示了如何增加一个 Code 菜单项的过程 if editor addMenuItems editor addMenuItems have to add menu item first insertCode name of the menu item label Code command insertCode group insertCode have to be added in config if editor contextMenu editor contextMenu addListener function element selection function to be run when context menu is displayed if element element is pre return null return insertCode C