Programmatic Control（中文）

以编程方式创建文档¶

您已经学习了如何通过软件的菜单和工具栏创建和使用 CCH Tagetik Supply Chain Planning Studio 文档。本章介绍如何使用 DScript™ 以编程方式创建和修改文档。

以编程方式创建文档而不是通过标准菜单和工具栏有许多原因。例如，您可能需要：

在数据处理例程结束时动态创建和/或操作图表；
编写函数以根据节点值为树的节点着色或设置节点属性；
创建具有标准菜单无法提供的属性组合的自定义图表或表格；或
创建您自己的加载项，自动创建/修改 Studio 文档。

本章介绍如何以编程方式创建和操作以下 CCH Tagetik Supply Chain Planning Studio 文档：

工作表（Tree Sheet、Text Sheet、Data Table、Report、Diagram）；
图表（Presentation Table、Graph (2-D)、Surface Plot (3-D)）；以及
节点

创建和使用文档

以下代码片段将创建一个名为 MyTable 的新 Presentation Table，并指定其数据、垂直图例和水平图例：

var x=inserttable("MyTable");
document[x].data="[[1,2,3],[4,5,6]]";
document[x].vlegend="['Row 1','Row 2','Row 3']";
document[x].hlegend="['Col 1','Col 2']";

上面示例中的 inserttable 函数创建一个新的 Presentation Table，并返回新工作表的名称（示例中为 "MyTable"）。

以下是用于创建其他 CCH Tagetik Supply Chain Planning Studio 文档的函数：

函数	创建新
insertdatasheet	Data Table
insertdiagramsheet	Diagram
insertgraph	Graph
insertgraph3	Surface Plot
insertreportsheet	Report
inserttable	Presentation Table
inserttextsheet	Text Sheet
inserttreesheet	Tree Sheet

您可以通过以下任一方式引用现有和之前创建的文档：

var x="sheetname";
document[x].property=value;

或

document.sheetname.property=value;

节点可以像工作表一样以编程方式引用和修改。但是，创建新节点的过程略有不同。

您可以通过在适当的命名空间中定义节点来创建新节点。例如，以下代码创建一个包含简单净资产收益率 (ROE) 模型的新 Tree Sheet。

BuildTree:=(
  var x=inserttreesheet("MyTree");
  document[x].rootnode="ROE";
  ROE:=Profit/Equity;
  Profit:=PBT-Tax;
  PBT:=100000;
  Tax:=PBT*34%;
  Equity:=Assets-Liabilities;
  Assets:=700000;
  Liabilities:=250000;
)

注意：注意：上面的 BuildTree 定义位于圆括号内，而不是大括号 ({ }) 内。如果代码放在大括号内，它将创建一个新块，并且当函数完成时，新节点将不再存在于模型作用域中。

文档属性参考¶

Data Table 属性

以下是 insertdatasheet 创建的 Data Table 文档的属性：

data [any] 表中包含的数据

vlegend [any] 垂直图例中包含的数据

hlegend [any] 水平图例中包含的数据

dformat (int) 表数据的数字格式，通过组合 Number Format Constants 指定

vformat (int) 表垂直图例的数字格式，通过组合 Number Format Constants 指定

hformat (int) 表水平图例的数字格式，通过组合 Number Format Constants 指定

cellwidth (real) 表中每个单元格的宽度，以字符数指定（使用指定字体的平均字符宽度）

legendwidth (real) 垂直图例的宽度，以字符数指定（使用指定字体的平均字符宽度）

示例：

var x=insertdatasheet("Stock Prices");
document[x].data=[[34.5,33.6,35.1],[80.1,85.2,85.9]];
document[x].vlegend=[2004,2005,2006];
document[x].hlegend=["Stock 1","Stock 2"];
document[x].dformat=FMT_D2+FMT_FIX+FMT_DLR;
document[x].vformat=FMT_D0;
document[x].hformat=0;
document[x].cellwidth=30;
document[x].legendwidth=20;

Diagram 属性

