api文档

本节介绍$ui对象的API文档，这些函数绝大部分需要在"ui";模式下才能调用。

$ui.layout(xml)

• xml {XML} | {string} 布局XML或者XML字符串

将布局XML渲染为视图（View）对象， 并设置为当前视图。

$ui.layoutFile(xmlFile)

• xml {string} 布局XML文件的路径

此函数和ui.layout相似，只不过允许传入一个xml文件路径来渲染布局。

$ui.inflate(xml[, parent = null, attachToParent = false])

• xml {string} | {XML} 布局XML或者XML字符串
• parent {View} 父视图
• attachToParent {boolean} 是否渲染的View加到父视图中，默认为false
• 返回 {View}

将布局XML渲染为视图（View）对象。如果该View将作为某个View的子View，我们建议传入parent参数，这样在渲染时依赖于父视图的一些布局属性能够正确应用。

此函数用于动态创建、显示View。

"ui";

$ui.layout(
    <linear id="container">
    </linear>
);

// 动态创建3个文本控件，并加到container容器中
// 这里仅为实例，实际上并不推荐这种做法，如果要展示列表，
// 使用list组件；动态创建十几个、几十个View会让界面卡顿
for (let i = 0; i < 3; i++) {
    let textView = $ui.inflate(
        <text textColor="#000000" textSize="14sp"/>
    , $ui.container);
    textView.attr("text", "文本控件" + i);
    $ui.container.addView(textView);
}

$ui.registerWidget(name, widget)

• name {string} 组件名称
• widget {Function} 组件

注册一个自定义组件。参考示例->界面控件->自定义控件。

$ui.isUiThread()

• 返回 {boolean}

返回当前线程是否是UI线程。

"ui";

log($ui.isUiThread()); // => true

$threads.start(function () {
    log($ui.isUiThread()); // => false
});

$ui.findView(id)

• id {string} View的ID
• 返回 {View}

在当前视图中根据ID查找相应的视图对象并返回。如果当前未设置视图或找不到此ID的视图时返回null。

一般我们都是通过ui.xxx来获取id为xxx的控件，如果xxx是一个ui已经有的属性，就可以通过$ui.findView()来获取这个控件。

$ui.finish()

结束当前活动并销毁界面。

$ui.setContentView(view)

• view {View}

将视图对象设置为当前视图。

$ui.post(callback[, delay = 0])

• callback {Function} 回调函数
• delay {number} 延迟，单位毫秒

将callback加到UI线程的消息循环中，并延迟delay毫秒后执行（不能准确保证一定在delay毫秒后执行）。

此函数可以用于UI线程中延时执行动作（sleep不能在UI线程中使用），也可以用于子线程中更新UI。

"ui";

ui.layout(
    <frame>
        <text id="result"/>
    </frame>
);

ui.result.attr("text", "计算中");
// 在子线程中计算1+ ... + 10000000
threads.start({
    let sum = 0;
    for (let i = 0; i < 1000000; i++) {
        sum += i;
    }
    // 由于不能在子线程操作UI，所以要抛到UI线程执行
    ui.post(() => {
        ui.result.attr("text", String(sum));
    });
});

$ui.run(callback)

• callback {Function} 回调函数
• 返回 {any} callback的执行结果

将callback在UI线程中执行。如果当前已经在UI线程中，则直接执行callback；否则将callback抛到UI线程中执行（加到UI线程的消息循环的末尾），并等待callback执行结束(阻塞当前线程)。

$ui.statusBarColor(color)

• color {string | number} 颜色

设置当前界面的状态栏颜色。

"ui";
ui.statusBarColor("#000000");

$ui.useAndroidResources()

启用使用Android的布局(layout)、绘图(drawable)、动画(anim)、样式(style)等资源的特性。启用该特性后，在project.json中进行以下配置，就可以像写Android原生一样写界面：

{
    // ...
    androidResources: {
        "resDir": "res",  // 资源文件夹
        "manifest": "AndroidManifest.xml" // AndroidManifest文件路径
    }
}

res文件夹通常为以下结构：

- res
    - layout  // 布局资源
    - drawable // 图片、形状等资源
    - menu // 菜单资源
    - values // 样式、字符串等资源
    // ...

可参考示例->复杂界面->Android原生界面。

$ui.imageCache.clearDiskCache()

[Pro 8.8.16新增]

清除UI的图片文件缓存，通常是清除使用url下载的图片缓存。（比如img控件的url链接加载的图片）

此函数也可用于清除自定义启动图中的图片控件的文件缓存。

此函数和找图找色无关，并不会清除图色相关的图片内存、缓存。

此函数需要若在UI线程执行，会自动切换到IO线程异步执行，因此在UI线程执行时，函数返回不代表文件缓存已全部清理完毕。

$ui.imageCache.clearMemory()

[Pro 8.8.16新增]

清除UI的图片内存缓存。

此函数和找图找色无关，并不会清除图色相关的图片内存、缓存。