打小我就狂
打小我就狂

sciter元素(Element)对象

元素(Element)对象

代表DOM元素。 拥有子对象(sub-objects): 属性(attributes) 和 样式(styles)。

元素(Element)类 派生自 节点(Node)类。

常量

STATE_LINK
STATE_HOVER
STATE_ACTIVE
STATE_FOCUS
STATE_VISITED
STATE_CURRENT
STATE_CHECKED
STATE_DISABLED
STATE_READONLY
STATE_EXPANDED
STATE_COLLAPSED
STATE_INCOMPLETE
STATE_ANIMATING
STATE_FOCUSABLE
STATE_ANCHOR
STATE_POPUP
STATE_OWNS_POPUP
STATE_EMPTY
STATE_BUSY

属性

从 Node类 继承的属性 或者 Node 相关的属性

枚举/遍历

方法/函数

节点(Node)特有的方法

元素的状态标志位，用于get/setState函数。TBD。

length

只读 - integer, 该元素中的子元素数量。只读属性。

[index]

读写 - Element, 子元素在该元素中的索引index位置，读写属性。索引从0开始。

root

只读 - Element, 该元素所属DOM的根元素。只读属性。

view

只读 - View, 元素的父视图(窗口)。只读属性。注意: 如果元素是从另一个view移过来时，element.view可以与全局的view变量并不相同。

parent

只读 - Element, 该元素的父元素。若该元素是根元素，则值为null。只读属性。

layoutParent

只读 - Element, 该元素的布局父元素。若该元素是根元素，则值为null。只读属性。

对于绝对定位(position:absolute)元素，它的layoutParent为该元素用于计算top/left/bottom/right的绝对定位容器(最近的绝对定位父元素)。

owner

只读 - Element, 该元素的拥有元素。若该元素是根元素，则值为null。只读属性。

大多数情况下，拥有元素为父元素，但是对于弹出(popup)元素，拥有元素为该弹出功能的拥有者。例如，对于tooltip元素，它的拥有者为引发该tooltip显示的元素。

index

只读 - Integer, 该元素在父容器中的索引。如果该元素未连接到任何父元素，则值为Undefined。

tag

只读 - String, 该元素的标签(tag)名。只读属性。

id

只读 - String, 该元素的id属性值(如果存在)。只读属性。

next

只读 - Element, 该元素的下一个兄弟元素。如果该元素是父容器中的最后一个，则值为null。

prior

只读 - Element, 该元素的上一个兄弟元素。如果该元素是父容器中的第一个，则值为null。

first

只读 - Element, 该元素的第一个子元素。如果没有子元素，则值为null。

last

只读 - Element, 该元素的最后一个子元素。如果没有子元素，则值为null。

attributes

类 - Attributes, 该元素的html属性集合。

@

类 - 访问 Attributes属性的简短格式, 该元素的html属性集合。它只是上面的attributes的别名。

示例：

this.@["selected"] = true // 或者

this.@#selected = true

等价于

this.attributes["selected"] = true

style

类 - Style, 该DOM元素的CSS样式属性集合。

state

类 - States, 该DOM元素的运行期状态(标志位)集合。

x

类 - Extenders, 附加到该元素上的本地行为(behavior)的列表集合:

  • element.x.length - 附加到该元素上的本地行为数量；
  • element.x[n] - 附加到该元素上的本地行为的第n个行为的名称；
  • element.x.函数名(....) - 调用本地行为实现的方法。

该接口的主要目的是为单独的名称空间提供调用函数的机制。

text

读写 - String, 元素的文本。对于符合元素，该属性返回内容的纯文本形式版本。

html

读写 - String, (内HTML) 元素内容的html源码。返回的文本不包含该元素的前后标签。

值可以设置字符串和Stream流对象。

outerHtml

读写 - String, ( 外HTML) 元素内容的html源码。返回的文本不包含该元素的前后标签。
值可以设置字符串和Stream流对象。

value

读写 - String, 默认情况下，如果元素附加了本地行为，则value值可能为integer, boolean, array等等。例如，若单选框出于"on"状态则返回true。

注意: property value(v) 可以在脚本中的behavior类中覆盖。在这种情况下，为了访问本地value值，可以使用Element.state.value属性。

prototype

读写 - 元素(Element)或行为(Behavior)的实例。Prototype值可以通过CSS(prototype:name_of_global_behavior_variable)或者该属性被设置。

isVisible

只读 - 如果该元素和它的父容器元素处于可见状态(未定义visibility:hidden或display:none)则返回true。

isEnabled

只读 - 如果元素和它的父容器不处在:disabled (setState(Element.STATE_DISABLED))状态时返回true。

ns

读写 - Object, 该元素的名称空间对象。脚本中当前文档定义的所有静态方法和类都属于该名称空间[namespace]的成员。

rows

读写 - integer, 该DOM元素中行(rows)的数量。对于

元素返回它里面的行的数量，对于其他元素则返回CSS的flow属性的行的数量。

columns

读写 - integer, 该DOM元素中列(columns)的数量。对于

元素返回它里面列的数量，对于其他元素则返回CSS的flow属性的列的数量。

options

读写 - Element, 对于

、 、、、元素。

selection

只读 - null | Selection, 若该元素支持选择的行为(如htmlarea、richtext)时返回Selection对象，否则返回null

firstCaretPos

只读 - null | bookmarkbookmark, 返回元素内第一个插入位置(光标)的书签。

lastCaretPos

只读 - null | bookmarkbookmark, 返回元素内最后一个插入位置(光标)的书签。

paintBackground