目前没有可以针对 Diagram 文档以编程方式修改的属性。但是，仍然可以通过 insertdiagramsheet 创建新的 Diagram 文档。

Graph 属性

以下是 insertgraph 创建的 Graph 文档的属性：

data (exe)->[real] 图中包含的 Y 数据点，表示为可求值文本（例如节点名）。最多可包含 4 组数据点

x (exe)->[real] X 数据点，表示为可求值文本（例如节点名）

style1 (int) 第一组数据的样式。通过组合 Graph Style Constants 指定。包含图表的 Global Graph Style 和第一组数据的 Individual Trace Style。

style2 (int) 第二组数据的样式。通过组合 Graph Style Constants 指定。包含第二组数据的 Individual Trace Styles。请注意任何 Global Graph Styles 都会被忽略。

style3 (int) 第三组数据的样式。通过组合 Graph Style Constants 指定。包含第三组数据的 Individual Trace Styles。请注意任何 Global Graph Styles 都会被忽略。

style4 (int) 第四组数据的样式。通过组合 Graph Style Constants 指定。包含第四组数据的 Individual Trace Styles。请注意任何 Global Graph Styles 都会被忽略。

title (text) 图表的标题

xlabel (text) x 轴标签

ylabel (text) y 轴标签

legend (exe)->[text] 每个 y 数据集的标签，表示为可执行文本（例如，节点名）

analysis (int) 分析类型。这是一个整数，表示在 Graph Properties 的 Analysis 选项卡上的 Data Filter 列表框中选定的值

param1 (real) 由 analysis 属性指定的分析的第一参数值

param2 (real) 由 analysis 属性指定的分析的第二参数值

param3 (real) 由 analysis 属性指定的分析的第三参数值

param4 (real) 由 analysis 属性指定的分析的第四参数值

formula (bool) True 表示在图表上显示公式，False 表示不显示公式

extent (real) 图表趋势延伸到的值。仅当 useextent 为 True 时使用此值

useextent (bool) True 表示延伸图表趋势（到 extent 中指定的值），False 表示不延伸趋势

yformat (int) y 轴数据的数字格式，通过组合 Number Format Constants 指定

xformat (int) x 轴数据的数字格式，通过组合 Number Format Constants 指定

x1 (real) X 轴下限，仅在使用 GS_LIMITX1 图表样式时使用

x2 (real) X 轴上限，仅在使用 GS_LIMITX2 图表样式时使用

y1 (real) Y 轴下限，仅在使用 GS_LIMITY1 图表样式时使用

y2 (real) Y 轴上限，仅在使用 GS_LIMITY2 图表样式时使用

示例：

var x=insertgraph("Product Sales");
document[x].data="Sales";
document[x].x="Months";
document[x].style1=GS_BAR+GS_AXES+GS_COLOR+GS_LIMITY1;
document[x].style2=GS_BAR;
document[x].title="Sales";
document[x].xlabel="Year";
document[x].ylabel="Millions";
document[x].legend="['ABC','XYZ']";
document[x].yformat=FMT_D0+FMT_DLR;
document[x].y1=0;
Sales:=[[3,7,12,15],[9,10,10,12]];
Months:=[1,2,3,4];

注意：上面的示例代码仅在位于圆括号内而不是大括号内时才能工作，这样它会在模型命名空间执行。

Surface Plot 属性

以下是 :insertgraph3 创建的 Surface Plot 文档的属性

data (exe)->[real] Z 轴值，表示为可执行文本（例如节点名）

x (exe)->[real] X 轴值，表示为可执行文本（例如节点名）

y (exe)->[real] Y 轴值，表示为可执行文本（例如节点名）

style (int) 图表样式，通过组合 Graph Style Constants 指定

title (text) 图表的标题

xlabel (text) X 轴标签

ylabel (text) Y 轴标签

zlabel (text) Z 轴标签

contours (int) 要在图表上绘制的等值线数量。将此值设置为 0 将使图表自动选择合理数量的等值线

