软航科技文档中心

Appearance

在自定义工具栏上添加按钮的相关事件 ​

概述 ​

本节介绍软航OFFICE文档控件提供的在自定义工具栏上添加按钮的相关事件，这些事件允许开发者在用户与自定义工具栏上的按钮交互时进行响应和处理，为文档管理系统提供完整的自定义工具栏按钮事件处理能力。

自定义工具栏按钮事件 ​

OnCustomToolBarCommand ​

语法：

javascript
OnCustomToolBarCommand(ButtonIndex)

功能：
该事件处理自己定义的自定义工具栏的命令点击事件。

参数：

名称必选/可选数据类型说明
ButtonIndex必选long自定义按钮位置

说明：
参数为调用AddCustomToolButton的返回值，即自定义工具栏上面的按钮的序号。用户可以在该事件判断点击的按钮执行相应的方法。

使用示例：

javascript
// 基本用法
<script language="javascript" for="控件对象ID" event="OnCustomToolBarCommand(btnIdx)">
    ShowTipMessage("TIP:", "" + btnIdx, false);
    if (0 == btnIdx) { // 用户单击第一个按钮新建office文件
        CreateNew("Word.Document");
    }
</script>

// 根据按钮索引处理不同操作
<script language="javascript" for="TANGER_OCX" event="OnCustomToolBarCommand(btnIdx)">
    console.log("自定义工具栏按钮点击，索引:", btnIdx);
    
    switch(btnIdx) {
        case 0:
            console.log("执行新建Word文档操作");
            CreateNew("Word.Document");
            break;
        case 1:
            console.log("执行新建Excel文档操作");
            CreateNew("Excel.Sheet");
            break;
        case 2:
            console.log("执行新建PowerPoint文档操作");
            CreateNew("PowerPoint.Presentation");
            break;
        case 3:
            console.log("执行保存文档操作");
            SaveDocument();
            break;
        case 4:
            console.log("执行打印文档操作");
            PrintDocument();
            break;
        default:
            console.log("未知按钮操作，索引:", btnIdx);
    }
</script>

// 显示按钮提示信息
<script language="javascript" for="TANGER_OCX" event="OnCustomToolBarCommand(btnIdx)">
    var buttonNames = {
        0: "新建Word文档",
        1: "新建Excel文档", 
        2: "新建PowerPoint文档",
        3: "保存文档",
        4: "打印文档",
        5: "文档转换",
        6: "文档加密"
    };
    
    var buttonName = buttonNames[btnIdx] || "未知按钮";
    ShowTipMessage("按钮提示:", buttonName, false);
    console.log("用户点击了:", buttonName);
</script>

// 记录按钮操作
<script language="javascript" for="TANGER_OCX" event="OnCustomToolBarCommand(btnIdx)">
    var timestamp = new Date().toISOString();
    console.log("自定义工具栏按钮操作记录:");
    console.log("按钮索引:", btnIdx);
    console.log("操作时间:", timestamp);
    
    // 可以记录用户按钮操作日志
    // logUserAction('toolbar_button', btnIdx, timestamp);
</script>

// 根据按钮功能分组处理
<script language="javascript" for="TANGER_OCX" event="OnCustomToolBarCommand(btnIdx)">
    // 文档操作按钮 (0-2)
    if (btnIdx >= 0 && btnIdx <= 2) {
        console.log("文档操作按钮被点击:", btnIdx);
        handleDocumentOperation(btnIdx);
    }
    // 文件操作按钮 (3-4)
    else if (btnIdx >= 3 && btnIdx <= 4) {
        console.log("文件操作按钮被点击:", btnIdx);
        handleFileOperation(btnIdx);
    }
    // 工具操作按钮 (5-6)
    else if (btnIdx >= 5 && btnIdx <= 6) {
        console.log("工具操作按钮被点击:", btnIdx);
        handleToolOperation(btnIdx);
    }
    else {
        console.log("其他按钮被点击:", btnIdx);
    }
</script>

// 处理文档操作
function handleDocumentOperation(btnIdx) {
    switch(btnIdx) {
        case 0:
            CreateNew("Word.Document");
            break;
        case 1:
            CreateNew("Excel.Sheet");
            break;
        case 2:
            CreateNew("PowerPoint.Presentation");
            break;
    }
}

// 处理文件操作
function handleFileOperation(btnIdx) {
    switch(btnIdx) {
        case 3:
            SaveDocument();
            break;
        case 4:
            PrintDocument();
            break;
    }
}

