句柄类型参考

概述

本头文件定义了 oosxl 库中使用的不透明句柄类型。这些句柄提供对内部 C++ 对象的类型安全引用，同时保持清晰的 C 接口。

句柄类型

type DocumentHandle

表示 Excel 文档的不透明句柄。

此句柄由文档创建和加载函数返回，并作为所有文档操作的根对象。

使用示例:

DocumentHandle doc = doc_create();
// ... work with document
doc_release(doc);

type WorkbookHandle

表示 Excel 工作簿的不透明句柄。

工作簿包含一个或多个工作表，并管理工作簿级别的设置，如计算模式和日期系统。

使用示例:

DocumentHandle doc = doc_create();
WorkbookHandle workbook = doc_get_workbook(doc);
// ... work with workbook
doc_release(doc);

type WorksheetHandle

表示 Excel 工作表的不透明句柄。

工作表包含实际的单元格数据、格式化和工作表特定设置。

使用示例:

WorksheetHandle sheet = wb_add_worksheet(workbook, "Sheet1");
ws_set_text(sheet, 0, 0, "Hello World");
// ... work with worksheet

type StyleHandle

表示单元格样式的不透明句柄。

样式控制单元格的视觉外观，包括字体、颜色、边框、对齐方式和数字格式。

使用示例:

StyleHandle style = wb_make_normal_style(workbook);
style_set_font_color(style, 0xFF0000); // Red text
style_set_bold(style, 1); // Bold font
ws_set_cell_style(sheet, 0, 0, style);
style_release(style);

type RichtextHandle

表示富文本内容的不透明句柄。

富文本允许在单个单元格内使用多种格式化样式，实现复杂的文本呈现。

使用示例:

RichtextHandle rt = wb_make_richtext(workbook);
rt_append(rt, "Normal text", normal_style);
rt_append(rt, "Bold text", bold_style);
ws_set_richtext(sheet, 0, 0, rt);
rt_release(rt);

type TabledefHandle

表示 Excel 表格(列表对象)的不透明句柄。

表格提供结构化数据管理，具有内置的筛选、排序和自动格式化功能。

使用示例:

TabledefHandle table = ws_add_tabledef(sheet, "Table1", 0, 0, 10, 5);
td_set_display_name(table, "Sales Data");
// ... configure table

内存管理

DocumentHandle 必须正确管理以避免内存泄漏：

创建: DocumentHandle 由 doc_create() 或 doc_load() 函数创建
使用: DocumentHandle 可以在应用程序生命周期内使用
销毁: DocumentHandle 必须使用相应的释放函数释放

正确的清理顺序:

DocumentHandle doc = doc_create();
WorkbookHandle workbook = doc_get_workbook(doc);
WorksheetHandle sheet = wb_add_worksheet(workbook, "Sheet1");
StyleHandle style = wb_make_normal_style(workbook);
RichtextHandle rt = wb_make_richtext(workbook);

// ... use objects

rt_release(rt);
style_release(style);

// Release the DocumentHandle
doc_release(doc); // Releases workbook and worksheet automatically

句柄生命周期

文档句柄拥有其包含的工作簿、工作表和其他对象
释放文档句柄会自动释放所有子对象
样式和富文本句柄如果是独立的，建议显式释放
尝试使用已释放的句柄会导致未定义行为

空句柄

NULL 句柄值表示:

创建失败(内存不足、无效参数)
对象未找到(无效索引、缺少名称)
已释放的对象

始终检查 NULL 句柄：

DocumentHandle doc = doc_load("nonexistent.xlsx");
if (doc == NULL) {
    printf("Failed to load document\n");
    return;
}

类型安全

句柄系统提供编译时类型安全：

每种句柄类型都是不同的，不能意外互换
编译器会捕获类型不匹配
不透明结构防止直接访问内部实现

句柄类型参考

概述

句柄类型

内存管理

句柄生命周期

空句柄

类型安全

相关函数