数据表格（DataGrid）

电子表格风格网格控件。与「表格」TableWidget 独立：本控件面向 A1 区域、冻结窗格、剪贴板与公式等能力。

功能概览

• 逻辑行列 + 稀疏 @CELL 存储；@W / @RH 可变列宽行高
• 工作表模式：列字母 A/B/C…、行号 1 基；可视区外虚拟扩维
• 可编辑：单击再点/双击 / F2 / 键入即编辑；Enter 提交下移 / Esc 取消 / Tab
• 键盘：方向键、Home/End、PgUp/PgDn、Shift 扩选
• 剪贴板：Ctrl+C / Ctrl+X / Ctrl+V（TSV）、Delete 清空选区、Ctrl+A 全选
• 选区：矩形、Ctrl 非连续多选、列头/行头选列行、角单元格全选
• 拖拽列头/行头边缘调列宽行高；冻结行/列滚动
• 行列结构：插入行 / 删除行 / 插入列 / 删除列、清空、排序(列, [升序])
• 公式：取单元格显示 对 =SUM / =AVG / =IF 等求值；非编辑态显示结果
• 事件：单元格被单击/双击、当前单元格改变、单元格改变、选区被改变、开始编辑、结束编辑
• 单元格嵌入控件：加入控件(行,列,组件名) 返回真实控件名，可 .置事件 / 读写属性

网格数据格式

@DATAGRID|cols|rows
@CELL|row|col|text
@W|72|80|...
@RH|0|28
@STYLE|row|col|fore|back|foreGrad|backGrad|font|fontSize|wrap

单元格文本转义：| → \p，\ → \\，换行 → \n。默认维度：8|20。

设计期属性

属性	说明
名称 / 左边 / 顶边 / 宽度 / 高度	布局
可见 / 启用	行为
可编辑	允许就地编辑与剪贴板写入
工作表模式	显示列字母与行号
显示行头	工作表模式下是否显示左侧行号列
角单元格文本	左上角单元格文字
行头宽度	-1=按行号位数自适应；≥24 为固定像素
表头高度	列字母行高度
默认列宽 / 默认行高	未单独设置时的单元格尺寸
冻结列数 / 冻结行数	滚动时固定的首列/首行数
背景色 / 显示边框 / …	外观
网格数据	@DATAGRID 文本

运行时方法

方法	说明
置行数 / 取行数 / 置列数 / 取列数	逻辑维度
置单元格(行,列,文本) / 取单元格	0 基
置单元格文本("A1", …) / 取单元格文本("A1")	A1 / A1:C3
置当前单元格 / 取当前行 / 取当前列	当前格
置选中区域 / 取选中区域 / 选中全部 / 清空选中	选区
滚动到单元格	滚入可视
置工作表模式 / 取工作表模式	列字母/行号开关
置列宽 / 取列宽 / 置行高 / 取行高	像素尺寸
置冻结列数 / 取冻结列数 / 置冻结行数 / 取冻结行数	冻结窗格
置显示行头 / 取显示行头	行号列开关
置角单元格文本 / 取角单元格文本	左上角文字
置区域文字色 / 置区域背景色	区域前景/背景
置区域文字渐变色 / 置区域背景渐变色	渐变 #A-#B
置区域字体 / 置区域字号 / 置区域自动换行	字体与换行
清空区域格式	清除样式
插入行 / 删除行 / 插入列 / 删除列	结构操作（可选第二参数数量）
清空	清空全部单元格文本，保留维度
排序(列, [升序])	按列文本排序
取单元格显示(行,列)	公式格返回求值结果
加入控件(行,列,组件名,[宽],[高])	嵌入按钮/下拉框等，返回控件名

嵌入控件示例

文本 按钮 = 数据表格1.加入控件(0, 2, "按钮", 64, 24)
数据表格1.置单元格(0, 2, "操作")
按钮.文本 = "确定"
按钮.置事件("单击", &单元格按钮单击)

事件

事件	参数
单元格被单击 / 单元格被双击	行, 列, 区域
当前单元格改变 / 单元格改变	行, 列, 区域
选区被改变	区域
开始编辑 / 结束编辑	行, 列, 区域

快捷键（运行时，焦点在数据表格上）

键	行为
方向键 / Home / End / PgUp / PgDn	移动当前格（Shift=扩选）
Tab / Shift+Tab	提交编辑并左右移
Enter	提交并下移
Esc	取消编辑
F2 / 双击	进入编辑
可打印字符	进入编辑并替换
Ctrl+C / X / V	复制 / 剪切 / 粘贴 TSV
Ctrl+A	全选
Ctrl+点击	切换单元格/列/行选中
Delete	清空选区文本

鼠标

操作	行为
拖拽列头右缘 / 行头下缘	调整列宽 / 行高
点击角单元格	全选
点击列头 / 行头	选列 / 选行（Ctrl 切换，Shift 扩选）

后续

见 docs/datagrid-plan.md：单元格样式、公式、行列插入删除等。