// 处理工具操作
function handleToolOperation(btnIdx) {
    switch(btnIdx) {
        case 5:
            ConvertDocument();
            break;
        case 6:
            EncryptDocument();
            break;
    }
}

方法分类总结 ​

分类事件功能说明
自定义工具栏按钮OnCustomToolBarCommand自定义工具栏按钮点击时触发自定义工具栏按钮操作

使用流程 ​

1. 基本自定义工具栏按钮事件处理流程 ​

javascript
// 基本自定义工具栏按钮事件处理流程
function basicCustomToolBarButtonEventHandling() {
    // 自定义工具栏按钮事件处理
    function handleCustomToolBarButton(btnIdx) {
        console.log("自定义工具栏按钮点击:", btnIdx);
        // 处理自定义工具栏按钮
    }
}

2. 高级自定义工具栏按钮事件处理流程 ​

javascript
// 高级自定义工具栏按钮事件处理流程
function advancedCustomToolBarButtonEventHandling() {
    // 自定义工具栏按钮事件配置
    var customToolBarButtonEventConfig = {
        enableLogging: true,
        enableCustomHandling: true,
        enableButtonValidation: true
    };
    
    // 处理自定义工具栏按钮
    function handleAdvancedCustomToolBarButton(btnIdx) {
        if (customToolBarButtonEventConfig.enableLogging) {
            console.log("自定义工具栏按钮日志:", btnIdx);
        }
        
        if (customToolBarButtonEventConfig.enableCustomHandling) {
            // 执行自定义处理
        }
    }
}

3. 自定义工具栏按钮事件质量控制流程 ​

javascript
// 自定义工具栏按钮事件质量控制流程
function customToolBarButtonEventQualityControl() {
    // 处理自定义工具栏按钮事件质量控制
    function controlCustomToolBarButtonEventQuality() {
        var customToolBarButtonEventQuality = {
            totalEvents: 0,
            successfulEvents: 0,
            failedEvents: 0,
            qualityScore: 0
        };
        
        // 计算质量分数
        if (customToolBarButtonEventQuality.totalEvents > 0) {
            customToolBarButtonEventQuality.qualityScore = (customToolBarButtonEventQuality.successfulEvents / customToolBarButtonEventQuality.totalEvents) * 100;
        }
        
        console.log("自定义工具栏按钮事件质量控制:", customToolBarButtonEventQuality);
        return customToolBarButtonEventQuality;
    }
    
    // 执行质量控制
    var qualityResult = controlCustomToolBarButtonEventQuality();
    console.log("自定义工具栏按钮事件质量控制结果:", qualityResult);
}

完整示例 ​

1. 基础自定义工具栏按钮事件处理 ​

javascript
// 基础自定义工具栏按钮事件处理示例
function basicCustomToolBarButtonEventHandling() {
    // 自定义工具栏按钮处理
    function onCustomToolBarButton(btnIdx) {
        console.log("自定义工具栏按钮:", btnIdx);
        // 处理自定义工具栏按钮
    }
}

2. 高级自定义工具栏按钮事件处理 ​

javascript
// 高级自定义工具栏按钮事件处理示例
function advancedCustomToolBarButtonEventHandling() {
    // 自定义工具栏按钮事件管理
    var customToolBarButtonEventManager = {
        isButtonEnabled: true,
        isButtonLoggingEnabled: true,
        isButtonValidationEnabled: true
    };
    
    // 处理自定义工具栏按钮
    function handleCustomToolBarButton(btnIdx) {
        if (customToolBarButtonEventManager.isButtonEnabled) {
            console.log("自定义工具栏按钮处理:", btnIdx);
            // 处理自定义工具栏按钮
        }
    }
}

3. 自定义工具栏按钮事件质量控制 ​

javascript
// 自定义工具栏按钮事件质量控制示例
function customToolBarButtonEventQualityControl() {
    // 自定义工具栏按钮事件质量控制
    function controlCustomToolBarButtonEventQuality() {
        var customToolBarButtonEventQuality = {
            buttonClicks: 0,
            buttonErrors: 0,
            buttonSuccess: 0,
            errors: []
        };
        
        // 监控自定义工具栏按钮事件质量
        function monitorCustomToolBarButtonEventQuality(eventType, success) {
            if (success) {
                customToolBarButtonEventQuality[eventType]++;
            } else {
                customToolBarButtonEventQuality.errors.push({
                    event: eventType,
                    timestamp: new Date().toISOString()
                });
            }
        }
        
        console.log("自定义工具栏按钮事件质量控制:", customToolBarButtonEventQuality);
        return customToolBarButtonEventQuality;
    }
    
    // 执行质量控制
    var qualityResult = controlCustomToolBarButtonEventQuality();
    console.log("自定义工具栏按钮事件质量控制结果:", qualityResult);
}

