YStudio Y++

表格(tablewidget)

Y++ / YStudio 开发文档 · 一点滴

选择器: tablewidget · 设计器组件: 表格 · 按名称: tablewidget#名称 或 #名称

硬约束与叠画

  1. 控件名来自窗口 XML「名称」;属性赋值无括号(如 标题 = "确定"),方法调用必须带括号(如 刷新())。
  2. 事件写 函数 控件名.事件名(参数…),形参类型以本页事件表为准。
  3. 任意控件客户区叠画用支持库 绘制类:绘制类 g → g.绑组件(本控件名)(组件名无引号)。画布场景编辑见 画布控件。
  4. 字体对象见绘制文档中的字体类;置字体(字体类) 将字体应用到本控件。
  5. 不要虚构未列出的方法;YSS 键见下文与 YSS.md。

属性

设计器属性面板与代码侧可读可写属性(来源:组件类库)。

属性 类型 读写 说明
提示 文本 读写 鼠标悬停时的提示文字
鼠标指针 文本 读写 空=默认;可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设,或.cur/.ani 路径(如 资源/press.cur)
左边 小数 读写 相对窗体左边的位置(像素)
顶边 小数 读写 相对窗体顶边的位置(像素)
宽度 小数 读写 控件宽度(像素)
高度 小数 读写 控件高度(像素)
停靠 整数 读写 0无 1上 2下 3左 4右 5填充;菜单/工具/状态栏仍用专用吸附
可见 逻辑 读写 真=显示,假=隐藏
启用 逻辑 读写 真=可用,假=禁用
句柄 长整数 只读 组件逻辑句柄(1 起,供动画类等绑定;非 HWND);只读
选择模式 整数 读写 0=单元格 1=整行 2=整列
列宽 整数 读写 默认列宽(像素)
行高 整数 读写 默认行高(像素)
表头高度 整数 读写 表头高度(像素)
滚动条 整数 读写 1=无 2=纵向 3=横向 4=两者
表格数据 文本 读写 表格行列、表头与单元格的整体数据
交替行色 文本 读写 无/预设名/自定义(配合交替行色颜色)
交替行色颜色 文本 读写 奇数行底色,如 #2A2A2E
表项对齐 文本 读写 左对齐/居中/右对齐
表头对齐 整数 读写 0=左 1=中 2=右
表头图标位置 文本 读写 左/右
可编辑 逻辑 读写 真=双击/F2 可编辑单元格
编辑背景 整数 读写 0=无 1=透明 2=自定
编辑背景色 文本 读写 编辑背景=自定时的颜色
显示勾选 整数 读写 0=不显示 1=所有单元格 2=仅首列
选中项 整数 读写 当前选中行索引(0 起)
表头排序 逻辑 读写 真=点击表头按该列排序
自动折行 逻辑 读写 真=单元格文字自动换行;假=单行显示,超出裁剪并省略(默认)
选中背景色 文本 读写 单元格选中底色
选中文字色 文本 读写 单元格选中文字色
圆角 整数 读写 像素,0=直角
显示边框 逻辑 读写 真=显示边框
边框大小 整数 读写 像素
边框颜色 文本 读写 如 #RRGGBB
文字色 文本 读写 如 #RRGGBB
背景色 文本 读写 如 #1E1E1E

方法

调用必须带括号。行列从 0 起;区域为 A1 风格。与 数据表格 不同:本控件侧重表头图标、单元格显示模板、行勾选/移动行等。下表由元数据生成(带类型签名)。

常用常量

