FCKeditorAPI接口的应用 - 张海宁的专栏 - 博客频道 - CSDN.NET

FCKeditorAPI接口的应用 – 张海宁的专栏 – 博客频道 – CSDN.NET.

FCKeditor JavaScript API  编辑器的js 应用编程接口

FCKeditor offers a complete JavaScript API so you can interact with it once the editor is loaded and running.
FCKeditor提供了完整的 js Api 接口函数，所以你可以在编辑器加载运行时与编辑器进行交互。

Once loaded, the editor registers a global object called FCKeditorAPI. This object offers the entry point to interact with any editor instance placed in a page (you can have more than one).  一旦加载完成，编辑器就会注册一个全局的对象叫做 FCKeditorAPI 。这个对象提供了与页面中的编辑器实例进行交互的入口（你可以有多个编辑器实例）。

NOTE: The FCKeditorAPI object will not be available during the page load. You need to wait for the editor to be loaded to use it. If you need to interact with the editor right after is has been loaded, use the “FCKeditor_OnComplete” function (see Events).
注意：这个FCKeditorAPI对象在页面加载没完成时是不会起作用的。所以你必须在编辑器加载完成后再使用它。如果你想在编辑器一加载完时就与其进行交互，可以使用”FCKeditor_OnComplete”函数（可以看下面的Events 部分）。

Retrieving an Editor Instance  访问一个编辑器的实例

     ● From out of an external script   从当前页获取FCK编辑器的实例
When placing the editor in the page, you give it an “instance name”. To retrieve it, you must simply call theFCKeditorAPI.GetInstance method.
Example:
当在页面中放置编辑器时，你给他提供了一个实例名。所以要访问该编辑器的实例，只需调用FCKeditorAPI.GetInstance 方法，例如：

var oEditor = FCKeditorAPI.GetInstance('InstanceName') ;

该函数返回一个编辑器的实例，一个实例其实就是下面要提到的FCK对象。

     ● From out of a dialog of the editor  从 FCK 编辑器的弹出的对话框窗口中获得 FCK 编辑器实例：
Call the InnerDialogLoaded to get the FCKObject.  调用InnerDialogLoaded 方法来获取FCK对象。
Example:例如

var oEditor = window.parent.InnerDialogLoaded().FCK ;

这里所说的对话框窗口比较常见的有图像属性对话框，当你点击”插入/编辑图像”按钮后，就会弹出图像属性对话框来。当给该对话框设置的脚本要访问编 辑器时，就可以用上述的方法，比如dedecms里的图像属性对话框命令就使用的自己的 dede_image.php 文件，该文件里就有下面的一段代码：

<script language=javascript>
var oEditor    = window.parent.InnerDialogLoaded() ;
var oDOM        = oEditor.FCK.EditorDocument ;
var FCK = oEditor.FCK;
var picnum = 1;

上面代码是 InnerDialogLoaded 的具体的应用
Both methods return the main FCKeditor object that gives the necessary bridge to interact with it. These are the most useful properties and methods of this object:
上述的所有的方法都返回一个FCKeditor 对象，这个对象提供了与编辑器进行联系的桥梁。在该对象里有非常有用的属性和方法：

Properties: 属性：

     ● Name = ( string ) – the instance name.   Name 属性（字符串类型）就是 实例名称

     ● Status = ( integer ) – the editor status (loading status).   Status 属性（整形类型）指编辑器的状态（加载的状态）。

     ● EditorDocument = ( object ) – the DOM Document object for the editing area.  EditorDocument 属性（对象类型）指编辑器区域的DOM (document)文档对象。

     ● EditorWindow = ( object ) – the DOM Window object for the editing area.  EditorWindow 属性（对象类型）指编辑器区域的DOM (window)窗口对象。

Methods: 方法:

     ● AttachToOnSelectionChange( functionPointer )

     ● Focus()

     ● SetHTML( html ), or SetData( html ) – sets the contents of the editor. Note that when using this method, you will loose any listener that you may have
previously registered on the editor.EditorDocument.
SetHTML(html)，或 SetData(html) – 设置编辑器的内容。注意当使用这个方法时，你会失去先前在editor.EditorDocument中注册的事件监听器，比如之前使用 editorInstance.EditorDocument.attachEvent(“onkeypress”, FCKeditor_OnKeyup) ; 挂接了一个按键事件，那么当使用了SetHTML后，挂接的事件会失效，所以此方法常用于”设置初始值”或”表单重置”。

     ● GetHTML( formatted ), or GetXHTML( formatted ), or GetData( formatted ) – retrieves the edited html from the editor. 获取编辑器中的html内容，其中oEditor.GetXHTML(formatted); // formatted 为：true|false，表示是否按HTML格式取出

     ● InsertElement( element )

     ● InsertElementAndGetIt( e )

     ● InsertHtml( html ) – inserts HTML in the current cursor position 在当前光标所在位置处插入html 代码。

     ● IsDirty() – checks if the content in the editor has been changed  判断编辑器的内容是否被修改了。

     ● MakeEditable()

     ● ResetIsDirty() – resets the dirty state 重置dirty（脏）的状态。

     ● SwitchEditMode()

     ● UpdateLinkedField()

Events  事件

Once the editor loading phase is complete and it is ready to use (and interact with JavaScript), a standard function is called in the page that contains the editor, if the function is defined. This function must be named“FCKeditor_OnComplete” and receives the related editor instance as the parameter. Using it, you can execute any initial code that may interact with the editor. This is a declaration example:
当编辑器的加载阶段完成后（就可以与js 脚本进行交互了），如果定义了一个名为”FCKeidtor_OnComplete”的函数的话，此时就会调用该函数，这个函数接收一个编辑器的实例作为 参数。使用这个函数，你可以执行任何与编辑器进行交互的初始代码，下面是该函数的定义声明的例子：

