软航科技文档中心

Appearance

自定义工具栏添加按钮 ​

添加自定义工具栏按钮 ​

AddCustomToolButton ​

语法：

javascript
AddCustomToolButton(ButtonText, ImgIndex)

功能：
为自定义工具栏添加按钮。

参数：

名称必选/可选数据类型说明
ButtonText必选string设定按钮上显示的文字
ImgIndex必选long设定按钮上面的图像

返回值：
数值型。返回的是按钮在自定义工具栏上面的索引，可以用于设定指定按钮的状态，或者在事件处理程序中标识按钮。

说明：
为自定义工具栏添加按钮。

参数说明：

  • ButtonText：如果设置为""字符串则为不显示字符串
  • ImgIndex：只能设置内部拥有的图片，传入的是图片索引

内置图片索引对照表：

索引图片名称说明
0拷贝复制功能图标
1剪切剪切功能图标
2删除删除功能图标
3新建文件新建文档图标
4打开文件打开文档图标
5文件保存保存文档图标
6搜索搜索功能图标
7帮助帮助功能图标
8粘贴粘贴功能图标
9打印打印功能图标
10打印预览打印预览图标
11属性属性功能图标
12重做重做功能图标
13替换替换功能图标
14撤销撤销功能图标

使用示例：

javascript
// 添加带文字和图片的按钮
OCX_OBJ.AddCustomToolButton("新建(0)", -1);
OCX_OBJ.AddCustomToolButton("word", 0);
OCX_OBJ.AddCustomToolButton("", 0);
OCX_OBJ.AddCustomToolButton("拷贝(1)", -1);
OCX_OBJ.AddCustomToolButton("", 1);
OCX_OBJ.AddCustomToolButton("剪切(2)", -1);
OCX_OBJ.AddCustomToolButton("", 2);
OCX_OBJ.AddCustomToolButton("保存(3)", -1);
OCX_OBJ.AddCustomToolButton("", 3);
OCX_OBJ.AddCustomToolButton("另存为(4)", -1);
OCX_OBJ.AddCustomToolButton("", 4);

设置自定义工具栏按钮状态 ​

SetCustomToolButtonStatus ​

语法：

javascript
SetCustomToolButtonStatus(ButtonIndex, IsEnable, IsVisible)

功能：
设定自定义工具栏上面按钮的状态。

参数：

名称必选/可选数据类型说明
ButtonIndex必选long指定设置的buttonIndex
IsEnable必选bool设定指定的按钮是否可用
IsVisible必选bool设定指定的按钮是否显示

返回值：
无返回值

说明：
设定自定义工具栏上面按钮的状态。

参数说明：

  • ButtonIndex：在调用AddCustomToolButton创建的时候得到
  • IsEnable：传True是可用，False为不可用
  • IsVisible：传True是显示，False是不显示

使用示例：

javascript
// 创建按钮并获取索引
var buttonIndex = OCX_OBJ.AddCustomToolButton("新建", 3);

// 设置按钮状态
OCX_OBJ.SetCustomToolButtonStatus(buttonIndex, true, true);  // 可用且显示
OCX_OBJ.SetCustomToolButtonStatus(buttonIndex, false, true); // 不可用但显示
OCX_OBJ.SetCustomToolButtonStatus(buttonIndex, true, false); // 可用但不显示

方法分类总结 ​

分类方法功能说明
按钮管理AddCustomToolButton添加自定义工具栏按钮创建自定义按钮
状态控制SetCustomToolButtonStatus设置按钮状态控制按钮可用性和可见性

使用流程 ​

1. 创建自定义工具栏按钮 ​

