在菜单上添加自定义按钮相关方法

添加菜单自定义按钮

AddCustomButtonOnMenu

语法：

javascript

AddCustomButtonOnMenu(btnPos, btnCaption, [IsNeedOpenDoc], [cmnuID])

功能：
在菜单右侧增加自定义按钮。

参数：

名称	必选/可选	数据类型	说明
btnPos	必选	string	按钮位置，取值0-9
btnCaption	必选	string	按钮标题
IsNeedOpenDoc	可选	bool	是否需要打开文档，默认为true
cmnuID	可选	long	按钮ID，默认＝0

返回值：
无返回值

说明：
自定义菜单栏按钮始终保持在文件菜单以及自定义菜单右侧位置，而非在控件最右边添加的按钮。

参数说明：

btnPos：按钮位置，取值0-9
btnCaption：按钮标题
IsNeedOpenDoc：该按钮是否需要打开的文档。如果为false，则按钮总是可用。否则，只有打开文档时按钮才可用
cmnuID：可用于在按钮处理事件中标识按钮。或者用第一个参数btnPos也可以。默认和btnPos数值相同

使用示例：

javascript

// 添加菜单自定义按钮
TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "按钮0", false);
TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "按钮1", true, 1);
TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "按钮2", true, 2);
TANGER_OCX_OBJ.AddCustomButtonOnMenu(3, "按钮3", false, 3);

RemoveCustomButtonOnMenu

语法：

javascript

RemoveCustomButtonOnMenu(btnPos)

功能：
删除菜单上的指定位置的自定义的按钮。

参数：

名称	必选/可选	数据类型	说明
btnPos	必选	long	按钮位置，取值0-9

返回值：
无返回值

说明：
删除菜单上的指定位置的自定义的按钮。

使用示例：

javascript

// 删除第一个菜单按钮
TANGER_OCX_OBJ.RemoveCustomButtonOnMenu(0);

事件处理

OnCustomButtonOnMenuCmd事件

语法：

javascript

OnCustomButtonOnMenuCmd(btnPos, btnCaption, btnCmdid)

功能：
处理菜单自定义按钮点击事件。

参数：

名称	数据类型	说明
btnPos	long	按钮位置
btnCaption	string	按钮标题
btnCmdid	long	按钮ID

使用示例：

javascript

// 事件处理示例
<script language="JScript" for="TANGER_OCX" event="OnCustomButtonOnMenuCmd(btnPos,btnCaption,btnCmdid)">
    alert("btnPos=" + btnPos + ",btnCaption=" + btnCaption + ",btnCmdid=" + btnCmdid);
    
    if(0 == btnCmdid) { // 切换全屏
        // 事件处理代码中可以直接引用控件属性或者方法，
        // 可以省略控件对象前缀
        FullScreenMode = !FullScreenMode; 
    }
    else if(1 == btnCmdid) {
        DoHandSign2('tanger');
    }
    else if(2 == btnCmdid) {
        // 处理按钮2的点击事件
    }
    else if(3 == btnCmdid) {
        // 处理按钮3的点击事件
    }
</script>

方法分类总结

分类	方法	功能	说明
按钮管理	`AddCustomButtonOnMenu`	添加菜单自定义按钮	在菜单右侧添加按钮
	`RemoveCustomButtonOnMenu`	删除菜单自定义按钮	删除指定位置的按钮
事件处理	`OnCustomButtonOnMenuCmd`	处理按钮点击事件	按钮点击事件处理

使用流程

1. 创建菜单自定义按钮

javascript

// 创建菜单自定义按钮
function createMenuButtons() {
    try {
        // 添加常用功能按钮
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "全屏切换", false, 0);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "手写签名", true, 1);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "保存文档", true, 2);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(3, "打印文档", true, 3);
        
        console.log("菜单自定义按钮创建完成");
        
    } catch (error) {
        console.error("创建菜单自定义按钮失败:", error.message);
    }
}

2. 管理按钮状态

javascript

