表格控件 (Grid Control)¶

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

表格控件是 SOUI 扩展控件中的一个重要组件，提供了类似 Excel 的表格功能，支持多种单元格类型、编辑、选择、排序等功能。

概述¶

SGridCtrl 是一个功能丰富的表格控件，可以显示和编辑表格数据。它支持多种单元格类型，包括文本、数字、复选框、颜色选择器、日期时间选择器、URL 链接等。控件还支持单元格合并、拖放操作、自定义编辑器等功能。

基本用法¶

在 XML 中声明表格控件¶

<gridctrl name="grid_test" rowCount="20" colCount="10" fixedRows="1" fixedCols="1"
          defRowHeight="25" defColWidth="80" gridLines="3" 
          gridLineColor="rgb(200,200,200)" editable="1" />

在代码中初始化表格控件¶

// 获取表格控件
SGridCtrl* pGrid = FindChildByName2<SGridCtrl>(L"grid_test");
if (pGrid)
{
    // 设置表格尺寸
    pGrid->SetRowCount(20);
    pGrid->SetColumnCount(10);
    pGrid->SetFixedRowCount(1);     // 固定行数（表头）
    pGrid->SetFixedColumnCount(1);  // 固定列数（行标题）

    // 设置列标题
    pGrid->SetItemText(0, 0, _T(""));
    pGrid->SetItemText(0, 1, _T("Name"));
    pGrid->SetItemText(0, 2, _T("Age"));
    // ... 设置其他列标题

    // 设置行标题
    for (int row = 1; row < 20; row++)
    {
        SStringT strRow;
        strRow.Format(_T("Row %d"), row);
        pGrid->SetItemText(row, 0, strRow);
    }

    // 填充数据
    pGrid->SetItemText(1, 1, _T("Alice"));
    pGrid->SetItemText(1, 2, _T("25"));
    // ... 填充其他数据
}

单元格类型¶

SGridCtrl 支持多种单元格类型，可以通过 SetCellType 方法设置：

单元格类型	描述
CELL_TYPE_TEXT	标准文本单元格（默认）
CELL_TYPE_NUMERIC	数字输入单元格
CELL_TYPE_URL	URL/超链接单元格
CELL_TYPE_CHECKBOX	复选框单元格
CELL_TYPE_OPTION	下拉列表单元格
CELL_TYPE_COLOR	颜色选择器单元格
CELL_TYPE_DATETIMEPICKER	日期时间选择器单元格
CELL_TYPE_CUSTOM	自定义单元格类型

设置单元格类型示例¶

// 设置颜色选择器单元格
pGrid->SetCellType(row, col, CELL_TYPE_COLOR);

// 设置日期时间选择器单元格
pGrid->SetCellType(row, col, CELL_TYPE_DATETIMEPICKER);

// 设置复选框单元格
pGrid->SetCellType(row, col, CELL_TYPE_CHECKBOX);

// 设置URL单元格
pGrid->SetCellType(row, col, CELL_TYPE_URL);

操作特定类型单元格¶

// 操作复选框单元格
SAutoRefPtr<IGridCellCheck> pCheckCell = pGrid->GetCellOp<IGridCellCheck>(row, col);
pCheckCell->SetCheck(TRUE);

// 操作颜色单元格
SAutoRefPtr<IGridCellColor> pColorCell = pGrid->GetCellOp<IGridCellColor>(row, col);
pColorCell->SetColor(RGB(255, 0, 0));

表格属性¶

尺寸属性¶

属性	描述
rowCount	行数
colCount	列数
fixedRows	固定行数（通常用于表头）
fixedCols	固定列数（通常用于行标题）
defRowHeight	默认行高
defColWidth	默认列宽

外观属性¶

属性	描述
gridLines	网格线显示方式（0=无，1=水平线，2=垂直线，3=全部）
gridLineColor	网格线颜色
gridBkColor	表格背景颜色

行为属性¶

属性	描述
editable	是否可编辑
listMode	列表模式
singleRowSel	单行选择模式
singleColSel	单列选择模式

单元格操作¶

设置和获取单元格数据¶

// 设置单元格文本
pGrid->SetItemText(row, col, _T("Hello World"));

// 获取单元格文本
SStringT text;
pGrid->GetItemText(row, col, &text);