javascript
// 创建自定义工具栏按钮
function createCustomToolbar() {
    try {
        // 添加常用功能按钮
        var newButtonIndex = OCX_OBJ.AddCustomToolButton("新建", 3);
        var openButtonIndex = OCX_OBJ.AddCustomToolButton("打开", 4);
        var saveButtonIndex = OCX_OBJ.AddCustomToolButton("保存", 5);
        var printButtonIndex = OCX_OBJ.AddCustomToolButton("打印", 9);
        
        // 添加分隔符（空按钮）
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 添加编辑功能按钮
        var copyButtonIndex = OCX_OBJ.AddCustomToolButton("复制", 0);
        var cutButtonIndex = OCX_OBJ.AddCustomToolButton("剪切", 1);
        var pasteButtonIndex = OCX_OBJ.AddCustomToolButton("粘贴", 8);
        
        console.log("自定义工具栏创建完成");
        
        // 返回按钮索引，用于后续状态控制
        return {
            newButton: newButtonIndex,
            openButton: openButtonIndex,
            saveButton: saveButtonIndex,
            printButton: printButtonIndex,
            copyButton: copyButtonIndex,
            cutButton: cutButtonIndex,
            pasteButton: pasteButtonIndex
        };
        
    } catch (error) {
        console.error("创建自定义工具栏失败:", error.message);
    }
}

2. 管理按钮状态 ​

javascript
// 管理按钮状态
function manageButtonStatus(buttonIndexes) {
    try {
        // 根据文档状态控制按钮可用性
        if (OCX_OBJ.DocType === 0) {
            // 没有文档时，禁用某些按钮
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, false, true);
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.printButton, false, true);
        } else {
            // 有文档时，启用所有按钮
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, true, true);
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.printButton, true, true);
        }
        
        // 根据剪贴板状态控制粘贴按钮
        if (OCX_OBJ.ActiveDocument.Selection.Paste() === false) {
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.pasteButton, false, true);
        } else {
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.pasteButton, true, true);
        }
        
        console.log("按钮状态管理完成");
        
    } catch (error) {
        console.error("按钮状态管理失败:", error.message);
    }
}

3. 动态更新工具栏 ​

javascript
// 动态更新工具栏
function updateToolbar() {
    try {
        // 根据用户权限显示/隐藏按钮
        var userRole = getUserRole(); // 假设的用户角色获取函数
        
        if (userRole === 'admin') {
            // 管理员显示所有按钮
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, true, true);
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.printButton, true, true);
        } else if (userRole === 'user') {
            // 普通用户隐藏某些按钮
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, false, false);
            OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.printButton, false, false);
        }
        
        console.log("工具栏更新完成");
        
    } catch (error) {
        console.error("工具栏更新失败:", error.message);
    }
}

完整示例 ​

1. 基础工具栏创建 ​

javascript
// 基础工具栏创建示例
function createBasicToolbar() {
    try {
        // 创建文件操作按钮
        var newButton = OCX_OBJ.AddCustomToolButton("新建", 3);
        var openButton = OCX_OBJ.AddCustomToolButton("打开", 4);
        var saveButton = OCX_OBJ.AddCustomToolButton("保存", 5);
        
        // 添加分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 创建编辑操作按钮
        var copyButton = OCX_OBJ.AddCustomToolButton("复制", 0);
        var cutButton = OCX_OBJ.AddCustomToolButton("剪切", 1);
        var pasteButton = OCX_OBJ.AddCustomToolButton("粘贴", 8);
        
        // 添加分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 创建打印操作按钮
        var printButton = OCX_OBJ.AddCustomToolButton("打印", 9);
        var printPreviewButton = OCX_OBJ.AddCustomToolButton("预览", 10);
        
        console.log("基础工具栏创建完成");
        
    } catch (error) {
        console.error("基础工具栏创建失败:", error.message);
    }
}

2. 高级工具栏管理 ​