function FCKeditor_OnComplete( editorInstance )
{
    alert( editorInstance.Name ) ;
}

Other than the above standard function, every FCKeditor instance has an “Event” object that can be used to listen for events to be fired. 除了上述的标准OnComplete函数外，每个FCKeditor 实例都有一个”Event”对象可以用于监听发生的事件，并针对不同的事件调用所需的回调函数。

Example: the following code listens for the “OnSelectionChange” to execute custom code:  例如：下面的代码用于监听 “OnSelectionChange”（该事件后面有说明）执行自定义的代码：

function FCKeditor_OnComplete( editorInstance )
{
    editorInstance.Events.AttachEvent( 'OnSelectionChange', DoSomething ) ;
}

var counter = 0 ;

function DoSomething( editorInstance )
{
    // This is a sample function that shows in the title bar the number of times
    // the "OnSelectionChange" event is called.
    window.document.title = editorInstance.Name + ' : ' + ( ++counter ) ;
}

Note that every event callback function receives the editor instance as a parameter.
注意每个事件回调函数都会接收一个编辑器实例作为参数。

The following is the list of events available:  下面是可用的事件列表：

     ● OnAfterLinkedFieldUpdate – fired right after the hidden linked field attached to the editor has its contents updated. It happens usually when the form is being posted.
（后面这段中文内容是转载自网上的，对LinkedField可以更好的理解 ）FCKEditor的编辑器实际上是 一个IFrame，每次在创建一个FCKEditor实体的时候，都会新建一个IFrame，然后各种toolbar 和编辑区都塞到这个IFrame中去了，在IFrame外面必须有一个对应的input元素（这个一般是一个textarea，FCKEditor中称之 为LinkedField），这样就可以将textarea中的已有的内容导入到编辑器中，或者将编辑好的内容更新到LinkedField中。下面代码 是该事件的一个应用：

FCK.UpdateLinkedField = function () {
FCK.LinkedField.value = FCK.GetXHTML(FCKConfig.FormatOutput); // 将FCKEditor编辑的内容取出来，这里是我们关心的重点
FCK.Events.FireEvent(“OnAfterLinkedFieldUpdate”);   //更新完LinkedField后触发OnAfterLinkedFieldUpdate事件。
};

     ● OnAfterSetHTML – fired once the HTML is loaded in the editor (including when changing views). 当编辑器内的html被载入后触发,包括改变视图.

     ● OnFocus – fired when the editor acquires the focus.当编辑器获得焦点时。

     ● OnPaste – fired when something is pasted in the editor. The function you specify must return true for the paste to proceed.   当在编辑器中粘贴内容时触发，你所指定的回调函数必须返回true ，才能让粘贴过程继续进行下去。

     ● OnStatusChange – fired when the editor status changes. The following constants are also available globally in the page: FCK_STATUS_NOTLOADED, FCK_STATUS_ACTIVE and FCK_STATUS_COMPLETE. 当编辑器的状态发生改变时。下面的常量是页面中可用的编辑器状态常量：FCK_STATUS_NOTLOADED, FCK_STATUS_ACTIVE 以及 FCK_STATUS_COMPLETE.

     ● OnSelectionChange – fired when the actual selection in the editor area changes (including cursor position and keystrokes). Note: In IE, this event does not fire on every keystroke, but only on some random keystrokes.  当编辑器中实际的选择区域发生变化时（包括光标位置和按键）。注意：在IE中，这个事件不会在每个按键时都触发，只会在一些随机的按键中触发。

Usage Samples使用示例

The following are a few samples of things that can be done with the JavaScript API. (In these samples, oEditor = FCKeditorAPI.GetInstance(‘InstanceName’).)
下面是一些Javascript API 的使用的示例。（在这些例子中，oEditor = FCKeditorAPI.GetInstance(‘InstanceName’) 。）

     ● Insert HTML at cursor position:在光标所在位置插入HTML：

oEditor.InsertHtml(HTML);

     ● Triggering a toolbar button / command: 触发一个工具条中的按钮 / 命令：

oEditor.Commands.GetCommand(commandName).Execute();

     ● Disabling toolbar buttons:   禁用编辑器的按钮：

oEditor.EditorWindow.parent.FCKToolbarItems.LoadedItems[commandName].Disable();

     ● Setting a config value:   设置一个配置的值：

oEditor.Config['<configVariableName>'] = 'newValue';

     ● Change editor document style at runtime: 在运行时改变编辑器的document文档样式：

oEditor.EditorDocument.body.style.cssText += 'color: #322805; background-color: #F7C928;' ;

     ● Set or get anything of the editor:  设置或获取编辑器的任何需要的元素：

FCKeditorAPI.GetInstance('InstanceName').EditorWindow.parent...

     ● Add a dynamic Save function: 添加一个动态的保存函数：

// called on save 当保存时调用
function doSave(){
        alert('Saved.');
        document.getElementById('someElement').innerHTML = 'Saved!';
        return false; //this disables default action (submitting the form)  返回false 来阻止默认的动作（提交表单）。
}
// called when FCKeditor is done starting.. 当编辑器完全准备好后会自动调用。
function FCKeditor_OnComplete( editorInstance ){
        editorInstance.LinkedField.form.onsubmit = doSave;  //当表单提交时触发自己的保存函数。
}

     ● Working with the selection in the editor: Use the Selection Object   可以使用Selection对象来操作编辑器的选择区。