只写 - null | function(gfx), 设置背景层的绘制函数。该函数能获取到绘制该层的Graphics对象。如果函数返回true时则默认的背景和边框绘制将不会再绘制。背景绘制函数是在本地绘制之前调用。

paintContent

只写 - null | function(gfx), 设置内容层的绘制函数。该函数能获取到绘制该层的Graphics对象。如果函数返回true时则默认的内容绘制将不会再绘制。内容绘制函数是在本地绘制之前调用。

paintForeground

只写 - null | function(gfx), 设置前景层的绘制函数。该函数能获取到绘制该层的Graphics对象。如果函数返回true时则默认的前景绘制将不会再绘制。前景绘制函数是在本地绘制之前调用。

paintOutline

只写 - null | function(gfx), 设置轮廓层的绘制函数。该函数能获取到绘制该层的Graphics对象。如果函数返回true时则默认的前景绘制将不会再绘制。轮廓绘制函数是在本地绘制之前调用。

isPointInside

r/w - null | function(x,y), 一个hit测试函数，这个函数根据x,y坐标值判断该坐标点是否在该元素图形区域内，如果在则返回true，这个元素可以是任意形状。

nodeIndex

只读 - Integer, 该节点在父节点容器中的索引位置。

nextNode

只读 - Element 或 Node, 该节点的下一个节点。若该节点是父容器中的最后一个则返回null。

priorNode

只读 - Element 或 Node, 该节点的上一个节点。若该节点是父容器中的第一个则返回null。

firstNode

只读 - Element 或 Node, 该节点的第一个子节点(元素/文本/注释)的引用。

lastNode

只读 - Element 或 Node, 该节点的最后一个子节点(元素/文本/注释)的引用。

isElement

只写 - 如果该节点是元素(Element)时返回true，否则返回false。

isText

只写 - 如果该节点是文本时返回true，否则返回false。

isComment

只写 - 如果该节点是注释时返回true，否则返回false。

for ... in

for(var child in element) { /* 循环体 */ } 或

for(var (index,child) in element) { /* 循环体 */ }

为element元素的每个子元素执行循环体中的代码。

示例, 对于html中的p元素的for循环:

Hello wonderfull world



循环将会执行一次，child变量将是Element("em")。

this

(tagname[, text])