项 取值
对齐方式 1左 · 2居中 · 3右
单元格/列显示 0文本 · 1用户(圆头像+双行) · 2徽章
行数据返回类型 1文本数组 · 2JSON 文本
选择模式(属性) 0单元格 · 1整行 · 2整列
方法 签名 返回 说明
置行数 无 置行数(整数 行数) 无 设置本控件逻辑行数;未写入数据的行视为空行,空行不单独占用单元格数据。
取行数 整数 取行数() 整数 返回本控件数据行数。
置列数 无 置列数(整数 列数) 无 设置本控件列数。
取列数 整数 取列数() 整数 返回本控件列数。
置单元格 无 置单元格(整数 行, 整数 列, 文本 文本) 无 设置指定单元格文本(行列从 0 起)。
取单元格 文本 取单元格(整数 行, 整数 列) 文本 返回指定单元格文本。
取单元格文本 文本 取单元格文本(文本 区域) 文本 按 A1 区域取单元格文本(如 A1;多区域取首格)。
置单元格文本 逻辑 置单元格文本(文本 区域, [文本 数据]) 逻辑 按 A1 区域写入文本;省略数据则清空。返回是否成功。
取单元格文本Ex 文本 取单元格文本Ex(整数 行, 整数 列) 文本 按 0 基行列取单元格文本(同「取单元格」)。
置单元格文本Ex 无 置单元格文本Ex(整数 行, 整数 列, 文本 文本) 无 按 0 基行列写单元格文本(同「置单元格」)。
置区域文字色 逻辑 置区域文字色(文本 区域, [文本 颜色]) 逻辑 设置区域文字色;省略颜色则清除文字色。
置区域背景色 逻辑 置区域背景色(文本 区域, [文本 颜色]) 逻辑 设置区域背景色;省略颜色则清除背景色。
置区域文字渐变色 逻辑 置区域文字渐变色(文本 区域, 文本 渐变) 逻辑 设置区域文字渐变,格式如 “#FF8888-#FF0000”。
置区域背景渐变色 逻辑 置区域背景渐变色(文本 区域, 文本 渐变) 逻辑 设置区域背景渐变,格式如 “#112233-#445566”。
清除格式 逻辑 清除格式(文本 区域) 逻辑 清除指定区域的单元格格式。
置区域字体 逻辑 置区域字体(文本 区域, 文本 字体) 逻辑 设置区域字体名。
置区域字号 逻辑 置区域字号(文本 区域, 整数 字号) 逻辑 设置区域字号(像素)。
置区域换行 逻辑 置区域换行(文本 区域, [逻辑 换行]) 逻辑 设置区域是否换行;省略换行参数默认为真。
置表头 无 置表头(整数 列, 文本 文本) 无 设置已有列的水平表头标题。新建列请优先用「添加列」。
添加列 无 添加列(文本 名称, [整数 列宽=80], [文本 图标], [整数 对齐方式=1]) 无 在表格末尾追加一列并设置表头。
添加行 无 添加行(文本 名称, [整数 行高=28], [文本 图标], [整数 对齐方式=1]) 无 在表格末尾追加一行;名称/图标写入首列单元格(表格无独立行头)。
取表头 文本 取表头(整数 列) 文本 返回水平表头指定列的标题。
置表头图标 无 置表头图标(整数 列, 文本 图标, [整数 大小=0], [整数 位置=0], [整数 间距=-2]) 无 设置表头图标。图标可为本地路径、资源或 http(s) URL。大小…
置表头图标字节集 无 置表头图标字节集(整数 列, 字节集 数据, [整数 大小=0], [整数 位置=0], [整数 间距=-2]) 无 用 HTTP 等返回的图片字节集设置表头图标(参数含义同「置表头图标…
取表头图标 文本 取表头图标(整数 列) 文本 返回水平表头指定列的图标路径。
插入行 无 插入行(整数 行) 无 在指定位置插入空行。
删除行 无 删除行(整数 行) 无 删除指定数据行。
插入列 无 插入列(整数 列) 无 在指定位置插入空列。
删除列 无 删除列([整数数组 列]) 无 删除列:省略参数或空数组=删除全部列;整数=单列;整数数组=批量删除。
置当前单元格 无 置当前单元格(整数 行, 整数 列) 无 设置当前单元格。
取当前行 整数 取当前行() 整数 返回当前单元格所在行。
取当前列 整数 取当前列() 整数 返回当前单元格所在列。
置列宽 无 置列宽(整数 列, 整数 宽度) 无 设置指定列宽度(像素);写入 @TABLE 的 @W 段,各列可独立。
取列宽 整数 取列宽(整数 列) 整数 返回指定列宽度(像素);无独立宽度时回退默认列宽。
清空 无 清空() 无 清空全部单元格文本,保留行列数与表头。
排序 无 排序(整数 列, [逻辑 升序=真]) 无 按指定列文本排序整表行。升序可显式指定;省略时默认升序。表头点击仍为…
置单元格图标 无 置单元格图标(整数 行, 整数 列, 文本 图标, [整数 大小=0], [整数 位置=0], [整数 间距=-2]) 无 设置单元格图标。图标可为本地路径、资源或 http(s) URL。大…
置单元格图标字节集 无 置单元格图标字节集(整数 行, 整数 列, 字节集 数据, [整数 大小=0], [整数 位置=0], [整数 间距=-2]) 无 用图片字节集设置单元格图标(适合 HTTP 类带请求头下载后的响应体…
开始更新 无 开始更新() 无 可选:批量写入前调用以减少中间刷新(可嵌套;与「结束更新」成对)。「…
结束更新 无 结束更新() 无 结束「开始更新」批量写入并刷新界面。
导入行数据 无 导入行数据([整数 起始行=0], 文本 数据[][]) 无 极速批量写入多行文本(二维文本数组)。内部自动挂起刷新并扩展行数,不…
导入分隔文本 无 导入分隔文本(文本 文本, [文本 分隔符], [整数 起始行=0]) 无 把整段文本按行+分隔符拆成单元格并极速写入(走内存虚表,不经 32K…
导入文件 无 导入文件(文本 路径, [文本 分隔符], [整数 起始行=0]) 无 从 UTF-8 文本文件极速导入(内存虚表;百万行约 1 秒级,导入…
虚拟加载 无 虚拟加载(文本 数据, [文本 列分隔符 = "----"], [整数 最大行数 = 0], [文本 编码 = "UTF-8"], [逻辑 清空原数据 = 真], [文本 记录分隔符 = ""], [整数 开始列 = 0]) 无 按页面缓存方式虚拟加载大文本数据,适合大文件。只建行偏移、按可见页解…
取单元格图标 文本 取单元格图标(整数 行, 整数 列) 文本 返回单元格图标路径。
置单元格显示 无 置单元格显示(整数 行, 整数 列, 整数 类型) 无 单元格显示模板:0=文本,1=用户(圆头像+双行),2=徽章。用户格…
取单元格显示 整数 取单元格显示(整数 行, 整数 列) 整数 返回单元格显示类型(含列默认)。
置列显示 无 置列显示(整数 列, 整数 类型) 无 设置整列默认显示模板(0文本/1用户/2徽章);单元格级「置单元格显…
取列显示 整数 取列显示(整数 列) 整数 返回列默认显示类型。
置单元格勾选 无 置单元格勾选(整数 行, 整数 列, 逻辑 勾选) 无 设置单元格勾选状态(需属性「显示勾选」为真)。
取单元格勾选 逻辑 取单元格勾选(整数 行, 整数 列) 逻辑 返回单元格是否勾选。
取标题 文本 取标题(整数 行, 整数 列) 文本 返回指定单元格的文本(不含嵌入控件名与图片路径)。
置标题 无 置标题(整数 行, 整数 列, [文本 数据], [字节集 图片数据]) 无 设置单元格文本和/或图片;参数可省略,可只设文字、只设图片或两者同时…
加入控件 文本 加入控件(整数 行, 整数 列, 文本 组件名, [整数 宽度=0], [整数 高度=0]) 文本 在指定单元格按类型名创建并嵌入控件(如 按钮、下拉框);可与单元格文…
取勾选 逻辑 取勾选(整数 行) 逻辑 返回指定行的勾选状态(读写首列;需属性「显示勾选」)。
置勾选 无 置勾选(整数 行, 逻辑 勾选) 无 设置指定行的勾选状态(写入首列;需属性「显示勾选」)。
取当前行数据 文本数组 取当前行数据([整数 返回值类型=1]) 文本数组 返回当前行各列单元格文本。默认文本数组;返回值类型=2 时返回 JS…
取行数据 文本数组 取行数据(整数 行, [整数 类型=1]) 文本数组 返回指定行各列文本。类型 1=文本数组,2=JSON 数组文本。
取选中单元格 长整数数组 取选中单元格() 长整数数组 返回多选单元格打包值数组:每项为 (行<<32)
取选中区域 文本 取选中区域() 文本 返回当前选中区域文本:单格 A1、连续块 A1:C3;Ctrl 多选…
置选中区域 逻辑 置选中区域(文本 区域) 逻辑 按 A1 区域设置选中(如 A1 / A1:C3 / A1,B2)。…
清空选中 无 清空选中() 无 清除表格全部选中状态。
选中全部 无 选中全部() 无 选中表格全部显示单元格。
置行高 无 置行高(整数 行, 整数 高度) 无 设置指定行高度(像素);超出当前行数时自动扩展。
取行高 整数 取行高(整数 行) 整数 返回指定行高度(像素);无独立高度时回退默认行高。
滚动到单元格 无 滚动到单元格(整数 行, 整数 列) 无 将指定单元格滚入可视区,并设为当前单元格。
置行数据 无 置行数据(整数 行, 文本数组 数据) 无 用文本数组一次写入整行各列;数组短于列数时其余列清空,长于列数时截断。
查找单元格 文本 查找单元格(文本 关键词, [整数 起始行=0], [整数 起始列=0], [逻辑 区分大小写=假]) 文本 从指定位置起查找包含关键词的单元格;命中则返回该格的 A1 坐标文本…
查找下一个 文本 查找下一个() 文本 继续上次「查找单元格」的搜索,返回下一处命中格的 A1 坐标文本;无…
取单元格控件 文本 取单元格控件(整数 行, 整数 列) 文本 返回该单元格已嵌入控件的名称;无嵌入返回空文本。
移除控件 逻辑 移除控件(整数 行, 整数 列) 逻辑 移除指定单元格的嵌入控件。成功返回真。
取列数据 文本数组 取列数据(整数 列, [整数 类型=1]) 文本数组 返回指定列各行文本。类型 1=文本数组,2=JSON 数组文本。
置列数据 无 置列数据(整数 列, 文本数组 数据) 无 用文本数组一次写入整列各行;数组短于行数时其余行清空。
取选区文本 文本 取选区文本() 文本 返回当前选区内容的制表符/换行文本(不经系统剪贴板)。无选区时返回当…
清空行 无 清空行(整数 行) 无 清空指定行全部单元格文本,不删行。
清空列 无 清空列(整数 列) 无 清空指定列全部单元格文本,不删列。
取勾选行 长整数数组 取勾选行() 长整数数组 返回已勾选行的行号数组(0 起;读写首列勾选)。
置勾选行 无 置勾选行(长整数数组 行号数组, 逻辑 勾选) 无 批量设置多行勾选状态。
移动行 无 移动行(整数 源行, 整数 目标行) 无 把源行整行数据移动到目标行位置(中间行顺移),不改变行数。
替换 整数 替换(文本 关键词, 文本 替换为, [文本 区域], [逻辑 区分大小写=假]) 整数 在指定区域(省略则整表)把单元格文本中的关键词全部替换。返回替换次数。
移动 无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度]) 无 可选同时改宽高
置焦点 无 置焦点() 无
刷新 无 刷新() 无
显示 / 隐藏 无 显示() / 无 隐藏() 无 等同 可见 = 真/假
置字体 逻辑 置字体(字体类 字体) 逻辑 见 painter.md
表格1.添加列("姓名", 120)
表格1.置单元格(0, 0, "张三")

事件

在代码中写 函数 控件名.事件名(...) 处理。单元格事件常见:整数 行, 整数 列, 文本 区域;选区被改变(文本 当前文本)(值为 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.单元格被单击 (整数 行, 整数 列, 文本 区域) {
    输出(区域 + " = " + 表格1.取单元格(行, 列))
}

YSS 样式

以下为样式表(.yss)键与示例;写样式前请先读窗体 XML 取控件 名称 与 typeId,见 window-xml.md。

布局与子选择器

通用报表/列表表格:自定义表头、单元格读写、勾选、排序、键盘导航、区域格式、嵌入子控件。适合做名单、订单明细、配置表等「一行一条记录」界面。

和「数据表格」不是同一个控件。 本页只讲设计器里的 表格(tablewidget / 表格1)。列字母、行号、冻结、公式、置工作表模式 在 数据表格。导入文件 也只在本页。

完整方法也可在 IDE「支持库 → 表格类」面板中查看参数与示例。


属性说明(逐键)

YSS 管表格外壳、表头、网格模式、行悬停、内边距,以及列级单元格显示模板(user / badge)。区域配色仍用 置区域背景色 等 API。

子选择器: tablewidget:header(表头底/字色)

XML / 设计器 ↔ YSS

设计器 / XML 常见项 YSS 键或写法
背景色 / 边框 / 圆角 / 显示边框 background-color、border-*、show-border
文字色 / 字体 color、font-size、font-family…
表头底/字(若面板有) header-background-color / header-color,或 tablewidget#名:header { … }
交替换色 alternating-row-colors: true(亦可用代码)
选中行 / 悬停行 item-selected-background、item-hover-background
列显示模板 column-display: user, text, badge, …
某区域底色 代码 置区域背景色(不要指望单元格级 YSS)

伪状态: 行悬停用 item-hover-background(不是整控件 :hover 铺底)。表头用子选择器 :header,不是伪态名「表头」。

外壳与字体

属性 作用 取值 / 范围 说明与注意
background-color / background 外壳/默认底板 颜色
border-color / border-width / border-radius / show-border 外壳边框 同按钮
color 默认文字色 颜色
font-size / font-family / font-bold / font-italic 默认字体 同标签

表头与网格

属性 作用 取值 / 范围 说明与注意
header-background-color 表头底色 颜色 亦可 tablewidget:header { background-color }
header-color 表头字色 颜色 亦可 :header { color }
header-padding-x 表头水平内边距 像素
grid-color / gridline-color 网格线色 颜色
grid-style 网格模式 both(默认)· horizontal · vertical · none

单元格与行态

属性 作用 取值 / 范围 说明与注意
cell-padding 单元格内边距 12 或 12 8(x y) 亦有 cell-padding-x / cell-padding-y
item-selected-background / item-selected-color 选中行底/字 颜色
item-hover-background 行悬停底 颜色 真正绘制整行悬停
alternating-row-colors 斑马纹 true/false

列显示模板

属性 作用 取值 / 范围 说明与注意
column-display 按列模板列表 如 user, text, badge, text, text 逗号分隔
column-N-display 单列模板 如 column-0-display: user N 从 0

模板约定:

  • text(默认):普通文本
  • user:姓名 + 换行/| + 副标题;首字圆头像,色由姓名哈希;图标列 #RRGGBB 可指定头像色
  • badge:tone|文案,tone=success/warning/muted/danger 或 #RRGGBB;亦可由文案推断
  • API:置列显示(列, 类型) / 置单元格显示(行, 列, 类型),类型 0文本 / 1用户 / 2徽章
tablewidget#名单:header {
    background-color: #FFFFFF;
    color: #6B7280;
}

使用示例

浅色列表外壳:

tablewidget#订单表 {
    background-color: #FFFFFF;
    color: #111827;
    border-color: #E5E7EB;
    border-radius: 10;
    show-border: true;
    grid-style: horizontal;
    grid-color: #F3F4F6;
    cell-padding: 12 8;
    column-display: user, text, badge, text, text;
    item-hover-background: #F9FAFB;
    item-selected-background: #EFF6FF;
}
tablewidget#订单表:header {
    background-color: #FFFFFF;
    color: #6B7280;
}

深色外壳:

tablewidget {
    background-color: #1E1E1E;
    border-color: #464646;
    border-width: 1;
    show-border: true;
    color: #E0E0E0;
    font-size: 13;
    header-background-color: #252526;
    header-color: #CCCCCC;
    grid-color: #3C3C3C;
}

命名实例:

tablewidget#名单 {
    background-color: #101010;
    border-radius: 4;
    header-background-color: #161616;
    grid-color: #2A2A2A;
}

完整示例

tablewidget {
    background-color: #1E1E1E;
    border-color: #464646;
    border-width: 1;
    border-radius: 0;
    show-border: true;
    color: #E0E0E0;
    font-size: 13;
    font-family: "Microsoft YaHei UI";
    header-background-color: #252526;
    header-color: #CCCCCC;
    grid-color: #3C3C3C;
}

tablewidget#名单 {
    background-color: #101010;
    border-color: #3C3C3C;
    border-radius: 4;
    show-border: true;
}

tablewidget#名单:header {
    background-color: #161616;
    color: #F4F4F5;
}