javascript
// 高级工具栏管理示例
function createAdvancedToolbar() {
    try {
        var buttonIndexes = {};
        
        // 文件操作组
        buttonIndexes.newButton = OCX_OBJ.AddCustomToolButton("新建", 3);
        buttonIndexes.openButton = OCX_OBJ.AddCustomToolButton("打开", 4);
        buttonIndexes.saveButton = OCX_OBJ.AddCustomToolButton("保存", 5);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 编辑操作组
        buttonIndexes.undoButton = OCX_OBJ.AddCustomToolButton("撤销", 14);
        buttonIndexes.redoButton = OCX_OBJ.AddCustomToolButton("重做", 12);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        buttonIndexes.cutButton = OCX_OBJ.AddCustomToolButton("剪切", 1);
        buttonIndexes.copyButton = OCX_OBJ.AddCustomToolButton("复制", 0);
        buttonIndexes.pasteButton = OCX_OBJ.AddCustomToolButton("粘贴", 8);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 查找替换组
        buttonIndexes.searchButton = OCX_OBJ.AddCustomToolButton("查找", 6);
        buttonIndexes.replaceButton = OCX_OBJ.AddCustomToolButton("替换", 13);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 打印操作组
        buttonIndexes.printPreviewButton = OCX_OBJ.AddCustomToolButton("预览", 10);
        buttonIndexes.printButton = OCX_OBJ.AddCustomToolButton("打印", 9);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 帮助操作组
        buttonIndexes.helpButton = OCX_OBJ.AddCustomToolButton("帮助", 7);
        buttonIndexes.propertiesButton = OCX_OBJ.AddCustomToolButton("属性", 11);
        
        console.log("高级工具栏创建完成");
        return buttonIndexes;
        
    } catch (error) {
        console.error("高级工具栏创建失败:", error.message);
    }
}

3. 按钮事件处理 ​

javascript
// 按钮事件处理示例
function setupButtonEvents(buttonIndexes) {
    try {
        // 为按钮添加点击事件处理
        // 注意：这里需要根据实际的事件处理机制来实现
        
        // 新建按钮事件
        function onNewButtonClick() {
            OCX_OBJ.CreateNew("Word.Document");
        }
        
        // 打开按钮事件
        function onOpenButtonClick() {
            OCX_OBJ.ShowDialog(1); // 显示打开对话框
        }
        
        // 保存按钮事件
        function onSaveButtonClick() {
            OCX_OBJ.SaveToLocal();
        }
        
        // 打印按钮事件
        function onPrintButtonClick() {
            OCX_OBJ.PrintOut();
        }
        
        // 打印预览按钮事件
        function onPrintPreviewButtonClick() {
            OCX_OBJ.PrintPreview();
        }
        
        console.log("按钮事件处理设置完成");
        
    } catch (error) {
        console.error("按钮事件处理设置失败:", error.message);
    }
}

注意事项 ​

  1. 版本要求：此方法是增强版及以上版本所有
  2. 图片索引：只能使用内置的15张图片，索引范围0-14
  3. 按钮索引：AddCustomToolButton返回的索引用于后续状态控制
  4. 状态管理：及时更新按钮状态以提供良好的用户体验
  5. 事件处理：需要配合相应的事件处理机制
  6. 权限控制：根据用户权限显示/隐藏相应按钮
  7. 错误处理：实现完善的错误处理机制

错误处理 ​

javascript
// 自定义工具栏错误处理
function handleToolbarError(operation, error) {
    console.error("自定义工具栏操作失败:", operation, error.message);
    
    switch(operation) {
        case 'AddCustomToolButton':
            console.log("添加按钮失败，请检查:");
            console.log("1. 按钮文字参数是否有效");
            console.log("2. 图片索引是否在0-14范围内");
            console.log("3. 控件版本是否支持此功能");
            break;
        case 'SetCustomToolButtonStatus':
            console.log("设置按钮状态失败，请检查:");
            console.log("1. 按钮索引是否有效");
            console.log("2. 状态参数是否正确");
            console.log("3. 按钮是否已创建");
            break;
        default:
            console.log("未知自定义工具栏操作失败");
    }
}

最佳实践 ​

1. 工具栏设计最佳实践 ​