创建一个新的标签为tagname(字符串/标识符)的元素对象，它的内容为text。使用方法如下：

  var el = new Element("option"); 
  // 或者
  var el = new Element(#option);

元素创建后处于 未连接 状态。为了连接到DOM中，可以使用父元素的insert方法。

create

(object) : Element

DOM元素的静态构造函数。这里的object是一个用下面的微格式(microformat)定义的字符。

示例：下面的代码片段相当于创建一个元素，该元素包含标记：

before after

:

  var para = Element.create { p, "paragraph text" }; 
  //或者文本是变量: 
  var para = Element.create { p, [paragraphText] };

clear

() : undefined

清除一个元素的内容，移除它的所有子元素。

toString

() : string

返回该元素表示的HTML字符串，该字符串是外HTML——包含头和尾标签、内容等同于html的返回值。

clone

() : Element

返回元素的一个新拷贝，该方法为深拷贝。 新元素处于 未连接 状态，可以使用insert()方法插入到DOM中。

select

(CSSselector:string [, argument1 [, argument2, ... ]]) : Element

返回满足CSS选择器(CSSselector, string)的第一个元素。CSSSelector可以包含格式化标识(如%d、%s)，这些标识在最终的CSS选择器字符串中可以被argument1 ... argumentN替代。该函数的使用规则和Stream.printf方法相同。

示例：如果文档包含元素，则下面的语句：

var inp = self.select("input[type='text']");

将会设置inp为这个元素的引用。

$

( CSSselector ) : Element

返回满足CSS选择器的第一个元素。

注意：该选择器写的时候不需要用""括住。

示例： 如果文档包含元素，则下面的语句：

var inp = self.$( input[type='text'] );

将会设置inp为这个元素的引用。

而且下面的代码片段:

  var n = 3;
  var li3 = self.$( ul > li:nth-child({n}) );

将会找到ul列表元素中第三个列表项。

select

(func , CSSselector: string [, argument1 [, argument2, ... ]]) returns: integer

调用func(函数引用)方法来遍历满足CSSselector选择器的每个元素。func函数接受一个参数，该参数为匹配元素的引用。 func函数可以返回true来停止遍历。

示例：下面的代码片段将会打印所有input元素的"name"属性：

function printel(el) { stdout.println( el.attributes["name"] ); }

document.select(printel, "input");

selectAll

(CSSselector: string [, argument1 [, argument2, ... ]]) returns: Array

返回满足CSS选择器(CSSselector, string)的所有元素的数组。CSSSelector可以包含格式化标识(如%d、%s)，这些标识在最终的CSS选择器字符串中可以被argument1 ... argumentN替代。该函数的使用规则和Stream.printf方法相同。

$$

( CSSselector ) returns: Array

返回满足CSS选择器的所有元素的数组。

注意：该选择器写的时候不需要用""括住。

selectParent

(CSSselector: string [, argument1 [, argument2, ... ]]) returns: Element

返回在子/父链上满足CSS选择器的(CSSselector, string)的第一个元素。CSSSelector可以包含格式化标识(如%d、%s)，这些标识在最终的CSS选择器字符串中可以被argument1 ... argumentN替代。该函数的使用规则和Stream.printf方法相同。

注意：该方法也会检查本元素(this)是否满足CSS条件。

$p

( CSSselector ) returns: Element

返回在子/父链上满足CSS选择器的的第一个元素。

注意1：该选择器写的时候不需要用""括住。

注意2：该方法也会检查本元素(this)是否满足CSS条件。

selectParent

(func , CSSselector: string [, argument1 [, argument2, ... ]]) returns: integer

调用func(函数引用)来遍历每个满足CSSselector的元素。func函数接受一个参数，该参数为匹配元素的引用。 func函数可以返回true来停止遍历。

示例：下面的代码片段可以打印出所有父div的id属性：

  function printel(el) {  stdout.println( el.attributes["id"] );  }
  some.selectParent(printel, "div");

注意：该方法也会检查本元素(this)是否满足CSS条件。

$$p

( CSSselector ) returns: Array of Elements

返回在子/父链上满足CSS选择器的的所有元素数组。

注意1：该选择器写的时候不需要用""括住。

注意2：该方法也会检查本元素(this)是否满足CSS条件。

match

( CSSselector: string [, argument1 [, argument2, ... ]]) returns: true | false

检查该DOM元素是否满足给定的CSSselector选择器。

$is

( CSSselector ) returns: true | false

检查该DOM元素是否满足给定的CSSselector选择器。

注意：该选择器写的时候不需要用""括住。

belongsTo

( parent: Element [, useUITree: true | false [, includingThis: true | false ]] ) : true | false

如果在该元素的父链上存在parent元素则返回true。

如果useUITree参数提供了且为true，则该函数使用UI关系而不是DOM树上的父/子链关系。例如，弹出元素可以被声明在它的宿主元素之外，但是如果宿主元素创建该弹出元素后使用该函数将返回true。

如果includingThis参数提供了且为true,则若parent为该元素本身是返回true: el.belongsTo(el,false,true) -> true。includingThis默认为false。

find

(x, y) returns: Element.

返回相对于该元素在x、y坐标位置的子元素的引用。如果该位置没有元素，则返回该元素本身。

update

([deep]) returns: undefined

在修改后重新计算该元素(deep为true时)和刷新它的可视区域。如果由于某些操作会导致该元素尺寸有变化时，请设置deep=true。若果仅仅是装饰属性(不会改变尺寸，如color属性)发生变化，请省略deep参数(或设置它为false)。

update

(stateUpdateFunction) returns: undefined

该方法用于"过渡更新(transactioned update)"。stateUpdateFunction 函数被调用时包含this变量(指向该元素对象)，且预期该函数会改变元素的一些状态、内容、或者它的子元素的状态。

"过渡更新(transactioned update)"机制用在元素期待它的"内容"更新有过渡效果，这些效果在CSS中使用transition:blend()、scroll-***()、slide-***()等定义的。

Element.update(stateUpdateFunction)执行时做以下步骤:

  1. 制作该元素的初始状态快照；
  2. 调用提供的stateUpdateFunction函数来应用所有的该元素的修改至新状态；
  3. 制作最终状态的该元素快照；
  4. 使用这两张快照开始过渡动画(如果在CSS中为该元素定义的话)。

如果没有在CSS为该元素定义过渡效果，则stateUpdateFunction会被调用，且视图会立即将元素更新为最新状态。

refresh

( [ x, y, width, height] ) returns: true|false

刷新该元素在屏幕上占据的区域。如果x、y、width、height (元素内部的区域坐标)被指定，则只会刷新该部分区域。这个方法用在当你使用Graphics对象渲染了元素表面区域时。

animate

( nextStep: function [, whenEnded: function] [, duration: duration | integer] ) : undefined

在元素上开始一段动画。nextStep为动画的步骤函数(修改尺寸、透明度等)。这个函数调用时包含this变量(指向该元素对象)，且它应该返回：

  • true - 继续动画，以系统定义的FPS;
  • integer- 毫秒数, 下一步动画执行的延时, 如果为0则将停止动画;
  • duration - 下一步动画执行的延时, 如果duration为0则将停止动画;
  • false - 停止动画;

如果whenEnded函数被提供，则它会在动画结束时被调用。

duration为动画持续的总时间(毫秒)。如果提供了该参数则nextStep函数的声明应该为：

function nextStep(progress: float) {}

其中，progress为0.0至1.0的浮点数——动画的进度。nextStep总是以接收到progress == 1.0作为最后一步。

一个整数——下一个步骤等待的毫秒数。如果返回0或非整数则动画终止。

否则step回调函数期待为无参数函数:

function nextStep() {}

box

( part [, edge [, relativeTo ]] ) returns: integer, 设备像素

返回该元素边缘的坐标。参数：

  • part -#left, #top, #right, #bottom, #width, #height中定义的常量标识符之一。定义返回盒(矩形)的哪一部分。#part还可以接受以下常量：
    • 如果part是#rect，则该函数返回4个值——左、上、右、下。使用示例：

      var (x1,y1,x2,y2) = this.box(#rect, #inner, #view);
    • 如果part是#rectw，则该函数返回4个值——左、上、宽、高。使用示例：

      var (x,y,w,h) = this.box(#rectw, #inner, #view);
    • 如果part是#dimension，则该函数返回两个值——宽、高。使用示例：

      var (w,h) = this.box(#dimension, #inner);
    • 如果part是#position，则该函数返回两个值——左、上。使用示例：

      var (x,y) = this.box(#position, #inner, #view);
  • edge, 元素的边缘常量标识之一:
    • #margin - 外边距边缘；
    • #border - 边框边缘；
    • #padding - 内边距边缘；
    • #inner, 默认值 - 内部盒边缘；
    • #content - 内容盒边缘。内容盒这里是指元素的内容轮廓，且它不是元素内部盒。比如，等元素设置了overflow属性时，内容盒可以大于内部盒。
    • #client - 客户区域。指#inner内部盒减去(可选的)滚动条区域。
    • #icon -元素图标覆盖的区域。图标这里指元素设置了foreground-repeat: no-repeat;的前景图片。如果该元素没有这样的图片，则函数返回的#width、#height为0。
  • relativeTo, 下面的值之一:
    • #screen - 返回相对于屏幕原点的坐标；
    • #root - 返回相对于根元素(视图)原点的坐标；
    • #parent - 返回相对于它的父元素原点的坐标。注意：是相对于父元素滚动位置。
    • #content - 返回相对于它的父元素的内容区的坐标。注意：不依赖于父元素的滚动位置。
    • #container - 返回相对于布局父元素的坐标。布局父元素可以是和DOM父元素不相同的。如position:absolute的元素的布局父元素就可能和DOM父元素不相同。
    • #self, 默认值 -所有坐标相对于该元素的内部盒原点。
    • #view - 返回相对于Sciter窗口(view对象)原点的坐标。
    • 或者 如果relativeTo等于以下值之一：

      该函数将返回相应部分累积宽度，例：

      var (mx1,my1,mx2,my2) = this.box(#rect, #margin, #inner);

      这里的每个mx*值将是外边距、边框、内边距在左、上、右、下方向上的总和。或者说，这个调用会返回元素内部(内容)盒的外边距的距离。而且这个调用：var (mx1,my1,mx2,my2) = this.box(#rect, #margin, #border); 将只会CSS属性中margin-left、margin-top、margin-right、margin-bottom的计算值。

      • #margin - 外边距边缘；
      • #border - 边框边缘；
      • #padding - 内边距边缘；
      • #inner - 内部盒边缘；

若想获取更多信息，请看CSS的ox model规范: http://www.w3.org/TR/CSS2/box.html

intrinsicWidthMin

( ) : integer, 设备像素

返回元素的最小内在(min-intrinsic)宽度。 最小内在宽度是显示元素没有横向滚动条时的最小宽度。

intrinsicWidthMax

( ) : integer, 设备像素

返回元素的最大内在(max-intrinsic)宽度。最大内在宽度是指显示元素无需换行的情况下的最小宽度。例如，

元素的最大内在宽度是它的文本只有一行时的宽度。

intrinsicHeight

( forWidth: integer ) : integer, 设备像素

返回元素在给定forWidth宽度情况下的最小内在(min-intrinsic)高度。最小内在高度是指显示元素没有垂直滚动条时的高度。

toPixels

( length : length | string | symbol [, #width | #height ] ) : integer, 设备像素

返回length转换为设备像素后的值。该转换是基于当前元素样式的上下文，所以el.toPixels( em(1.4) )将会当前元素中字体尺寸的1.4em对应的像素值。

如果length是一个字符串或标识，则它会被当做一个CSS长度字符，所以length的值可以是el.toPixels(#xx-small)或el.toPixels(#system-scrollbar-width)。

第二个symbol参数用在百分比长度的转换时：

var h50p = el.toPixels( pr(50.0), #height ); - 将会和下面的CSS声明计算出相同的值: height:50%.

scroll

(part) returns: integer, 设备像素

返回元素的各种滚动相关的位置。参数：

part - 以下常量标识之一：

  • #left - 视图相对于内容原点视图左边位置；
  • #top - 视图相对于内容原点视图上边位置；
  • #right - 视图右边缘相对于内容盒右边缘的偏移；
  • #bottom - 视图下边缘相对于内容盒下边缘的偏移；
  • #width - 滚动区域的宽度；
  • #height - 滚动区域的高度；
  • #rect - 返回left,top,right,bottom四个整数值。

scrollTo

( x:int, y:int [, smooth:bool [, unrestricted : bool] ]  ) : void

设置元素到x、y的滚动位置。该元素应该有overflow: hidden-scroll、scroll或者auto(即可以滚动它的内容区)。如果unrestricted被设置为true，则滚动位置将被允许操作内容边界。

scrollToView

( [ toTop:bool, smooth: bool = true ] )

滚动元素到视图——确保元素是可见的。如果toTop为true，则强制元素滚动到它的滚动容器的顶部。该方法做深滚动——它将试图使元素在它的所有滚动容器中可见。如果smooth为false,则将不会使用动画滚动。

注意: 该方法只在建立了盒模型(display: block | inline-block | table-cell 等)的元素上。比如，表格中的

不是一个盒元素。所以要滚到表格中的特定行时，你需要选择该行的第一个单元格元素来调用该方法。

mapLocalToView

(xLocal:int, yLocal:int ) : (int,int)

映射元素的xLocal/yLocal点到xView/yView (window)坐标，它会随着CSS的变化而改变。

mapViewToLocal

(xView:int, yView:int ) : (int,int)

映射视图的xView/yViewl点到xLocal/yLocal (element)坐标，它会随着CSS的变化而改变。

insert

( element | html | object | array [, index = Integer.MAX] ) returns: true | false.

element为将被插入到该元素中index位置的子DOM元素。如果index大于该元素当前的子元素数量，则新元素将会被添加到最后。Index为可选参数，如果省略则元素会被添加到最后。如果element已经是其他元素的子元素，则它将会立即取消与之前元素的连接。

如果第一个参数是字符串(html文本)，则将试图将它插入到给定位置。

如果第一个参数是一个对象，则它会被当做创建新DOM元素的模板。参考该对象的微格式定义

如果第一个参数是一个数组，则它将包含DOM节点的引用(元素 和/或 文本 节点)。

append

( element | html | object | array ) returns: true | false.

等价于insert ( ... , Integer.MAX );

prepend

( element | html | object | array ) returns: true | false.

等价于insert ( ... , 0 );

content

( element | array [, element2 [, element3, ... ]] ) returns: true | false.

替换元素的内容。该函数是el.clear(); el.append(element1); el.append(element2); ...的短格式。

该方法可以用在设置

中的单元格。它会妥善处理col/rowspans。

对于其他所有元素，elementN可以是DOM元素、字符串、对象(使用微格式定义的元素模板)或者元素/节点数组。

$content

( .. inline html .. ) : Element

Stringizer方法，用inline html替代元素的内容。参数是Stringizer方法，即HTML可以这样提供：

var el = ... , num = ...;
el.$content(This is item number { num });

该方法返回该元素本身。

$append

( .. html .. ) : Element

Stringizer方法，将html添加到元素的所有子元素最后。

该方法返回第一个添加的元素。

$prepend

( .. html .. ) : Element

Stringizer方法，插入html到元素的所有子元素第一个。

该方法返回第一个添加的元素。

$after

( .. html .. ) : Element

Stringizer方法，添加html到该元素的后面。

该方法返回第一个添加的元素。

$before

( .. html .. ) : Element

Stringizer方法，添加html到该元素的前面。

该方法返回最后一个添加的元素(即该元素的新this.prior)。

$replace

( .. html .. ) : Element

Stringizer方法，将该元素从DOM中移除并且将html替换到当前位置。

该方法返回第一个添加的元素。

nodes

( ) : Array

该方法创建一个数组并将子元素列表添加到该数组中。其中，文本和注释节点是Node对象，DOM元素是Element对象实例。

detach

( ) : Element

从它的父元素的子元素容器中移除该元素，所以当该方法调用后，该元素的parent将会变成null。如果update为true,则会为它的父元素调用update()。返回该元素。该方法不会销毁它的状态和附加到该元素上的行为，直到GC不在收集该元素(即没有指向它的引用)。

remove

( ) : Element

从它的父元素的子元素容器中移除该元素，所以当该方法调用后，该元素的parent将会变成null。如果update为true,则会为它的父元素调用update()。返回该元素。所有运行时状态和行为将会被该方法销毁。本地行为会接收到BEHAVIOR_DETACHED事件。

load

( url: string[, headers: object] ) returns: true/false

加载url指定的文档的内容作为该元素的内容。对于设置了behavior:frame的元素会加载url指向的html、样式和执行脚本或包含流。指定behavior:frame的元素在加载完成后会发送DOCUMENT_COMPLETE事件。而对于其他元素则只会加载文档的Body部分，且不会加载样式和脚本。如果url指向一个外部资源(如"http://...")，则该方法是异步的，否则该方法将会使用同步方式加载。

如果headers对象(键/值 映射表)被指定，且url是http/https，则HTTP GET请求将会将headers作为请求头。

load

( stream: Stream ) returns: true/false

从内存流中加载文档的内容作为该元素的内容。对于设置了behavior:frame的元素会加载stream流指向的html、样式和执行脚本。指定behavior:frame的元素在加载完成后会发送DOCUMENT_COMPLETE事件。而对于其他元素则只会加载文档的Body部分，且不会加载样式和脚本。

load

( html: string, url:string ) returns: true/false

从html字符串中加载文档的内容作为该元素的内容。对于设置了behavior:frame的元素会加载html参数中的html、样式和执行脚本。指定behavior:frame的元素在加载完成后会发送DOCUMENT_COMPLETE事件。而对于其他元素则只会加载文档的Body部分，且不会加载样式和脚本。

loadImage

( url: string [, callback: function [, useCache: true| false ] ] ) returns: Image | null

从url中加载图像。如果callback被省略，则引擎将会试图同步加载图像。否则(callback是一个函数)引擎会异步处理请求且在图像加载后调用callback函数。

callback函数的声明是function callback(image)，image参数是一个Image类或null(当出错时)。

如果useCache不为false，则该方法将尝试从图像缓存中获取图像，并且下载成功的图像也会放到缓存中。useCache默认值为false。

callback函数的声明是function callback(image, status)，image参数是一个Image类或null(当出错时), status 为http状态(200、404等)。

bindImage

( url: string , img: Image ) returns: true | false

将img对象绑定到url。作为结果，该img可以被用在CSS中(如作为背景)。URL可以是任意的字符串，如"in-memory:dyn-image1"。

bindImage

( url: string ) returns: Image | null

返回先前绑定到该URL上的图像，如果没有图像则返回null。

request

( callback: function | integer, #get | #post | #post-data | #put-data | #post-json | #put-json | #delete, url: string [, params: object [, headers: object] ] ) : Object | Stream | Bytes | Error

发送同步或异步HTTP数据GET/POST请求道服务端/页面(url)，使用JSON-RPC调用。

  • #get、#post、#post-data、#json为标识符——发送的http请求类型：
    • #get - 发送纯HTTP GET请求, URL编码的参数(如果存在)被附加到表单的请求的url中；
    • #post - 发送HTTP POST请求，参数作被序列化为Content-Type: application/x-www-form-urlencoded;charset=utf-8；
    • #post-data - 发送HTTP POST请求，参数作被序列化为Content-Type: multipart/form-data; boundary= ...；
    • #put-data - 发送HTTP PUT请求，参数作被序列化为Content-Type: multipart/form-data; boundary= ...;
    • #post-json - 发送HTTP POST请求，参数作被序列化为JSON:Content-Type: application/json;charset=utf-8;
    • #put-json - 发送HTTP PUT请求，参数作被序列化为JSON:Content-Type: application/json;charset=utf-8;
    • #delete - 发送HTTP DELETE请求。
  • url 是一个字符串 - 处理HTTP请求的服务端页面(位置)的URL。
  • params是一个对象, 它的属性是HTTP请求的服务参数。
  • headers是一个对象 - 一个被单独附加到请求中的键/值对请求头。
  • returns: 对于异步请求返回true|false；对于同步请求返回(status:integer,data:any)——请求的结果，data值见下面，status为HTTP状态代码(如200 - 请求成功, 404 - 资源在服务端未找到)。
如果参数 callback是一个整数，则该参数被当做超时值(毫秒数)，且该函数执行 同步请求。如果callback是一个函数，则服务端的响应将会调用 callback函数来处理。 callback函数的声明如下： 
function dataArrivedCallback( data: any, status: integer );

data值为以下之一:

  • Error对象的实例, 在数据响应解析错误时；
  • stream对象, 如果data为服务端返回文本类型(text/plain、text/html、text/xml等)。
  • 对象、数组实例。如果响应有text/javascript、text/ecmascript、text/tiscript、 application/json类型的内容，且这些内容成功解析到data对象。
  • Bytes对象, 如果服务端返回的类型是二进制类型(image / *等)。在这种情况下，Bytes.type会包含一个字符串——服务端报告的该数据的mime-type。

status为一个整数—— HTTP状态码(如200 - 请求成功, 404 - 资源在服务端未找到)，如果该代码大于12000，则它是WinInet的错误代码。见http://support.microsoft.com/kb/193625。

服务端响应的data示例(type: text/javascript):

({ id : 1234, message : "Hello from XYS server!" })

- 在这种情况下，服务端返回的对象有两个属性：id和message。in this case server returns object having two properties: id and message. ({ 和 })的解释请看这里。

getState

( [ stateFlags:int] ) :int

返回元素的状态。stateFlags参数是一个位集合——STATE_***常量的"或"操作集。 如果stateFlags被提供，则函数返回整数标识集——元素的状态标识和stateFlags的"与"操作。如果stateFlags未指定，则函数返回该元素当前在全状态标识集合。

setState

( stateFlags:int ) :void

设置该元素的状态标识并且更新文档在屏幕上的相应位置(处理样式和刷新)。

clearState

( stateFlags:int ) :void

清除元素的状态标识，且更新文档在屏幕上的相应位置。

capture

( onOff: true | false | #strict ) :void
  • element.capture(true) - 设置"宽松"的鼠标捕获到该元素，鼠标消息被传递到该元素和它的子元素；
  • element.capture(#strict) - 设置"严格"的鼠标捕获到该元素，鼠标消息仅被传递到该元素；
  • element.capture(false) - 从该元素移除鼠标捕获。

popup

( el: Element[, placement: int] ) :void

将el元素作为弹出窗口显示，位置相对于该元素。Placement 是下面两组数字的混合:

相对于this元素的点( 又名 弹出锚点 )

  • 1 - 弹出元素在该元素(锚点)的左下角;
  • 2 - 弹出元素在该元素(锚点)的下面居中的位置;
  • 3 - 弹出元素在该元素(锚点)的右下角;
  • 4 - 弹出元素在该元素(锚点)的中间居左的位置;
  • 5 - 弹出元素在该元素(锚点)的中间居中的位置;
  • 6 - 弹出元素在该元素(锚点)的中间居右的位置;
  • 7 - 弹出元素在该元素(锚点)的左上角;
  • 8 - 弹出元素在该元素(锚点)的上面居中的位置;
  • 9 - 弹出元素在该元素(锚点)的右上角;

popup弹出元素放置在锚点上的点:

  • 1 << 16 - popup元素的bottom-left在锚点上;
  • 2 << 16 - popup元素的bottom-center在锚点上;
  • 3 << 16 - popup元素的bottom-right在锚点上;
  • 4 << 16 - popup元素的center-left在锚点上;
  • 5 << 16 - popup元素的middle-center在锚点上;
  • 6 << 16 - popup元素的middle-right在锚点上;
  • 7 << 16 - popup元素的top-left在锚点上;
  • 8 << 16 - popup元素的top-center在锚点上;
  • 9 << 16 - popup元素的top-right在锚点上;
( 见小键盘上的数字 )。
 

placement参数是可省略的。弹出位置也可以在CSS中通过popup-position属性来定义。

 

popup

( el: Element, x:int, y:int ) :void

将el元素作为弹出窗口在x、y(相对于视图的坐标)坐标位置显示。Placement是7。

( 见小键盘上的数字 )。

closePopup

() :void

如果el或者它的父元素是弹出窗口，则关闭弹出窗口。

timer

( milliseconds: integer, callback: function [, avoidSameOriginCheck : bool ] )

如果milliseconds大于0，则该方法会为DOM元素创建一个有milliseconds延时的计时器。

在milliseconds毫秒延迟后，引擎会调用callback函数并且有一个执行该dom元素的this变量。如果你需要计时器继续执行，则callback函数返回true，否则返回false。

调用timer()方法，且milliseconds = 0时，则会停止计时器。

如果元素正在运行的计时器已经包含相同的callback函数(同源)，则该计时器将会在增加新的计时器之前移除旧的计时器。设置avoidSameOriginCheck参数未true则会抑制同源匹配。

swap

(other: Element ) : null

呼唤两个元素的DOM位置——该方法的拥有者和other元素。返回调用该方法的元素。

sendEvent

( eventCode:int [ , reason : int [, owner: Element | null [, data:value ]]] ) : true | false | value

在该元素的父/子链上冒泡传递(发送)事件。事件被该方法生成，且被链上的元素的onControlEvent方法处理。

  • eventCode 是内建行为的逻辑事件代码(见Event)。或者任意的大于0x1000的整数(自定义控件事件范围)。
  • reason 这里是任意一个整数值(该值对于发送者和接受者是知道的)。
  • owner 是一个可选的指向某项DOM元素。例如，在MENU_ITEM_CLICK事件中，它指向一个元素——弹出菜单的拥有者或null。
  • data是任何一个JSON值——将会同BEHAVIOR_EVENT_PARAMS.data字段传递(见sdk/api/sciter-x-behavior.h文件)。
sendEvent函数会遍历父子链，如果消息被消耗则返回true——即在父子链上的某个元素的 onControlEvent()处理了该事件且返回true。如果父子链上某些元素处理了该事件且设置了 data字段，则sendEvent()方法的data参数值会被更新。

sendEvent

( event:string [, data:value ] ) : true | false | value

在该元素的父/子链上冒泡传递(发送)事件。事件被该方法生成，且被链上的元素的onControlEvent方法处理。

  • event是一个事件名称(可能包含名称空间)，见下面的Element.subscribe/unsubscribe()方法。
  • data是任何一个JSON值——将会同BEHAVIOR_EVENT_PARAMS.data字段传递(见sdk/api/sciter-x-behavior.h文件)。
sendEvent函数会遍历父子链，如果消息被消耗则返回true——即在父子链上的某个元素的 onControlEvent()处理了该事件且返回true。如果父子链上某些元素处理了该事件且设置了 data字段，则sendEvent()方法的data参数值会被更新。

postEvent

( event:string [, data:value ] ) : true

postEvent方法将事件放到内部的发送队列中以便延迟调用sendEvent(name,data)发送消息。该方法是立即返回的。

postEvent

( eventCode:int [ , reason : int [, owner: Element | null [, data:value ]]] ) : undefined

postEvent方法将事件放到内部的发送队列中以便延迟调用sendEvent发送消息。该方法是立即返回的。

sendKeyEvent

( eventDef: object ) : true | false | undefined

sendKeyEvent方法模拟按键事件。eventDef可能有以下字段：

{
  type: Event.KEY_DOWN 或 Event.KEY_UP 或 Event.KEY_CHAR; // 按键事件的类型
  keyCode: int;            // 按键 或 字符代码 如'O'
  altKey: true 或 false;   // 可选, 'ALT' 键按下标志
  shiftKey: true 或 false; // 可选, 'SHIFT' 键按下标志
  ctrlKey: true 或 false;  // 可选, 'CTRL' 键按下标志
  shortcutKey: true 或 false; // 可选, 'CTRL/win' 或 'COMMAND/mac' 键按下标志
  commandKey: true 或 false; // 可选, 'WIN/win' 或 'COMMAND/mac' 键按下标志
}

在捕获/冒泡过程中,该元素或作为target参数。若事件被处理了，则返回true。

sendMouseEvent

( eventDef: object ) : true | false | undefined

sendMouseEvent模拟鼠标事件。eventDef可能有以下字段：

{
  type: Event.MOUSE_ENTER或MOUSE_LEAVE或MOUSE_MOVE或MOUSE_UP或MOUSE_DOWN或MOUSE_DCLICK或MOUSE_WHEEL或MOUSE_TICK或MOUSE_IDLE, // 鼠标事件类型
  altKey: true 或 false;   // 可选, 'ALT' 键按下标志
  shiftKey: true 或 false; // 可选, 'SHIFT' 键按下标志
  ctrlKey: true 或 false;  // 可选, 'CTRL' 键按下标志
  shortcutKey: true 或 false; // 可选, 'CTRL/win' 或 'COMMAND/mac' 键按下标志
  commandKey: true 或 false; // 可选, 'WIN/win' 或 'COMMAND/mac' 键按下标志
  mainButton: true 或 false, // 可选, 鼠标左键按下标志
  propButton: true 或 false, // 可选, 鼠标右键按下标志
  x: int, // 鼠标x坐标，相对于视图
  y: int, // 鼠标y坐标，相对于视图
}

在捕获/冒泡过程中,该元素或作为target参数。若事件被处理了，则返回true。

post

( callback: function [, only_if_not_there:boolean] ) : undefined

该方法运行延迟执行callback函数。当调用callback函数时，this环境变量指向post的调用者。

only_if_not_there可选参数如果被指定，且为true时，运行只延迟发送事件一次。多次post相同的callback函数时，它将会post队列中相同的入口。

url

( [ relativeUrl: string ] ) : string

该方法使用文档的url作为基url，和 relativeUrl组合成绝对url。如果没有relativeUrl，则只返回当前DOM元素所属的文档的url。

sort

( comparator: function [, fromIndex: integer [, numOfElements:integer]] В ) : void

使用comparator函数来排序元素的子元素。comparator函数的声明必须是：

function cmp(el1: Element, el2: Element) : int

如果返回负数则认为el1小于el2，如果返回0则认为他们相等，如果返回正数则认为el1大于el2。

fromIndex和numOfElements用于定义排序元素的范围。

move

( [ x: int, y: int [, w: int, h: int] [, relto] [, mode ][, referencePoint: int]   ) : void

该方法将该元素变成一个"调皮鬼"——它将独立于其他DOM元素进行移动：

声明该元素position:popup且移动它到position(x,y)。如果元素移动到了视图外面则引擎会为它创建一个弹出窗口。第三个参数描述了x和y的角色。如果提供了w、h参数则将会改变元素的尺寸。

mode参数：

  • #auto - 如果元素移动到视图外面将会创建窗口。如果元素在视图内则它会被渲染为popup:fixed。
  • #attached-window - 强制引擎为该元素创建一个弹出窗口。该窗口和它的宿主窗口(视图)是同步移动的。
  • #detached-window - 强制引擎为该元素创建弹出窗口，该元素的窗口位置独立于它的宿主窗口。
  • #detached-topmost-window - 与#detached-window相同，不过是创建在最顶窗口层上。

relto 指示x,y坐标的类型，可以是: #view, #root, #screen或#self。默认为#view.

referencePoint是一个1到9之间的数字 - 定义x,y坐标代表的位置。7代表左上角，5代表元素的中间, 请参考键盘上的数字键盘。注意:如果定义了referencePoint，则x/y定义的是相对于元素边框盒的位置，否则x/y是相对于内容盒的位置。

参考示例：sdk/samples/ideas/moveable-windows/ and sdk/samples/ideas/rect-tracker/ 。

调用move()函数没有参数时将还原元素的默认位置。

见: Element.style.dimension() 方法。

textWidth

( text: string ) : int

以该元素的当前字体计算text文本的宽度。如果文本使用"\n"分隔多行则该方法将返回最宽的字符串的宽度。

textHeight

( text: string ) : int

以该元素的当前字体和行高计算text文本的高度。如果文本使用"\n"分隔多行则该方法将返回所有行字符串高度之和。

subscribe

( handler: function, eventGroup : int [, eventType: int] ) :

将handler函数绑定到该元素DOM对象特定的事件上。

handler函数的声明应该为: function(evt) {...}, 其中evt为描述当前事件详细信息的事件(Event)对象。

eventGroup参数这里是以下常量之一：

  • Event.MOUSE - 鼠标事件组( 如Event.MOUSE_DOWN、Event.MOUSE_UP等 );
  • Event.KEY - 键盘事件组( 如Event.KEY_DOWN、Event.KEY_UP等 );
  • Event.BEHAVIOR_EVENT - 人工合成事件组 ( 如控件事件Event.BUTTON_CLICK、 Event.HYPERLINK_CLICK、Event.BUTTON_STATE_CHANGED等 );
  • Event.FOCUS - 焦点事件组;
  • Event.SCROLL - 滚动事件组;
  • Event.SIZE - 尺寸改变事件;

eventType参数这里是为特定事件组定义的以下常量之一。 eventType 参数是可选的——如果它没有被提供则handler会接收到eventGroup的所有事件。

subscribe()方法依序附加多个和独立的事件处理函数到一个元素上。

注意：subscribe()不是下面定义的事件处理器的onMouse(evt)、onKey(evt)等方法的替代。这是两种不同的事件处理方式。onXXXX()方法用于为元素类的事件处理器类(Behaviors)中定义事件处理。而subscribe()/unsubscribe()方法用于将事件处理器附加到特定的元素上。

该方法返回调用它的元素，则运行链式调用subscribe()。

subscribe

( event: string [, selector: string] , handler: function ) :

将handler函数绑定到该元素或它的子元素DOM对象特定的事件上。event参数这里是一个字符串，它可以接受符号事件名称。

事件名可以含有名称空间。例如："click.mywidget"为一些mywidget组件定义了单击事件。名称空间在你需要一次unsubscribe多个事件处理器时会比较有用。例如el.unsubscribe(".mywidget")会移除所有包含mywidget名称空间的事件处理器。

selector是一个可选参数——子元素的CSS选择器。当需要给一些特定子元素订阅事件处理器时可以使用这个参数。

handler参数可以是任意的 function(evt:Event) {...} - 当事件发生时被调用的回调函数。this变量被设置到evt.target字段上 - 事件发生的最初元素。

要在元素的EVENT_SINKING阶段订阅事件，则需要事件名前添加~标识符。例如下面的示例：

container.subscribe("~keydown", function() {...});

该处理器将会在它的子元素之前接收到keydown事件。

注意：这个方法模仿jQuery的.on()方法且具有相同的语意。

on

上面的subscribe(event: string [, selector: string] , handler: function)方法的别名。

unsubscribe

( handler: function ) or
( eventGroup : int [, eventType: int]) :

unsubscribe()方法从元素上移除事件处理器。

unsubscribe

( event : string [, selector: string]) :

该方法移除元素上匹配的事件处理器。这些事件处理器时使用上面的subscribe("name",...)方法定义的。

示例：

  el.unsubscribe("click");

将会移除所有的"click"名称的事件处理器，即使它们包含名称空间(如"click.mywidget")。

注意：这个方法模拟jQuery的.off()方法。

off

上面的unsubscribe方法的别名。

commonParent

( other : Element) : Element

返回this与other DOM元素的共同父元素。

row

( rowNo: integer) : array of Elements

该函数返回该元素给定行的元素列表(数组)。

column

( colNo: integer) : array of Elements

该函数返回该元素给定列的元素列表(数组)。

rowY

( rowNo: integer) : (y: integer, height: integer)

该函数返回给定行的位置和行高。

columnX

( colNo: integer) : (x: integer, width: integer)

该函数返回指定列的位置和列宽。

transact

( action:function [, name:string] ) : true | false

该方法使可以进行事务操作——一组可以undone/redone的操作集合。action函数的声明为function action(transaction) { ... }

transaction是一个Transaction实例——用于修改DOM状态的原语。当用户在编辑器上选择撤销/重做后，任何修改可以通过这些方法来撤销/重做。

execCommand

( command:string [, attributes:map] ) : true | false

execCommand方法用于执行可撤销的编辑命令。command字符串标识要执行的命令。

编辑命令对所有可编辑元素( 、