// 管理按钮状态
function manageButtonStatus() {
    try {
        // 根据文档状态控制按钮可用性
        if (TANGER_OCX_OBJ.DocType === 0) {
            // 没有文档时，某些按钮不可用
            // 注意：IsNeedOpenDoc参数在创建时已设置，这里只是示例
            console.log("没有文档，某些按钮将不可用");
        } else {
            // 有文档时，所有按钮可用
            console.log("有文档，所有按钮可用");
        }
        
        console.log("按钮状态管理完成");
        
    } catch (error) {
        console.error("按钮状态管理失败:", error.message);
    }
}

3. 处理按钮事件

javascript

// 处理按钮事件
function setupButtonEvents() {
    try {
        // 按钮事件处理已在HTML中定义
        // 这里提供JavaScript函数供事件调用
        
        // 全屏切换功能
        function toggleFullScreen() {
            TANGER_OCX_OBJ.FullScreenMode = !TANGER_OCX_OBJ.FullScreenMode;
        }
        
        // 手写签名功能
        function doHandSign() {
            TANGER_OCX_OBJ.DoHandSign2('tanger');
        }
        
        // 保存文档功能
        function saveDocument() {
            TANGER_OCX_OBJ.SaveToLocal();
        }
        
        // 打印文档功能
        function printDocument() {
            TANGER_OCX_OBJ.PrintOut();
        }
        
        console.log("按钮事件处理设置完成");
        
    } catch (error) {
        console.error("按钮事件处理设置失败:", error.message);
    }
}

完整示例

1. 基础按钮创建

javascript

// 基础按钮创建示例
function createBasicMenuButtons() {
    try {
        // 创建基础功能按钮
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "新建", false, 1001);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "打开", false, 1002);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "保存", true, 1003);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(3, "打印", true, 1004);
        
        console.log("基础菜单按钮创建完成");
        
    } catch (error) {
        console.error("基础菜单按钮创建失败:", error.message);
    }
}

2. 高级按钮管理

javascript

// 高级按钮管理示例
function createAdvancedMenuButtons() {
    try {
        // 创建高级功能按钮
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "全屏", false, 2001);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "签名", true, 2002);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "转换", true, 2003);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(3, "设置", false, 2004);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(4, "帮助", false, 2005);
        
        console.log("高级菜单按钮创建完成");
        
    } catch (error) {
        console.error("高级菜单按钮创建失败:", error.message);
    }
}

3. 动态按钮管理

javascript

// 动态按钮管理示例
function dynamicButtonManagement() {
    try {
        // 根据用户权限动态添加按钮
        var userRole = getUserRole();
        
        if (userRole === 'admin') {
            // 管理员显示所有按钮
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "管理", false, 3001);
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "设置", false, 3002);
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "日志", false, 3003);
        } else if (userRole === 'editor') {
            // 编辑者显示编辑相关按钮
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "编辑", true, 4001);
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "保存", true, 4002);
        } else {
            // 查看者显示查看相关按钮
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "查看", true, 5001);
            TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "打印", true, 5002);
        }
        
        console.log("动态按钮管理完成");
        
    } catch (error) {
        console.error("动态按钮管理失败:", error.message);
    }
}

事件处理示例

1. 基础事件处理

javascript

// 基础事件处理示例
<script language="JScript" for="TANGER_OCX" event="OnCustomButtonOnMenuCmd(btnPos,btnCaption,btnCmdid)">
    // 根据按钮ID处理不同功能
    switch(btnCmdid) {
        case 1001: // 新建
            TANGER_OCX_OBJ.CreateNew("Word.Document");
            break;
        case 1002: // 打开
            TANGER_OCX_OBJ.ShowDialog(1);
            break;
        case 1003: // 保存
            TANGER_OCX_OBJ.SaveToLocal();
            break;
        case 1004: // 打印
            TANGER_OCX_OBJ.PrintOut();
            break;
        default:
            alert("未知按钮: " + btnCaption);
    }
</script>

2. 高级事件处理

javascript

