控件基础知识

Tabris.js app的UI界面用原生控件构成，并用JavaScript对象来描述。有各种不同的控件可以使用，比如Button、TextView 或 ScrollView。每个控件类都是Widget的子类， Widget类提供了共通方法来获取属性、设置属性、事件监听以及向父控件添加控件。大多数方法都返回控件本身，便于链式调用。

创建原生控件

每个控件类都接受一个具有初始值的对象来创建原生控件。下面展示了如何用 Tabris.js 创建并初始化控件：

let button = new Button({
  left: 10,
  top: 10,
  text: 'OK'
});

如果你更喜欢声明式UI，你也可以用 JSX 来创建控件。当你生成一个 TypeScript 项目时，JSX的支持已经配置好了。

控件属性

每个原生控件都支持一组属性（比如 text 或color）。这些属性可读并且可以直接覆写，或者使用控件的get() 和 set() 方法。

widget.text = 'Hello World';
let text = widget.text;

get() 和 set() 的例子:

widget.set('text', 'Hello World');
let text = widget.get('text');

和构造函数一样，也可以一次设置多个属性：

button.set({
  text: 'OK',
  background: 'blue'
});

当设置非法值时（比如错误的值类型），如果可以的话，设置的值会被转换，否则会被忽略并在控制台输出警告。set() 方法也会输出警告来说明不支持的属性。

事件

控件可以监听事件，比如交互或属性改变。事件监听可以用 on() 和 once()方法添加，并用off()移除。

示例：

function selectionHandler(event) {
  console.log('Button ' + event.target.text + ' selected!');
};
button.on('select', selectionHandler);

监听函数被调用时，会将一个包含多个属性的事件对象作为其参数，属性内容视不同的事件类型而定。但所有的事件都有下面的共通属性：

type: 事件类型
target: 接收事件的控件
timeStamp: 事件创建的时间，用毫秒表示

事件类形是大小写敏感的。

一个上下文对象可以作为on()方法的第三个参数。然后这个对象可以在监听函数中用this访问。

function selectionHandler() {
  console.log(this.foo);
};
button.on('select', selectionHandler, {foo: 'Hello World'});

once()方法和on() 一样，但它在触发事件后会移除事件监听。

使用off()方法移除事件监听。

Change事件

全部控件都支持属性改变事件，当属性改变时该事件会被触发。全部change事件都以 [propertyName]Changed 命名并且提供了一个ChangeEvent。

除了共通的事件属性外，change 事件包含一个value属性，其值为改变属性的当前值。

示例：

new TextInput().on('textChanged', (event) => {
  console.log('The text has changed to: ' + event.value);
});

使用 ES6 解构语法作为事件参数，通常比较方便，解构语法可以用事件属性来作为变量名：

checkBox.on('selectionChanged', ({target, value: checked}) => {
  target.text = checked ? 'checked' : 'unchecked';
});

动画

所有控件都有animate(properties, options)方法。它接受一个要进行动画的属性组成的对象（类似于 set 方法），以及动画本身需要的一组配置作为参数。动画开始时，所有动画属性都会被设置为目标值。因此，调用 get 方法只会返回动画的初始值或者目标值。只有 transform 和 opacity 属性才可以做动画。

animate 方法会返回一个 Promise 对象，并在动画完成后 resolve。如果动画中止，比如清除控件，promise 会被 rejecte。

示例：

label.animate({
  opacity: 0,
  transform: {
    translationX: 200,
    scaleX: 0.1
  }
}, {
  duration: 1000,
  easing: 'ease-out'
}).then(() => label.dispose());

控件树

设置父控件

控件需要一个父控件使其可见。容器视图(ui.contentView)是所有控件的顶级父控件。可以使用append() 或 appendTo()方法将控件添加到对应控件的层次结构中。

示例：

let button = new Button({
  text: 'OK',
  ...
}).appendTo(parent);

如果控件已经有一个父控件了，它会从当前的父控件中删除然后添加到新的父控件中。在添加控件的父控件中，addChild 事件会被触发。

也可以使用append()一次添加多个控件到父控件：

page.append(okButton, cancelButton);

遍历

参考：Selector API

parent 方法返回控件当前的父控件， children 方法返回子控件。

示例：

let parent = widget.parent();
let firstChild = parent.children()[0];
let lastChild = parent.children().last();

子控件结果列表是一个类数组的WidgetCollection对象。

清除控件

dispose 会清除控件以及其所有子控件。它会在其父控件上触发removeChild事件，并在其自身上触发dispose事件。

示例：

button.on('dispose', () => console.log('Button disposed!'));
button.dispose();

在清除控件后，除了isDisposed()之外的控件方法都不会生效，如果控件已经被清除了，isDisposed()返回true，否则返回false。

原文:

https://youjingyu.github.io/Tabris-Documention/?folderName=guide&pageName=widget-basics.html