// 设置单元格用户数据
pGrid->SetItemData(row, col, (LPARAM)userData);

// 获取单元格用户数据
LPARAM userData = pGrid->GetItemData(row, col);

单元格尺寸¶

// 设置行高
pGrid->SetRowHeight(row, 30);

// 设置列宽
pGrid->SetColumnWidth(col, 100);

// 获取行高
int rowHeight = pGrid->GetRowHeight(row);

// 获取列宽
int colWidth = pGrid->GetColumnWidth(col);

选择操作¶

// 设置选中范围
pGrid->SetSelectedRange(minRow, minCol, maxRow, maxCol, TRUE);

// 获取选中范围
SCELLRANGE range;
pGrid->GetSelectedCellRange(&range);

// 清除选择
pGrid->ClearSelection();

// 全选
pGrid->SelectAll();

// 选择行
pGrid->SelectRow(row, FALSE);

// 选择列
pGrid->SelectColumn(col, FALSE);

单元格合并¶

// 合并单元格
pGrid->MergeCells(startRow, startCol, endRow, endCol);

// 合并单元格（使用范围结构）
SCellRange range(1, 1, 3, 3);
pGrid->MergeCells(&range);

// 取消合并单元格
pGrid->UnmergeCells(row, col);

// 检查单元格是否已合并
BOOL isMerged = pGrid->IsCellMerged(row, col);

编辑操作¶

// 开始编辑
SCellID cell(1, 1);
pGrid->StartEdit(cell);

// 结束编辑
pGrid->EndEdit(TRUE);  // TRUE表示保存更改，FALSE表示取消更改

// 检查是否正在编辑
BOOL isInEdit = pGrid->IsInEdit();

自定义编辑器¶

可以通过事件处理来自定义单元格的编辑器：

// 处理获取编辑器样式事件
void OnGridGetInplaceStyle(IEvtArgs *e){
    EventGridGetInplaceStyle* pEvt = sobj_cast<EventGridGetInplaceStyle>(e);
    IGridCell * pCell = pEvt->pCell;
    int cellType = pCell->GetType();

    if(cellType == CELL_TYPE_OPTION){
        const wchar_t * kOptionStyle = L"<combobox dropDown=\"0\" dropHeight=\"300\"> \
            <liststyle itemHeight=\"30\" />\
            <editstyle inset=\"5,0,5,0\" />\
        </combobox>";
        pEvt->pstrXmlStyle->Assign(kOptionStyle);
    }
}

// 初始化编辑器数据
void OnGridInitInplaceWnd(IEvtArgs* e)
{
    EventGridInitInplaceWnd* pEvt = sobj_cast<EventGridInitInplaceWnd>(e);
    IGridCell * pCell = pEvt->pCell;
    IGridInplaceWnd * pInplaceWnd = pEvt->pInplaceWnd;

    if(pCell->GetType() == CELL_TYPE_OPTION){
        SComboBox * pCombo = (SComboBox *)pInplaceWnd->GetIWindow();
        for(int i=0;i<10;i++){
            pCombo->InsertItem(i,SStringT().Format(_T("option %d"),i),0,0);
        }
        SStringT text = pCell->GetText();
        int nSel = pCombo->FindString(text);
        pCombo->SetCurSel(nSel);
        pInplaceWnd->InitData(pCell->GetText());
        pEvt->bInited = TRUE;
    }
}

事件处理¶

在 XML 中绑定事件：

<gridctrl name="grid_test" 
          onEventGridInitInplaceWnd="OnGridInitInplaceWnd"
          onEventGridGetInplaceStyle="OnGridGetInplaceStyle" />

最佳实践¶

性能优化：对于大量数据，考虑使用虚拟模式或分页加载
用户体验：合理设置默认行高和列宽，确保内容可读
类型匹配：为不同数据类型选择合适的单元格类型
验证机制：在编辑时添加数据验证逻辑
键盘导航：确保键盘操作流畅，支持常见的导航快捷键

常见问题¶

单元格编辑不生效：检查是否设置了 editable="1"
固定行列显示异常：确保 fixedRows 和 fixedCols 设置正确
自定义编辑器不显示：检查事件绑定和样式定义是否正确
单元格合并显示问题：确保合并范围不重叠且有效