xformat (int) x 轴标签的数字格式，通过组合 Number Format Constants 指定

yformat (int) y 轴标签的数字格式，通过组合 Number Format Constants 指定

dformat (int) z 轴标签的数字格式，通过组合 Number Format Constants 指定

示例：

var x=insertgraph3("Sales Grid");
document[x].data="SalesData";
document[x].x="SalesX";
document[x].y="SalesY";
document[x].style=G3_DEFSTYLE;
document[x].title="Title";
document[x].xlabel="x";
document[x].ylabel="y";
document[x].zlabel="Millions";
document[x].dformat=FMT_D0+FMT_DLR;
SalesData:=[[10,18,20],[30,52,40],[25,30,25]];
SalesX:=[1,2];
SalesY:=[1,2];

注意：上面的示例代码仅在位于圆括号内而不是大括号内时才能工作，这样它会在模型命名空间执行。

Report 属性

以下是 insertreportsheet 创建的 Report 文档的属性：

text (text) 工作表的文本

rtf (text) 工作表的 RTF（富文本格式）版本（可包含文本格式）

html (text) 工作表的 HTML 版本。此属性为只读。

editmode (bool) TRUE 表示使报表可编辑，FALSE 表示显示计算值（作为只读）

示例：

var x=insertreportsheet("Sales Report");
document[x].text="\
Sales Report
Sales (in millions) were: <%Sales%>";

Presentation Table 属性

以下是 inserttable 创建的 Presentation Table 文档的属性：

data (exe)->[real] 要显示的数据，表示为可执行文本（例如节点名）

vlegend (exe)->[real] 垂直图例的值，表示为可执行文本（例如节点名）

hlegend (exe)->[real] 水平图例的值，表示为可执行文本（例如节点名）

style (int) 表格样式，通过组合 Table Style Constants 指定

title (text) 表格的标题

vlabel (text) 表格的垂直标签

hlabel (text) 表格的水平标签

tbmargin (real) 每个单元格内的上下边距，以字符高度为单位

lrmargin (real) 每个单元格内的左右边距，以平均字符宽度为单位

dformat (int) 表格数据的数字格式，通过组合 Number Format Constants 指定

vformat (int) 垂直图例的数字格式，通过组合 Number Format Constants 指定

hformat (int) 水平图例的数字格式，通过组合 Number Format Constants 指定

示例：

var x=inserttable("My Table");
document[x].data="Sales Data";
document[x].hlegend="Sales Products";
document[x].style=TS_DEFSTYLE;
document[x].title="Product Sales";
document[x].vlabel="Year";
document[x].hlabel="Product";
document[x].dformat=FMT_D0+FMT_DLR;
Sales Data:=[[3,7,12,15],[9,10,10,12]];
Sales Products:=["ABC","XYZ"];

注意：上面的示例代码仅在位于圆括号内而不是大括号内时才能工作，这样它会在模型命名空间执行。

Text Sheet 属性

以下是 inserttextsheet 创建的 Text Sheet 文档的属性：

text (text) 工作表的文本

rtf (text) 工作表的 RTF（富文本格式）版本（可包含文本格式）

html (text) 工作表的 HTML 版本。此属性为只读。

示例：

var x=inserttextsheet("Instructions");
document[x].text="This is a model for forecasting sales for the next few quarters";

Tree Sheet 表格属性

以下是 inserttreesheet 创建的 Tree Sheet 文档的属性：

rootnode (text) 工作表的根节点名称

pageroot (text) 工作表的已分页节点名称（即，如果用户已分页到某个分支，则与 rootnode 不同）

changenodetype (method) 在 Decision Tree 分析中，调用此属性可在 Decision Node 和 Event Node 之间切换选定节点。

style (int) 树样式，通过组合 Tree Style Constants 指定

title (text) 树工作表的标题

示例：

var x=inserttreesheet("ROE Model");
document[x].rootnode="ROE";
ROE:=Profit/Equity;
Profit:=PBT-Tax;
PBT:=100000;
Tax:=PBT*34%;
Equity:=Assets-Liabilities;
Assets:=700000;
Liabilities:=250000;

