TreeSheets脚本API参考指南：掌握自动化操作的核心函数

项目概述

TreeSheets是一款创新的分层电子表格工具，它将电子表格、思维导图和文本编辑器的功能融为一体。通过内置的脚本系统，用户可以自动化执行各种操作，大幅提升工作效率。本文将全面介绍TreeSheets的脚本API，帮助开发者充分利用其自动化能力。

核心功能API详解

单元格导航与控制

TreeSheets的脚本系统围绕单元格操作展开，提供了完整的导航功能：

• 根节点操作：ts.goto_root()将当前单元格定位到文档根节点，是脚本执行的起点
• 视图控制：ts.goto_view()同步脚本与用户当前查看的单元格位置
• 选择集处理：ts.has_selection()和ts.goto_selection()配合使用可检测并跳转到用户选择
• 层级遍历：ts.goto_parent()和ts.goto_child(n)实现文档树结构的上下导航

网格与布局管理

TreeSheets的网格系统可通过脚本动态调整：

# 创建3x2的网格
ts.create_grid(3, 2)

# 在第二列前插入新列
ts.insert_column(1)

# 删除(1,1)位置开始的2x1区域
ts.delete((1,1), (2,1))

内容与样式操作

单元格内容和样式可通过API全面控制：

• 文本内容：ts.get_text()获取文本，ts.set_text()设置文本
• 样式设置：支持背景色(set_background_color)、文字颜色(set_text_color)等
• 文字样式：ts.set_style_bits()可设置粗体(1)、斜体(2)、等宽(4)等组合样式

实用功能API

文档管理

# 获取当前文档路径
current_file = ts.get_filename()

# 加载新文档
if ts.load_document("newfile.ts"):
    print("加载成功")

用户交互

# 获取用户选择的文件
user_file = ts.get_filename_from_user(False)  # False表示打开对话框

# 设置状态栏消息
ts.set_status_message("处理完成！")

内置通用函数

数据结构操作

TreeSheets脚本内置了丰富的数据处理函数：

• 数组操作：push/pop实现栈操作，insert/remove处理任意位置元素
• 搜索功能：binary_search系列函数支持各种数据类型的二分查找
• 字符串处理：substring截取子串，find_string查找内容

调试输出

# 设置打印格式
set_print_indent(4)  # 使用4空格缩进
set_print_decimals(2)  # 浮点数保留2位小数

# 调试输出
print("当前单元格内容：" + ts.get_text())

最佳实践建议

1. 导航安全：在执行操作前，先用ts.has_parent()等函数检查当前位置是否有效
2. 错误处理：关键操作如文件加载应检查返回值
3. 性能优化：对大规模操作使用vector_capacity预分配内存
4. 用户体验：通过set_status_message向用户反馈脚本执行进度

总结

TreeSheets的脚本系统提供了从基础内容操作到高级布局管理的完整API集合。通过熟练掌握这些函数，开发者可以实现：

• 自动化文档处理流程
• 批量内容更新与转换
• 动态生成复杂结构文档
• 与其他系统集成

本文涵盖的API只是TreeSheets自动化能力的开始，结合这些基础函数可以构建出强大的文档处理解决方案。