选择器：
datagrid· 设计器组件： 数据表格 · 按名称：datagrid#名称或#名称
硬约束与叠画
- 控件名来自窗口 XML「名称」；属性赋值无括号（如
标题 = "确定"），方法调用必须带括号（如刷新()）。 - 事件写
函数 控件名.事件名(参数…)，形参类型以本页事件表为准。 - 任意控件客户区叠画用支持库 绘制类：
绘制类 g→g.绑组件(本控件名)（组件名无引号）。画布场景编辑见 画布控件。 - 字体对象见绘制文档中的字体类；
置字体(字体类)将字体应用到本控件。 - 不要虚构未列出的方法；YSS 键见下文与 YSS.md。
属性
设计器属性面板与代码侧可读可写属性（来源：组件类库）。
| 属性 | 类型 | 读写 | 说明 |
|---|---|---|---|
提示 |
文本 | 读写 | 鼠标悬停时的提示文字 |
鼠标指针 |
文本 | 读写 | 空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如 资源/press.cur） |
左边 |
小数 | 读写 | 相对窗体左边的位置（像素） |
顶边 |
小数 | 读写 | 相对窗体顶边的位置（像素） |
宽度 |
小数 | 读写 | 控件宽度（像素） |
高度 |
小数 | 读写 | 控件高度（像素） |
停靠 |
整数 | 读写 | 0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附 |
可见 |
逻辑 | 读写 | 真=显示，假=隐藏 |
启用 |
逻辑 | 读写 | 真=可用，假=禁用 |
句柄 |
长整数 | 只读 | 组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读 |
网格数据 |
文本 | 读写 | 列×行，如 8×20；填 0 表示不预设默认网格 |
工作表模式 |
逻辑 | 读写 | 真=列字母/行号；假=普通表格 |
选择模式 |
整数 | 读写 | 0=单元格 1=整行 2=整列 |
启用排序 |
逻辑 | 读写 | 真=表头点击排序 |
启用表头筛选 |
逻辑 | 读写 | 真=允许表头筛选（须 筛选类.绑定 且 设置筛选(列) 才显示 ▼） |
滚动条 |
整数 | 读写 | 1=不显示 2=纵向 3=横向 4=两者 |
交替换色 |
逻辑 | 读写 | 真=奇偶行交替背景 |
换色颜色 |
文本 | 读写 | 交替行背景色，如 #2A2A2E |
圆角 |
整数 | 读写 | 像素，0=直角 |
显示边框 |
逻辑 | 读写 | 真=显示边框 |
边框大小 |
整数 | 读写 | 像素 |
边框颜色 |
文本 | 读写 | 如 #RRGGBB |
背景色 |
文本 | 读写 | 如 #1E1E1E |
方法
调用必须带括号。行列索引从 0 起；区域文本为 Excel 风格（如 A1、A1:C3）。与「表格」控件 API 相近但不等价（本控件有工作表模式/冻结/列类型等）。下表由元数据生成（带类型签名）。
常用常量
| 项 | 取值 |
|---|---|
| 列类型 | 0文本 · 1复选框列 |
| 开启复选框模式 | 1仅首列 · 2每列 |
| 对齐方式 | 1左 · 2居中 · 3右 |
| 行/列数据返回类型 | 1文本数组 · 2JSON 文本 |
| 方法 | 签名 | 返回 | 说明 |
|---|---|---|---|
置行数 |
无 置行数(整数 行数) |
无 | 设置本控件逻辑行数；未写入数据的行视为空行，空行不单独占用单元格数据。 |
取行数 |
整数 取行数() |
整数 | 返回本控件逻辑行数。 |
置列数 |
无 置列数(整数 列数) |
无 | 设置本控件逻辑列数。 |
取列数 |
整数 取列数() |
整数 | 返回本控件逻辑列数。 |
滚动到单元格 |
无 滚动到单元格(整数 行, 整数 列) |
无 | 将指定单元格滚入可视区，并设为当前单元格。 |
置单元格 |
无 置单元格(整数 行, 整数 列, 文本 文本) |
无 | 设置指定单元格文本（行列从 0 起）；空单元格可不写入，按需赋值即可。 |
取单元格 |
文本 取单元格(整数 行, 整数 列) |
文本 | 返回指定单元格文本。 |
取单元格文本 |
文本 取单元格文本(文本 区域) |
文本 | 按 Excel 风格区域取首格文本（如 A1 / A1:C3）。 |
置单元格文本 |
整数 置单元格文本(文本 区域, [文本 数据]) |
整数 | 按 Excel 风格区域写入文本；省略数据则清空。返回写入格数。 |
置当前单元格 |
无 置当前单元格(整数 行, 整数 列) |
无 | 设置当前单元格并滚动到可视区。 |
取当前行 |
整数 取当前行() |
整数 | 返回当前单元格行索引（0 起）。 |
取当前列 |
整数 取当前列() |
整数 | 返回当前单元格列索引（0 起）。 |
取选中区域 |
文本 取选中区域() |
文本 | 返回当前选区的 A1 文本（如 A1、A1:C3；Ctrl 多选为 … |
置选中区域 |
逻辑 置选中区域(文本 区域) |
逻辑 | 按 A1 区域设置选区（如 A1:C3）。 |
选中全部 |
无 选中全部() |
无 | 选中全部单元格。 |
清空选中 |
无 清空选中() |
无 | 清空选区（保留当前单元格）。 |
置工作表模式 |
无 置工作表模式(逻辑 开启) |
无 | 开启后显示列字母 A/B/C… 与行号；关闭则仅网格。 |
取工作表模式 |
逻辑 取工作表模式() |
逻辑 | 返回是否处于工作表模式（列字母/行号）。 |
置交替换色 |
无 置交替换色(逻辑 开启) |
无 | 开启或关闭奇偶行交替背景色（工作表模式默认关闭，可代码开启）。 |
取交替换色 |
逻辑 取交替换色() |
逻辑 | 返回是否启用奇偶行交替背景色。 |
置表头筛选 |
无 置表头筛选(逻辑 开启) |
无 | 开启或关闭表头 Excel 式筛选按钮；须配合 筛选类.绑定 才显示… |
取表头筛选 |
逻辑 取表头筛选() |
逻辑 | 返回是否启用表头 Excel 式筛选按钮。 |
置列类型 |
无 置列类型(整数 列, 整数 类型) |
无 | 设置列类型：0=文本，1=复选框列（单击切换勾选）。 |
取列类型 |
整数 取列类型(整数 列) |
整数 | 返回列类型：0=文本，1=复选框。 |
置列宽 |
无 置列宽(整数 列, 整数 宽度) |
无 | 设置指定列宽度（像素）。 |
取列宽 |
整数 取列宽(整数 列) |
整数 | 返回指定列宽度（像素）。 |
置行高 |
无 置行高(整数 行, 整数 高度) |
无 | 设置指定行高度（像素）。 |
取行高 |
整数 取行高(整数 行) |
整数 | 返回指定行高度（像素）。 |
置冻结列数 |
无 置冻结列数(整数 列数) |
无 | 设置左侧冻结列数。 |
取冻结列数 |
整数 取冻结列数() |
整数 | 返回左侧冻结列数。 |
置冻结行数 |
无 置冻结行数(整数 行数) |
无 | 设置顶部冻结行数。 |
取冻结行数 |
整数 取冻结行数() |
整数 | 返回顶部冻结行数。 |
置显示行头 |
无 置显示行头(逻辑 开启) |
无 | 是否显示左侧行号列。 |
取显示行头 |
逻辑 取显示行头() |
逻辑 | 返回是否显示行号列。 |
置角单元格文本 |
无 置角单元格文本(文本 文本) |
无 | 设置左上角单元格文本。 |
取角单元格文本 |
文本 取角单元格文本() |
文本 | 返回左上角单元格文本。 |
置区域文字色 |
逻辑 置区域文字色(文本 区域, 文本 颜色) |
逻辑 | 设置区域文字颜色，如 “#FF0000”。 |
置区域背景色 |
逻辑 置区域背景色(文本 区域, 文本 颜色) |
逻辑 | 设置区域背景颜色。 |
置区域文字渐变色 |
逻辑 置区域文字渐变色(文本 区域, 文本 渐变) |
逻辑 | 设置区域文字渐变，格式 “#RRGGBB-#RRGGBB”。 |
置区域背景渐变色 |
逻辑 置区域背景渐变色(文本 区域, 文本 渐变) |
逻辑 | 设置区域背景渐变。 |
置区域字体 |
逻辑 置区域字体(文本 区域, 文本 字体名) |
逻辑 | 设置区域字体族。 |
置区域字号 |
逻辑 置区域字号(文本 区域, 整数 字号) |
逻辑 | 设置区域字号（像素）。 |
置区域自动换行 |
逻辑 置区域自动换行(文本 区域, 逻辑 开启) |
逻辑 | 设置区域是否自动换行。 |
置区域换行 |
逻辑 置区域换行(文本 区域, [逻辑 换行]) |
逻辑 | 设置区域是否自动换行；省略换行参数默认为真（同「置区域自动换行」）。 |
取区域换行 |
逻辑 取区域换行(文本 区域) |
逻辑 | 返回区域首格是否开启自动换行（如 A1:C3 取 A1）。 |
置换行 |
无 置换行(整数 行, 整数 列, [逻辑 换行]) |
无 | 设置指定单元格是否自动换行；省略换行参数默认为真。 |
取换行 |
逻辑 取换行(整数 行, 整数 列) |
逻辑 | 返回指定单元格是否开启自动换行。 |
清空区域格式 |
逻辑 清空区域格式(文本 区域) |
逻辑 | 清除区域单元格样式。 |
添加列 |
无 添加列(文本 名称, [整数 宽度=80], [文本 图片], [整数 对齐方式=1], [逻辑 开启排序]) |
无 | 在本控件末尾追加一列（普通模式显示列标题）。 |
置列头 |
无 置列头(整数 列, 文本 文本) |
无 | 设置普通模式下列标题（如 姓名、班级）；自动开启列头显示。工作表模式… |
取列头 |
文本 取列头(整数 列) |
文本 | 返回普通模式下列标题文本。 |
添加行 |
无 添加行(文本 名称, [整数 宽度=80], [文本 图片], [整数 对齐方式=1]) |
无 | 在本控件末尾追加一行并设置行标题（普通模式显示行头）。 |
取标题 |
文本 取标题(整数 行, 整数 列) |
文本 | 返回指定单元格文本（同「取单元格」）。 |
置标题 |
无 置标题(整数 行, 整数 列, 文本 文本) |
无 | 设置指定单元格文本（同「置单元格」）。 |
取选中行 |
整数 取选中行() |
整数 | 返回当前单元格行索引（0 起，同「取当前行」）。 |
取选中列 |
整数 取选中列() |
整数 | 返回当前单元格列索引（0 起，同「取当前列」）。 |
开启复选框 |
无 开启复选框([整数 模式=1]) |
无 | 开启单元格复选框。模式：1=仅首列，2=每列；默认 1。 |
插入行 |
无 插入行(整数 行, [整数 数量=1]) |
无 | 在指定位置插入空行；大于行数则追加到末尾。 |
删除行 |
无 删除行(整数 行, [整数 数量=1]) |
无 | 从指定行起删除若干行。 |
插入列 |
无 插入列(整数 列, [整数 数量=1]) |
无 | 在指定位置插入空列；大于列数则追加到末尾。 |
删除列 |
无 删除列(整数 列, [整数 数量=1]) |
无 | 从指定列起删除若干列（至少保留 1 列）。 |
清空 |
无 清空() |
无 | 清空全部单元格文本，保留行列数与表头/格式段。 |
排序 |
无 排序(整数 列, [逻辑 升序=真]) |
无 | 按指定列文本排序整表行。 |
取单元格显示 |
文本 取单元格显示(整数 行, 整数 列) |
文本 | 返回单元格显示文本；公式格返回求值结果，编辑态仍显示公式原文。 |
加入控件 |
文本 加入控件(整数 行, 整数 列, 文本 组件名, [整数 宽度=0], [整数 高度=0]) |
文本 | 在指定单元格按类型名创建并嵌入控件（如 按钮、下拉框）；可与单元格文… |
取行数据 |
文本数组 取行数据(整数 行, [整数 类型=1]) |
文本数组 | 返回指定行各列文本。类型 1=文本数组，2=JSON 数组文本。 |
取当前行数据 |
文本数组 取当前行数据([整数 返回值类型=1]) |
文本数组 | 返回当前行各列单元格文本。默认文本数组；返回值类型=2 时返回 JS… |
置行数据 |
无 置行数据(整数 行, 文本数组 数据) |
无 | 用文本数组一次写入整行各列；数组短于列数时其余列清空，长于列数时截断。 |
复制选区 |
逻辑 复制选区() |
逻辑 | 把当前选区复制到系统剪贴板（制表符分隔）。成功返回真。 |
剪切选区 |
逻辑 剪切选区() |
逻辑 | 复制选区到剪贴板后清空选区文本。成功返回真。 |
粘贴到选区 |
逻辑 粘贴到选区([文本 数据]) |
逻辑 | 从当前选区左上角开始粘贴。省略数据则使用系统剪贴板；传入文本则按制表… |
置区域文本 |
逻辑 置区域文本(文本 区域, 文本 数据) |
逻辑 | 把制表符/换行分隔的多值文本填入 A1 矩形区域（从区域左上角起，不… |
取选中单元格 |
长整数数组 取选中单元格() |
长整数数组 | 返回多选单元格打包值数组：每项为 (行<<32) |
查找单元格 |
文本 查找单元格(文本 关键词, [整数 起始行=0], [整数 起始列=0], [逻辑 区分大小写=假]) |
文本 | 从指定位置起查找包含关键词的单元格；命中则返回该格的 A1 坐标文本… |
查找下一个 |
文本 查找下一个() |
文本 | 继续上次「查找单元格」的搜索，返回下一处命中格的 A1 坐标文本；无… |
取单元格控件 |
文本 取单元格控件(整数 行, 整数 列) |
文本 | 返回该单元格已嵌入控件的名称；无嵌入返回空文本。 |
移除控件 |
逻辑 移除控件(整数 行, 整数 列) |
逻辑 | 移除指定单元格的嵌入控件。成功返回真。 |
取列数据 |
文本数组 取列数据(整数 列, [整数 类型=1]) |
文本数组 | 返回指定列各行文本。类型 1=文本数组，2=JSON 数组文本。 |
置列数据 |
无 置列数据(整数 列, 文本数组 数据) |
无 | 用文本数组一次写入整列各行；数组短于行数时其余行清空。 |
取选区文本 |
文本 取选区文本() |
文本 | 返回当前选区内容的制表符/换行文本（不经系统剪贴板）。 |
清空行 |
无 清空行(整数 行) |
无 | 清空指定行全部单元格文本，不删行。 |
清空列 |
无 清空列(整数 列) |
无 | 清空指定列全部单元格文本，不删列。 |
置行头 |
无 置行头(整数 行, 文本 文本) |
无 | 设置普通模式下的行头文本（工作表模式行号不受影响）。 |
取行头 |
文本 取行头(整数 行) |
文本 | 返回行头文本。 |
取区域显示 |
文本 取区域显示(文本 区域) |
文本 | 返回区域内各格的显示文本（公式格为求值结果），以制表符/换行拼接。 |
是否编辑中 |
逻辑 是否编辑中() |
逻辑 | 返回当前是否处于单元格就地编辑。 |
替换 |
整数 替换(文本 关键词, 文本 替换为, [文本 区域], [逻辑 区分大小写=假]) |
整数 | 在指定区域（省略则整表）把单元格文本中的关键词全部替换。返回替换次数。 |
移动 |
无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度]) |
无 | 可选同时改宽高 |
置焦点 |
无 置焦点() |
无 | |
刷新 |
无 刷新() |
无 | |
显示 / 隐藏 |
无 显示() / 无 隐藏() |
无 | 等同 可见 = 真/假 |
置字体 |
逻辑 置字体(字体类 字体) |
逻辑 | 见 painter.md |
数据表格1.置列数(3)
数据表格1.置行数(10)
数据表格1.置单元格(0, 0, "A1")
事件
在代码中写 函数 控件名.事件名(...) 处理。单元格类事件常见形参：整数 行, 整数 列, 文本 区域；选区被改变(文本 当前文本)（值为 A1 区域）。
| 事件 | 参数 | 说明 |
|---|---|---|
单击 |
整数 X, 整数 Y | 鼠标左键单击控件。 |
双击 |
整数 X, 整数 Y | 鼠标左键双击控件。 |
右键单击 |
整数 X, 整数 Y | 鼠标右键单击控件。 |
鼠标按下 |
整数 X, 整数 Y, 逻辑 按下 | 鼠标键在控件上按下。按下=真表示当前仍按住。 |
鼠标抬起 |
整数 X, 整数 Y, 逻辑 按下 | 鼠标键在控件上放开。 |
鼠标移动 |
整数 X, 整数 Y, 逻辑 按下 | 鼠标在控件上移动。按下表示左键是否按住。 |
鼠标进入 |
整数 X, 整数 Y | 鼠标指针进入控件区域。 |
鼠标离开 |
整数 X, 整数 Y | 鼠标指针离开控件区域。 |
鼠标左键单击 |
整数 X, 整数 Y | 鼠标左键单击（与「单击」同时触发）。 |
鼠标左键双击 |
整数 X, 整数 Y | 鼠标左键双击（与「双击」同时触发）。 |
鼠标中间单击 |
整数 X, 整数 Y | 鼠标中键单击控件。 |
鼠标齿轮滚动 |
整数 X, 整数 Y, 逻辑 向上 | 在控件上滚动鼠标滚轮。向上=真表示向上滚。 |
鼠标右键单击 |
整数 X, 整数 Y | 鼠标右键单击（与「右键单击」同时触发）。 |
鼠标右键双击 |
整数 X, 整数 Y | 鼠标右键双击控件。 |
当前单元格改变 |
整数 行, 整数 列, 文本 区域 | 当前单元格变化时触发。第三参为 A1 坐标（如 A1）。 |
单元格被单击 |
整数 行, 整数 列, 文本 区域 | 用户单击某一单元格时触发。 |
单元格被双击 |
整数 行, 整数 列, 文本 区域 | 用户双击某一单元格时触发。 |
单元格被激活 |
整数 行, 整数 列, 文本 区域 | 回车激活当前单元格时触发。 |
单元格改变 |
整数 行, 整数 列, 文本 区域 | 单元格文本被编辑提交后触发。 |
单元格被右键单击 |
整数 行, 整数 列, 文本 区域 | 鼠标右键单击单元格时触发。 |
选区被改变 |
文本 当前文本 | 选区变化时触发。参数值为 A1 区域（如 A1:C3）。 |
开始编辑 |
整数 行, 整数 列, 文本 区域 | 进入单元格就地编辑时触发。 |
结束编辑 |
整数 行, 整数 列, 文本 区域 | 提交或取消单元格编辑时触发。 |
函数 数据表格1.单元格被单击 (整数 行, 整数 列, 文本 区域) {
输出(区域)
}
YSS 样式
以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。
布局与子选择器
电子表格风格网格：A1 区域、工作表模式（列字母/行号）、冻结窗格、就地编辑、剪贴板、公式显示、区域格式、行列插入删除、表头筛选与嵌入控件。
和「表格」不是同一个控件。 本页只讲设计器里的 数据表格（
datagrid/数据表格1）。导入文件/虚拟加载在 表格。工作表模式（列字母/行号）只在本控件。
完整方法见 IDE「支持库 → 数据表格类」。表头筛选的高级用法可配合支持库中的 筛选类 / 筛选UI类。
属性说明（逐键）
YSS 主要管表格外壳（底板、边框、默认前景字色与字体）。单元格/区域配色、斑马纹、选中色等请用代码 API（如 置区域背景色、置交替换色）或设计器属性；datagrid:cell 等单元格级选择器能力有限，不要指望用 YSS 精细样式化每一格。
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
background-color / background |
外壳/默认底板 | 颜色，如 #1A1A1A |
加载前/空隙底色 |
border-color |
外壳边框色 | 颜色 | |
border-width |
边框宽 | 像素 | |
border-radius |
圆角 | 像素 | 只圆角外壳，不裁剪格子 HWND 内容 |
show-border |
是否画边框 | true/false |
|
color |
默认文字色 | 颜色 | 单元格未单独设色时回退 |
font-size |
默认字号 | 像素 | |
font-family |
默认字体族 | 字符串 | |
font-bold / font-italic |
默认粗/斜 | true/false |
圆角 / 显示边框 / 边框大小 / 边框颜色 / 背景色亦与设计器外观属性对齐，可由 YSS 写入。
XML / 设计器 ↔ YSS / 代码（分工）
| 设计器 / XML | YSS | 代码 API（格子级） |
|---|---|---|
| 背景色 | background-color |
—（外壳） |
| 边框颜色 / 大小 / 显示边框 / 圆角 | border-* / show-border / border-radius |
— |
| 交替换色 / 换色颜色 | 不要用 YSS 键硬写 | 置交替换色 / 属性「换色颜色」 |
| 某格/区域底色、字色、渐变 | 无可靠单元格选择器 | 置区域背景色 / 置区域文字色 / 置区域*渐变色 |
| 字体（整表默认） | font-size / font-family / … |
置区域字体（区域覆盖） |
伪状态： 数据表格外壳一般不依赖 :hover 整控件铺底；交互高亮走选中/编辑态与区域 API。
外壳 + 区域配色配合示例（YSS 管壳，代码管格）：
函数 主窗口.创建完毕() {
报表.置交替换色(真)
报表.置区域背景色("A1:A1", "#1E3A5F")
报表.置区域文字色("A1:A1", "#E0E0E0")
}
使用示例
深色外壳：
datagrid {
background-color: #1A1A1A;
border-color: #464646;
border-width: 1;
show-border: true;
color: #E0E0E0;
font-size: 13;
}
命名实例：
datagrid#报表 {
background-color: #101010;
border-radius: 4;
}
完整示例
datagrid {
background-color: #1A1A1A;
border-color: #464646;
border-width: 1;
border-radius: 0;
show-border: true;
color: #E0E0E0;
font-size: 13;
font-family: "Microsoft YaHei UI";
}
datagrid#报表 {
background-color: #101010;
border-color: #3C3C3C;
border-radius: 4;
show-border: true;
}