注意：上面的示例代码仅在位于圆括号内而不是大括号内时才能工作，这样它会在模型命名空间执行。

节点属性

以下是节点的属性：

note (text) 节点的注释

form (text) 节点的对话框窗体，如果没有窗体则为 null

nodeformat (int) 指定节点的格式，包括最大节点长度。此属性通过组合 Node Format Constants 指定，并可选择添加最大节点长度值 (1-255)。

valueformat (int) 节点的数字格式，通过组合 Number Format Constants 指定

color (int) 节点的颜色（RGB 十六进制格式）。RGB 函数可以帮助将 RGB 强度值转换为十六进制格式。

showformat (int) 节点的显示格式，通过组合 Node Show Format Constants 指定

group (int) 如果非零，定义包含此节点的组的 ID

groupchild (int) 如果非零，则这是一个组节点，此值定义此组中的节点在其 group 属性中将具有的 ID。

value (any) 节点的值

reductionunit (bool) 如果节点定义缩减单位，则为 True

execnamespace (int) 执行命名空间的名称（此节点将在其中执行）

homenamespace (int) 主命名空间的名称（此节点在其中定义）

minargs (text) 节点接受的最小参数数量（+ 1 表示函数名本身）。此属性为只读。

maxargs (text) 节点接受的最大参数数量（+ 1 表示函数名本身）。此属性为只读。

definition (text) 节点的系统定义。此属性为只读。

示例：

注意：此示例基于 Tree Sheet 文档 (ROE) 示例中创建的工作表/节点。建议您先运行该示例以创建 ROE 工作表，然后再运行下面的示例。

each(document[x].valueformat=FMT_SEP+FMT_DLR,x,
user(treelist("ROE")));
document.ROE.valueformat=FMT_PCT;
document.ROE.color=RGB(0,0,255);
document.ROE.note="Return on Equity";

格式常量参考¶

本节列出本章讨论的文档属性所使用的格式常量。通常，样式和格式通过将适当的格式属性设置为所需格式常量的组合来指定。格式常量定义为 "位"，组合时打开或关闭样式和格式属性。格式常量可以使用 Add (+) 运算符或 Bitwise Or (|) 运算符组合。例如，您可以使用以下任一方式定义图表的样式：

document.Graph1.style1=GS_BAR+GS_GRID+GS_AXES;

或

document.Graph1.style1=GS_BAR|GS_GRID|GS_AXES;

在上面的示例中，使用这些标志定义完整样式或格式时，两种方法是等效的。但是，在修改现有样式时，应始终使用 Bitwise Or 和 Bitwise And 方法。例如，如果您想将图表更改为彩色模式，应使用以下方法：

document.Graph1.style1=document.Graph1.style1|GS_COLOR;

同样，如果您想将图表更改为灰度模式（即移除 GS_COLOR 位），应使用以下方法：

document.Graph1.style1=document.Graph1.style1&~GS_COLOR;

注意：使用按位运算符修改现有样式，因为您并不总是知道该样式位是否已设置。例如，如果您使用 Add 运算符意图添加 GS_COLOR 样式位，但 GS_COLOR 样式位已经开启，则图形样式将无法正确设置。

数字格式常量

以下数字格式常量可用于指定数字的显示格式。

小数位/有效数字（仅选择一项）：


FMT_D0	0 位小数
FMT_D1	1 位小数
FMT_D2	2 位小数
FMT_D3	3 位小数
FMT_D4	4 位小数
FMT_D5	5 位小数
FMT_D6	6 位小数
FMT_D7	7 位小数
FMT_D8	8 位小数
FMT_D9	9 位小数

格式（仅选择一项）：


FMT_FIX	定点小数
FMT_SIG	仅有效数字
FMT_SCI	科学记数法
FMT_ENG	工程记数法

样式（可组合多项）：


FMT_ZER	隐藏末尾零
FMT_PCT	百分比
FMT_SEP	千位分隔符
FMT_DLR	货币符号
FMT_PRN	负数加括号
FMT_UNT	化简复合单位