// 高级事件处理示例
<script language="JScript" for="TANGER_OCX" event="OnCustomButtonOnMenuCmd(btnPos,btnCaption,btnCmdid)">
    // 记录按钮点击
    console.log("按钮点击: " + btnCaption + " (ID: " + btnCmdid + ")");
    
    // 根据按钮功能分类处理
    if (btnCmdid >= 2001 && btnCmdid <= 2005) {
        // 高级功能按钮
        handleAdvancedButton(btnCmdid);
    } else if (btnCmdid >= 3001 && btnCmdid <= 3003) {
        // 管理功能按钮
        handleAdminButton(btnCmdid);
    } else if (btnCmdid >= 4001 && btnCmdid <= 4002) {
        // 编辑功能按钮
        handleEditorButton(btnCmdid);
    } else if (btnCmdid >= 5001 && btnCmdid <= 5002) {
        // 查看功能按钮
        handleViewerButton(btnCmdid);
    }
    
    // 处理高级功能按钮
    function handleAdvancedButton(cmdId) {
        switch(cmdId) {
            case 2001: // 全屏
                FullScreenMode = !FullScreenMode;
                break;
            case 2002: // 签名
                DoHandSign2('tanger');
                break;
            case 2003: // 转换
                // 转换功能
                break;
            case 2004: // 设置
                // 设置功能
                break;
            case 2005: // 帮助
                // 帮助功能
                break;
        }
    }
    
    // 处理管理功能按钮
    function handleAdminButton(cmdId) {
        switch(cmdId) {
            case 3001: // 管理
                // 管理功能
                break;
            case 3002: // 设置
                // 设置功能
                break;
            case 3003: // 日志
                // 日志功能
                break;
        }
    }
    
    // 处理编辑功能按钮
    function handleEditorButton(cmdId) {
        switch(cmdId) {
            case 4001: // 编辑
                // 编辑功能
                break;
            case 4002: // 保存
                SaveToLocal();
                break;
        }
    }
    
    // 处理查看功能按钮
    function handleViewerButton(cmdId) {
        switch(cmdId) {
            case 5001: // 查看
                // 查看功能
                break;
            case 5002: // 打印
                PrintOut();
                break;
        }
    }
</script>

注意事项

版本要求：此方法是增强版及以上版本所有
按钮位置：按钮位置范围0-9
按钮ID：建议使用唯一的按钮ID便于事件处理
文档依赖：IsNeedOpenDoc参数控制按钮是否需要打开文档
事件处理：配合OnCustomButtonOnMenuCmd事件处理按钮点击
按钮位置：按钮始终保持在文件菜单以及自定义菜单右侧位置
错误处理：实现完善的错误处理机制

错误处理

javascript

// 菜单按钮错误处理
function handleMenuButtonError(operation, error) {
    console.error("菜单按钮操作失败:", operation, error.message);
    
    switch(operation) {
        case 'AddCustomButtonOnMenu':
            console.log("添加菜单按钮失败，请检查:");
            console.log("1. 按钮位置是否在0-9范围内");
            console.log("2. 按钮标题是否有效");
            console.log("3. 控件版本是否支持此功能");
            break;
        case 'RemoveCustomButtonOnMenu':
            console.log("删除菜单按钮失败，请检查:");
            console.log("1. 按钮位置是否有效");
            console.log("2. 按钮是否已创建");
            console.log("3. 控件版本是否支持此功能");
            break;
        case 'OnCustomButtonOnMenuCmd':
            console.log("按钮事件处理失败，请检查:");
            console.log("1. 事件处理代码是否正确");
            console.log("2. 按钮ID是否有效");
            console.log("3. 控件状态是否正常");
            break;
        default:
            console.log("未知菜单按钮操作失败");
    }
}

最佳实践

1. 按钮设计最佳实践

javascript

// 按钮设计最佳实践
function buttonDesignBestPractice() {
    try {
        // 按功能分组设计按钮
        // 基础功能按钮
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "新建", false, 1001);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "打开", false, 1002);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "保存", true, 1003);
        
        // 编辑功能按钮
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(3, "撤销", true, 2001);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(4, "重做", true, 2002);
        
        // 工具功能按钮
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(5, "全屏", false, 3001);
        TANGER_OCX_OBJ.AddCustomButtonOnMenu(6, "签名", true, 3002);
        
        console.log("按钮设计完成");
        
    } catch (error) {
        console.error("按钮设计失败:", error.message);
    }
}

2. 状态管理最佳实践

javascript