javascript
// 工具栏设计最佳实践
function toolbarDesignBestPractice() {
    try {
        // 按功能分组设计工具栏
        var buttonIndexes = {};
        
        // 文件操作组
        buttonIndexes.newButton = OCX_OBJ.AddCustomToolButton("新建", 3);
        buttonIndexes.openButton = OCX_OBJ.AddCustomToolButton("打开", 4);
        buttonIndexes.saveButton = OCX_OBJ.AddCustomToolButton("保存", 5);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        // 编辑操作组
        buttonIndexes.undoButton = OCX_OBJ.AddCustomToolButton("撤销", 14);
        buttonIndexes.redoButton = OCX_OBJ.AddCustomToolButton("重做", 12);
        
        // 分隔符
        OCX_OBJ.AddCustomToolButton("", -1);
        
        buttonIndexes.cutButton = OCX_OBJ.AddCustomToolButton("剪切", 1);
        buttonIndexes.copyButton = OCX_OBJ.AddCustomToolButton("复制", 0);
        buttonIndexes.pasteButton = OCX_OBJ.AddCustomToolButton("粘贴", 8);
        
        // 根据文档状态初始化按钮状态
        updateButtonStates(buttonIndexes);
        
        console.log("工具栏设计完成");
        return buttonIndexes;
        
    } catch (error) {
        console.error("工具栏设计失败:", error.message);
    }
}

2. 状态管理最佳实践 ​

javascript
// 状态管理最佳实践
function stateManagementBestPractice(buttonIndexes) {
    try {
        // 根据文档状态更新按钮状态
        function updateButtonStates() {
            var docType = OCX_OBJ.DocType;
            
            if (docType === 0) {
                // 没有文档时
                OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, false, true);
                OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.undoButton, false, true);
                OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.redoButton, false, true);
            } else {
                // 有文档时
                OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, true, true);
                OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.undoButton, true, true);
                OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.redoButton, true, true);
            }
        }
        
        // 定期更新按钮状态
        setInterval(updateButtonStates, 1000);
        
        console.log("状态管理设置完成");
        
    } catch (error) {
        console.error("状态管理设置失败:", error.message);
    }
}

3. 权限控制最佳实践 ​

javascript
// 权限控制最佳实践
function permissionControlBestPractice(buttonIndexes) {
    try {
        // 根据用户权限控制按钮显示
        function updateButtonPermissions() {
            var userRole = getUserRole();
            
            switch(userRole) {
                case 'admin':
                    // 管理员显示所有按钮
                    Object.keys(buttonIndexes).forEach(function(key) {
                        OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes[key], true, true);
                    });
                    break;
                case 'editor':
                    // 编辑者隐藏某些按钮
                    OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.deleteButton, false, false);
                    break;
                case 'viewer':
                    // 查看者只显示查看相关按钮
                    OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.newButton, false, false);
                    OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.saveButton, false, false);
                    OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.cutButton, false, false);
                    OCX_OBJ.SetCustomToolButtonStatus(buttonIndexes.pasteButton, false, false);
                    break;
            }
        }
        
        // 初始化权限控制
        updateButtonPermissions();
        
        console.log("权限控制设置完成");
        
    } catch (error) {
        console.error("权限控制设置失败:", error.message);
    }
}

技术要点 ​

  1. 版本兼容性：确保使用增强版及以上版本
  2. 图片资源：只能使用内置的15张图片
  3. 索引管理：正确管理按钮索引
  4. 状态同步：及时更新按钮状态
  5. 事件处理：配合相应的事件处理机制
  6. 权限控制：根据用户权限控制按钮显示
  7. 错误处理：完善的错误处理机制

总结 ​

自定义工具栏添加按钮功能为软航OFFICE文档控件提供了强大的工具栏定制能力。通过AddCustomToolButton方法可以创建自定义按钮，通过SetCustomToolButtonStatus方法可以控制按钮状态，为开发者提供了灵活的工具栏管理功能，大大提升了控件的可定制性和用户体验。

Copyright © 2025 软航科技