图形样式常量

以下图形样式常量可用于指定图形的样式/类型。全局图形样式定义图形的全局设置，例如轴刻度和网格绘制。单个迹线样式指定图形中不同数据集/迹线的样式（即一个数据集可显示为折线图，另一个显示为条形图等）。曲面图图形样式定义仅适用于曲面图的特殊样式。复合样式是其他基础样式的组合。

全局图形样式


GS_LOGX	使用对数 x 轴刻度；所有 x 值必须大于零
GS_LOGY	使用对数 y 轴刻度；所有 y 值必须大于零
GS_ZERO	在 y 轴中包含零。y 轴范围通常自动选择以包含所有 y 值。此选项强制在 y 范围中包含零。
GS_BOX	在图形周围绘制边界框。此样式与 GS_GRID 样式强制将轴放置在图形的左边缘和下边缘，而非图形内部。
GS_AXES	绘制 x 轴和 y 轴。等同于 GS_AXISX + GS_AXISY。
GS_AXISX	绘制 x 轴
GS_AXISY	绘制 y 轴
GS_GRID	绘制网格。等同于 GS_GRIDX + GS_GRIDY。此样式与 GS_BOX 样式强制将轴放置在图形的左边缘和下边缘，而非图形内部。
GS_GRIDX	在 x 方向绘制网格
GS_GRIDY	在 y 方向绘制网格
GS_ASPECT	使用相同的比例因子调整 x 轴和 y 轴。通常，轴会缩放以适应绘制图形的窗口或页面。选择此样式强制 x 方向的一个单位与 y 方向的一个单位具有完全相同的物理长度。
GS_COLOR	使用颜色区分图形上的不同迹线。通常使用阴影图案或虚线。
GS_AUTO	如果系统中任何节点发生更改，则自动重建图形。若不使用此选项，您可以通过点击 Recalculate（重新计算）按钮显式更新图形。
GS_STACKED	堆叠连续数据集并绘制总和。第一条迹线仅基于 y1 数据集。第二条迹线基于 y1 和 y2 数据集的总和；依此类推。最后一条迹线表示所有 y 数据集的总和。
GS_LIMITX1	使用 x 下限，如图形 x1 属性中所定义
GS_LIMITX2	使用 x 上限，如图形 x2 属性中所定义
GS_LIMITY1	使用 y 下限，如图形 y1 属性中所定义
GS_LIMITY2	使用 y 上限，如图形 y2 属性中所定义

单个迹线样式


GS_AREA	为折线图下方的区域着色
GS_LINE	用直线连接各点
GS_POINT	绘制数据点
GS_BAR	创建条形图。对于条形图，x 轴不按比例绘制，而是为每个 x 点在 x 轴上分配相同的空间。
GS_DELTA	绘制垂直箭头，其高度表示 y 方向上的量值
GS_VALUE	在每个点上方显示 y 值

曲面图样式


GS_MESH	在绘制的曲面上显示与采样点网格对应的网格
GS_CONTOURFILL	使用颜色或灰度级别为曲面图着色，以表示 z 方向上的不同层级
GS_CONTOURLINES	在 z 方向上离散层级之间的边界处绘制等高线
GS_LEGEND	绘制图例，将等高线填充颜色与 z 方向上的层级关联
GS_XFIXED	无论值如何，x 值在 x 轴上均匀分布
GS_CONTOUR	生成无透视和 3D 效果的平面等高线图

复合图形样式


GS_DEFSTYLE	GS_LINE + GS_GRIDX + GS_GRIDY + GS_AXISX + GS_AXISY + GS_COLOR
G3_DEFSTYLE	GS_CONTOURFILL + GS_LEGEND + GS_MESH + GS_BOX + GS_GRID + GS_AXES + GS_COLOR

表格样式常量

以下表格样式常量可用于指定表格的显示样式。复合表格样式是其他基础样式的组合。

表格样式常量