// 状态管理最佳实践
function stateManagementBestPractice() {
    try {
        // 根据文档状态管理按钮
        function updateButtonStates() {
            var docType = TANGER_OCX_OBJ.DocType;
            
            if (docType === 0) {
                // 没有文档时，某些按钮不可用
                // 注意：这里只是示例，实际状态由IsNeedOpenDoc参数控制
                console.log("没有文档，某些按钮将不可用");
            } else {
                // 有文档时，所有按钮可用
                console.log("有文档，所有按钮可用");
            }
        }
        
        // 定期更新按钮状态
        setInterval(updateButtonStates, 1000);
        
        console.log("状态管理设置完成");
        
    } catch (error) {
        console.error("状态管理设置失败:", error.message);
    }
}

3. 权限控制最佳实践

javascript

// 权限控制最佳实践
function permissionControlBestPractice() {
    try {
        // 根据用户权限控制按钮显示
        function updateButtonPermissions() {
            var userRole = getUserRole();
            
            // 清除现有按钮
            for(var i = 0; i < 10; i++) {
                try {
                    TANGER_OCX_OBJ.RemoveCustomButtonOnMenu(i);
                } catch (e) {
                    // 忽略删除不存在的按钮的错误
                }
            }
            
            switch(userRole) {
                case 'admin':
                    // 管理员显示所有按钮
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "管理", false, 3001);
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "设置", false, 3002);
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "日志", false, 3003);
                    break;
                case 'editor':
                    // 编辑者显示编辑相关按钮
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "编辑", true, 4001);
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "保存", true, 4002);
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(2, "打印", true, 4003);
                    break;
                case 'viewer':
                    // 查看者只显示查看相关按钮
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(0, "查看", true, 5001);
                    TANGER_OCX_OBJ.AddCustomButtonOnMenu(1, "打印", true, 5002);
                    break;
            }
        }
        
        // 初始化权限控制
        updateButtonPermissions();
        
        console.log("权限控制设置完成");
        
    } catch (error) {
        console.error("权限控制设置失败:", error.message);
    }
}

技术要点

版本兼容性：确保使用增强版及以上版本
按钮位置管理：正确管理按钮位置
按钮ID管理：使用唯一的按钮ID
文档依赖控制：合理设置IsNeedOpenDoc参数
事件处理：配合OnCustomButtonOnMenuCmd事件
权限控制：根据用户权限控制按钮显示
错误处理：完善的错误处理机制

总结

在菜单上添加自定义按钮相关方法为软航OFFICE文档控件提供了强大的菜单按钮定制能力。通过AddCustomButtonOnMenu方法可以在菜单右侧添加自定义按钮，通过RemoveCustomButtonOnMenu方法可以删除指定位置的按钮，通过OnCustomButtonOnMenuCmd事件可以处理按钮点击事件，为开发者提供了灵活的菜单按钮管理功能，大大提升了控件的可定制性和用户体验。

在菜单上添加自定义按钮相关方法 ​

添加菜单自定义按钮 ​

AddCustomButtonOnMenu ​

RemoveCustomButtonOnMenu ​

事件处理 ​

OnCustomButtonOnMenuCmd事件 ​

方法分类总结 ​

使用流程 ​

1. 创建菜单自定义按钮 ​

2. 管理按钮状态 ​

3. 处理按钮事件 ​

完整示例 ​

1. 基础按钮创建 ​

2. 高级按钮管理 ​

3. 动态按钮管理 ​

事件处理示例 ​

1. 基础事件处理 ​

2. 高级事件处理 ​

注意事项 ​

错误处理 ​

最佳实践 ​

1. 按钮设计最佳实践 ​

2. 状态管理最佳实践 ​

3. 权限控制最佳实践 ​

技术要点 ​

总结 ​

在菜单上添加自定义按钮相关方法

添加菜单自定义按钮

AddCustomButtonOnMenu

RemoveCustomButtonOnMenu

事件处理

OnCustomButtonOnMenuCmd事件

方法分类总结

使用流程

1. 创建菜单自定义按钮

2. 管理按钮状态

3. 处理按钮事件

完整示例

1. 基础按钮创建

2. 高级按钮管理

3. 动态按钮管理

事件处理示例

1. 基础事件处理

2. 高级事件处理

注意事项

错误处理

最佳实践

1. 按钮设计最佳实践

2. 状态管理最佳实践

3. 权限控制最佳实践

技术要点

总结