注意事项 ​

  1. 事件顺序：注意自定义工具栏按钮事件触发的顺序，确保在正确的时机执行相应操作
  2. 参数验证：验证自定义工具栏按钮事件参数的有效性，避免空值或无效值
  3. 错误处理：实现完善的错误处理机制
  4. 性能考虑：避免在自定义工具栏按钮事件处理中执行耗时操作
  5. 资源管理：及时清理不需要的资源
  6. 状态同步：保持自定义工具栏按钮状态的一致性
  7. 用户体验：确保自定义工具栏按钮事件处理不影响用户体验

错误处理 ​

javascript
// 自定义工具栏按钮事件错误处理
function handleCustomToolBarButtonEventError(eventType, error) {
    console.error("自定义工具栏按钮事件处理失败:", eventType, error.message);
    
    switch(eventType) {
        case 'OnCustomToolBarCommand':
            console.log("自定义工具栏按钮事件失败，请检查:");
            console.log("1. 自定义工具栏按钮是否正确添加");
            console.log("2. 按钮索引是否正确");
            console.log("3. 按钮事件处理是否正确");
            break;
        default:
            console.log("未知自定义工具栏按钮事件处理失败");
    }
}

最佳实践 ​

1. 自定义工具栏按钮事件管理最佳实践 ​

javascript
// 自定义工具栏按钮事件管理最佳实践
function customToolBarButtonEventManagementBestPractice() {
    // 自定义工具栏按钮事件配置
    var customToolBarButtonEventConfig = {
        enableLogging: true,
        enableCustomHandling: true,
        enableButtonValidation: true,
        enableQualityControl: true
    };
    
    // 应用自定义工具栏按钮事件配置
    function applyCustomToolBarButtonEventConfig() {
        try {
            // 设置自定义工具栏按钮事件处理
            if (customToolBarButtonEventConfig.enableLogging) {
                console.log("自定义工具栏按钮事件日志已启用");
            }
            
            if (customToolBarButtonEventConfig.enableCustomHandling) {
                console.log("自定义工具栏按钮处理已启用");
            }
            
            console.log("自定义工具栏按钮事件配置应用成功");
        } catch (error) {
            handleCustomToolBarButtonEventError('applyCustomToolBarButtonEventConfig', error);
        }
    }
    
    // 应用配置
    applyCustomToolBarButtonEventConfig();
}

2. 自定义工具栏按钮事件质量控制最佳实践 ​

javascript
// 自定义工具栏按钮事件质量控制最佳实践
function customToolBarButtonEventQualityControlBestPractice() {
    // 自定义工具栏按钮事件质量控制
    function controlCustomToolBarButtonEventQuality() {
        try {
            // 自定义工具栏按钮事件质量控制
            var customToolBarButtonEventQuality = {
                totalEvents: 0,
                successfulEvents: 0,
                failedEvents: 0,
                qualityScore: 0
            };
            
            // 计算质量分数
            if (customToolBarButtonEventQuality.totalEvents > 0) {
                customToolBarButtonEventQuality.qualityScore = (customToolBarButtonEventQuality.successfulEvents / customToolBarButtonEventQuality.totalEvents) * 100;
            }
            
            console.log("自定义工具栏按钮事件质量控制完成:", customToolBarButtonEventQuality);
            return customToolBarButtonEventQuality;
        } catch (error) {
            console.error("自定义工具栏按钮事件质量控制失败:", error.message);
            return null;
        }
    }
    
    // 执行质量控制
    var qualityResult = controlCustomToolBarButtonEventQuality();
    console.log("自定义工具栏按钮事件质量控制结果:", qualityResult);
}

技术要点 ​

  1. 事件顺序：注意自定义工具栏按钮事件触发的顺序，确保在正确的时机执行相应操作
  2. 参数验证：验证自定义工具栏按钮事件参数的有效性，避免空值或无效值
  3. 错误处理：完善的错误处理机制
  4. 性能优化：避免在自定义工具栏按钮事件处理中执行耗时操作
  5. 资源管理：及时清理不需要的资源
  6. 状态同步：保持自定义工具栏按钮状态的一致性
  7. 用户体验：确保自定义工具栏按钮事件处理不影响用户体验

Copyright © 2025 软航科技