TS_VRULE	在列之间显示垂直分隔线
TS_HRULE	在行之间显示水平分隔线
TS_GRAY	图例列和行使用灰色背景
TS_LEFT	若设置，单元格内容左对齐；若未设置，右对齐
TS_UNIFORM	若设置，使用统一的单元格宽度；若未设置，每列使用尽可能小的宽度
TS_LABEL	将 vlabel 放置在第一列上方，而非整个表格的左侧
TS_AUTO	如果系统中任何节点发生更改，则自动重建表格

复合表格样式


TS_DEFSTYLE	TS_VRULE + TS_HRULE + TS_GRAY + TS_UNIFORM

树样式常量

以下树样式常量可用于指定树形工作表的显示样式。

树样式常量


IDT_SHOWTREE	在工作表上显示树
IDT_SHOWBRANCHES	显示冗余分支
IDT_SHOWTABLE	显示输入/输出表
IDT_SHADOW	在节点后方显示阴影
IDT_COLORCODING	应用颜色编码以反映节点的值
IDT_VARIABLELENGTH	使节点长度适应其内容
IDT_AUTOCALC	当节点定义更改时自动重新计算树
IDT_DECISIONFORMAT	以决策树格式显示树
IDT_SHOWDENODES	在每个末端节点显示"热点"，允许用户双击以快速添加子节点
IDT_HIGHLIGHTPATH	在决策树中高亮显示最优/选定的路径
IDT_DRAFTLAYOUT	以草稿布局显示树
IDT_SHOWFULLNOTE	在每个节点内显示完整注释（多行）。若未选择，则仅显示注释的第一行。
IDT_LISTFORMAT	以列表格式显示树
IDT_PRINTLAYOUT	以打印格式显示树
IDT_DTREEFORMAT	以决策树脚本格式显示
IDT_SHOWPARTENTS	将树顺序从父-子反转为子-父

节点格式常量

以下节点格式常量可用于指定节点的显示格式。

节点格式常量


（节点长度）	节点格式样式的前 8 位为节点长度/最大长度（例如 55+NFMT_LEFT+...）。节点长度可为 0-255。
NFMT_SHOWCOMMENT	在树视图中显示注释
NFMT_SHOWNAME	在树视图中显示名称
NFMT_SHOWDEFINITION	在树视图中显示定义
NFMT_SHOWVALUE	在树视图中显示计算值
NFMT_INPUTFORMAT	将节点设为输入节点
NFMT_OUPUTFORMAT	将节点设为输出节点
NFMT_SHOWEQUATION	以公式格式显示定义
NFMT_SHOWBORDER	在节点周围显示边框
NFMT_BUTTONFORMAT	将节点设为按钮
NFMT_LEFT	节点内容使用左对齐
NFMT_CENTER	节点内容使用居中对齐
NFMT_RIGHT	节点内容使用右对齐
NFMT_ISNOTE	将节点设为浮动文本框
NFMT_ISPICTURE	将节点设为图片
NFMT_NOSELECT	使节点不可选择
NFMT_HOTSPOTFORMAT	将节点设为热点
NFMT_FIXEDWIDTH	将节点设为使用固定长度而非可变长度
NFMT_COMPONENT	节点定义为组件
NFMT_PRIMITIVEFORMAT	当模型作为组件加载时，节点将移至原始命名空间
NFMT_EXPANDBRANCH	在列表视图中展开树的分支
NFMT_HIDECHILDREN	隐藏所有子节点
NFMT_HIDENODE	隐藏节点
NFMT_PAGEBREAK	在节点内容中插入分页符

节点显示格式常量

以下节点显示格式常量可用于指定节点和子节点的显示方式。

节点显示格式常量


NSFT_PAGEBREAK	在此节点后创建分页符
NSFT_HIDENODE	隐藏此节点及所有子节点
NSFT_HIDECHILDREN	隐藏节点的子节点
NSFT_EXPANDBRANCH	当树为列表格式时显示节点的所有子节点。模拟在树中点击展开/折叠（±）