用户界面¶

UI-PROTOTYPE 内置了一套常用的模块化用户界面，只需引入所需的界面即可使用。

API¶

所有通用的用户界面相关文件都储存在src/shared，下文均以src/shared为工作目录。

窗口¶

类型	路径
脚本文件	`ui/window.ts`

该模块为渲染进程中窗口管理，主线程中管理窗口请参考：窗口。

函数：`initWindowEvents`¶

function initWindowEvents(): void;

初始化窗口事件。

标题栏¶

类型	路径
HTML 模板	`views/_titlebar.pug`
样式文件	`styles/_titlebar.styl`
脚本文件	`ui/titlebar.ts`
定义文件	`types/ui.d.ts`

若要使用标题栏组件，需要在 HTML 模板中引入 views/_titlebar.pug 和 styles/_titlebar.styl。

实例：`titlebar`¶

该对象为接口 Titlebar 实例。

接口：`Titlebar`¶

方法：`init`¶

function titlebar.init(): void;

初始化标题栏。

方法：`toggleButtonHidden`¶

function toggleButtonHidden(id: string, hidden?: boolean): void;

切换标题栏上指定 ID 的按钮显示或隐藏。

方法：`toggleButtonDisabled`¶

function toggleButtonDisabled(id: string, disabled?: boolean): void;

切换标题栏上指定 ID 的按钮禁用或启用。

方法：`toggleWindowControlHidden`¶

function toggleWindowControlHidden(id: string, hidden?: boolean): void;

切换窗口右上角指定 ID 的按钮显示或隐藏。

方法：`toggleWindowControlDisabled`¶

function toggleWindowControlDisabled(id: string, disabled?: boolean): void;

切换窗口右上角上指定 ID 的按钮禁用或启用。

属性：`state`¶

type state = string | HTMLElement | Dom;

应用程序状态信息。

属性：`buttons`¶

type buttons = TitlebarButton[];

标题栏左侧按钮数组。
参考：TitlebarButton。

属性：`searchbar`¶

type searchbar = UIText | HTMLInputElement | null;

标题栏搜索框，允许设置为 UIText 或 HTMLInputElement 元素。设置为 null 时移除搜索栏。参考：UIText。

属性：`avatar`¶

type avatar = TitlebarAvatar;

可选参数，标题栏右侧头像按钮。
参考：TitlebarAvatar。

属性：`windowControls`¶

type windowControls = TitlebarButton[];

窗口右上角按钮。参考：TitlebarButton。

属性：`windowControlMinimize`¶

type windowControlMinimize = boolean;

检查或设置窗口最小化按钮显示或隐藏。

属性：`windowControlResize`¶

type windowControlResize = boolean;

检查或设置窗口最大化/还原按钮显示或隐藏。

属性：`windowControlClose`¶

type windowControlClose = 'close' | 'hide' | 'none';

检查或设置窗口关闭按钮。

值	说明
`close`	显示该按钮，点击后关闭窗口
`hide`	显示该按钮，点击后隐藏窗口
`none`	隐藏该按钮

接口：`TitlebarButton`¶

属性：`id`¶

type id = string;

必要属性，按钮的 ID，应当保持唯一性。

属性：`icon`¶

type icon = string;

必要属性，按钮的图标名，按钮上不会显示任何文字，所以应当设置一个图标。
参考：图标。

属性：`action`¶

type action = Function;

必要属性，按钮点击回调。

属性：`tooltip`¶

type tooltip = string;

可选参数，图标的工具提示，设置为 undefined 时移除工具提示。参考：Tooltip。

属性：`hidden`¶

type hidden = boolean;

可选参数，设置为 true 时，使按钮隐藏。

属性：`disabled`¶

type disabled = boolean;

可选参数，设置为 true 时，按钮禁用。

接口：`TitlebarAvatar`¶

属性：`img`¶

type img = string;

必要属性，头像文件路径。

属性：`action`¶

type action = Function;

可选参数，头像点击回调。

属性：`action`¶

窗口背景¶

类型	路径
样式文件	`styles/_background.styl`
脚本文件	`ui/background.ts`

函数：`initMica`¶

function initMica(): void;

初始化模拟的 Mica 背景。
默认不使用 mica alt，若修改默认行为，请修改 config/ui.json 中 micaAlt 参数。
注意：不稳定。
已知问题：多屏幕时显示异常。

多页面¶

类型	路径
样式文件	`styles/_pages.styl`
脚本文件	`ui/pages.ts`
定义文件	`types/pages.d.ts`

UI-PROTOTYPE 提供一套可选的页面管理接口，可以轻松的实现多页面、历史记录、页面切换动画。

事件¶

名称	说明
`open`	将要打开新页面时触发
`back`	将要切换到前一页面时触发
`jump`	将要跳转页面时触发
`home`	将要切换到主页时触发
`shortcut`	使用快捷键切换页面时触发

参考：IPagesEvent。

实例：`pages`¶

该对象为接口 IPages 实例。

接口：`IPages`¶

方法：`init`¶

function init(options?: PagesInitOptions): void;

初始化页面管理，推荐在定义主页后初始化。
参考：PagesInitOptions，define。

方法：`home`¶

function home(): Promise<boolean>;

清理历史记录并回到主页。
当主页未定义或事件被阻止时返回 false。

方法：`back`¶

function back(): Promise<void>;

回到上一页面。

方法：`open`¶

function open(
  name: string,
  options?: any,
  animation?: PageSwitchAimationOptions
): Promise<boolean>;

打开新的页面。
name 为要打开的页面名称。 options 为页面构建参数。 animation 为页面打开动画，参考：PageSwitchAimationOptions。当要打开的页面未定义或事件被阻止时返回 false。

方法：`jump`¶

function jump(index: number): Promise<boolean>;

跳转到指定页面。
当 index 对应页面不存在或事件被阻止时返回 false。

方法：`define`¶

function define(name: string, constructor: PageConstructor): void;

定义一个页面。 name 为页面唯一名称，只能使用字母、数字、连字符和下划线。 constructor 为页面类，参考：PageConstructor 和 IPage。

方法：`on`¶

function on<K extends keyof PagesEventMap>(
  name: K,
  listener: (event: PagesEventMap[K]) => any
): void;

添加一个事件监听器。
参考：PagesEventMap 和 IPagesEvent。

方法：`off`¶

function off<K extends keyof PagesEventMap>(
  name: K,
  listener: (event: PagesEventMap[K]) => any
): void;

移除一个事件监听器。
参考：PagesEventMap 和 IPagesEvent。

属性：`history`¶

type history = string[];

只读属性，已打开的页面名称数组。

属性：`shortcutDisabled`¶

type shortcutDisabled = boolean;

启用或禁用页面切换快捷键。

接口：`IPage`¶

页面接口。有关页面类构造函数及静态接口：PageConstructor。

方法：`onShow`¶

function onShow(heroOptions?: HeroOptions): any;

可选方法，页面将显示时调用。
heroOptions 为英雄动画参数，参考：HeroOptions。

方法：`onHide`¶

function onHide(heroOptions?: HeroOptions): any;

可选方法，页面将隐藏时调用。
heroOptions 为英雄动画参数，参考：HeroOptions。

方法：`onClose`¶

function onClose(): any;

页面将关闭时调用，若页面为单例页面，此方法永远不会被调用。
返回 true 将阻止页面关闭。

接口：`PageConstructor`¶

页面构造函数及静态接口，有关页面类实例接口请参考：IPage。

构造函数¶

function constructor(node: HTMLDivElement, utils: IPageUtils, options?: any): IPage;

页面被创建时调用，若页面为单例页面，则只调用一次。
node 为页面元素实例。 utils 为页面工具，参考：IPageUtils。 options 为页面构建参数。

静态函数：`getLayoutOptions`¶

function getLayoutOptions?(options?: any): any;

可选函数，页面元素创建前调用，返回值若为 Object，将会作为页面 HTML 模板编译参数。

静态属性：`SINGLETON_INSTANCE`¶

type SINGLETON_INSTANCE = boolean;

为 true 时，页面为单例页面。

静态属性：`LAYOUT_TEMPLATE`¶

type LAYOUT_TEMPLATE = boolean;

当为 true 时，将使用渲染线程目录下 views/pages/<page_name>.pug 模板构建页面元素。

接口：`IPageUtils`¶

页面工具。

方法：`close`¶

function close(): void;

调用该方法以主动关闭页面。仅在页面为当前页面时有效。

接口：`IPagesEvent`¶

页面事件接口。

方法：`prevent`¶

function prevent(): void;

阻止事件默认行为。

属性：`target`¶

type target = IPage;

只读属性，与该事件有关的页面实例。

属性：`node`¶

type node = HTMLDivElement;

只读属性，与该事件有关的页面元素。

属性：`type`¶

type type = string;

只读属性，事件类型。

接口：`PagesEventMap`¶

页面事件枚举接口。

接口：`PagesInitOptions`¶

页面管理初始化参数接口。

属性：`home`¶

type home = string;

可选参数，主页名称，默认 home。

属性：`shortcutDisabled`¶

type shortcutDisabled = boolean;

可选参数，启用或禁用页面切换快捷键，默认 false。

接口：`HeroOptions`¶

英雄动画参数接口。
注意：不稳定。

属性：`node`¶

type node = HTMLElement;

英雄动画相关元素。

属性：`rect`¶

type rect = DOMRect;

英雄动画相关元素初始位置尺寸信息。

接口：`BasicPageSwitchAnimationOptions`¶

基本页面切换动画参数。

属性：`hero`¶

type hero = HeroOptions;

可选参数，英雄动画参数。

接口：`EntrancePageSwitchAnimationOptions`¶

参数 type 固定为 entrance。

属性：`from`¶

type from = 'bottom' | 'right' | 'left' | 'top';

可选参数，动画进入方向，默认 bottom。

接口：`SlidePageSwitchAnimationOptions`¶

参数 type 固定为 slide。

属性：`from`¶

type from = 'right' | 'left' | 'bottom' | 'top';

可选参数，动画进入方向，默认 right。

接口：`DrillPageSwitchAnimationOptions`¶

参数 type 固定为 drill。

属性：`from`¶

type from = 'in' | 'out';

可选参数，动画进入方向，默认 in。

接口：`FadePageSwitchAnimationOptions`¶

参数 type 固定为 fade。

属性：`outroDuration`¶

type outroDuration = number;

可选参数，淡出时长，单位毫秒，默认 100。

属性：`introDuration`¶

type introDuration = number;

可选参数，淡入时长，单位毫秒，默认 100。

属性：`introWhen`¶

type introWhen = number;

可选参数，淡入开始时间，单位毫秒，默认 0。

接口：`PageSwitchAimationOptions`¶

页面切换动画参数。
由基本参数 BasicPageSwitchAnimationOptions 和其他切换动画参数组成。
默认切换动画类型 entrance。
若要修改默认动画类型，请修改 config/ui.json 中参数 defaultPageSwitchAnimation。

UI 组件¶

类型	路径
样式文件	`styles/_components/*`
脚本文件	`ui/components.ts`
组件脚本文件	`components/*`

函数：`initComponents`¶

function initComponents(...componentNames: ComponentNameMap[]): void;

按需初始化 UI 组件。

函数：`initAllComponents`¶

function initAllComponents(): void;

初始化所有 UI 组件。

类：`UILang`¶

多语言元素。根据键名自动设置翻译文本。
模板：

ui-lang app.name

运行时：

<ui-lang>UI-PROTOTYPE</ui-lang>

方法：`update`¶

function update(): void;

强制更新翻译文本。

属性：`key`¶

type key = string;

翻译键名。

类：`UIScroll`¶

滚动条元素。

#scroll-view
ui-scroll(target="#scroll-view")
ui-scroll(target="#scroll-view" horizontal)

属性：`target`¶

type target = HTMLElement;

绑定的滚动视图元素。

属性：`horizontal`¶

type horizontal = boolean;

检索或设置滚动条为横向滚动条，false 时为纵向滚动条。

类：`UIText`¶

输入框元素。

ui-text(multiLine disabled readonly header="<b>Header</b>" placeholder="<ui-lang>app.name</ui-lang>" value="Value")

静态方法：`generateClearButton`¶

function generateClearButton(
  text: UIText,
  btnId = 'clear'
): {
  button: UITextButton;
  handler: Function;
};

为输入框元素创建一个自动隐藏的清空按钮，并自动绑定对应事件。

方法：`toggleButtonHidden`¶

function toggleButtonHidden(id: string, force?: boolean): void;

切换指定 ID 的按钮显示或隐藏。

方法：`toggleButtonDisabled`¶

function toggleButtonDisabled(id: string, force?: boolean): void;

切换指定 ID 的按钮启用或禁用。

属性：`multiLine`¶

type multiLine = boolean;

查询或设置输入框为单行或多行。

属性：`disabled`¶

type disabled = boolean;

查询或设置输入框禁用或启用。

属性：`readonly`¶

type readonly = boolean;

查询或设置输入框只读模式。

属性：`header`¶

type header = string;

查询或设置输入框头部。

属性：`placeholder`¶

type placeholder = string;

查询或设置输入框占位符。

属性：`value`¶

type value = string;

查询或设置输入框内容。

属性：`autoSuggest`¶

type autoSuggest = (string | UITextSuggest)[] | AutoSuggest;

查询或设置输入框自动补全回调或自动补全内容。
参考：UITextSuggest、AutoSuggest。

属性：`isSelectingSuggest`¶

type isSelectingSuggest = boolean;

只读属性，查询用户是否正在选择自动补全。

属性：`leftButtons`¶

type leftButtons = UITextButton[]

查询或设置输入框左侧按钮。
参考：UITextButton。

属性：`rightButtons`¶

type rightButtons = UITextButton[]

查询或设置输入框右侧按钮。
参考：UITextButton。

类型：`AutoSuggest`¶

type AutoSuggest = (value: string) => (string | UITextSuggest)[];

接受用户输入的文本，动态生成自动补全或建议。

接口：`UITextSuggest`¶

属性：`label`¶

type label = string | HTMLElement | Dom;

建议内容。

属性：`text`¶

type text = string;

可选参数，自动补全内容。

属性：`action`¶

type action = Function;

可选参数，选择建议时的回调函数。

接口：`UITextButton`¶

属性：`icon`¶

type icon = string;

按钮图标。
参考：图标。

属性：`action`¶

type action = (text: UIText, id?: string) => any;

按钮被点击时的回调函数。
id 为按钮 ID。

属性：`tooltip`¶

type tooltip = string;

可选参数，按钮的工具提示。

属性：`id`¶

type id = string;

可选参数，按钮 ID。

属性：`disabled`¶

type disabled = boolean;

可选参数，禁用按钮。

属性：`hidden`¶

type hidden = boolean;

可选参数，隐藏按钮。

模块：`components\tooltip.ts`¶

工具提示模块。
该模块没有导出，只需引入该模块，就可以使用工具提示。

div(tooltip="HTML <i>Text</i> here.")

用户界面¶

API¶

窗口¶

函数：initWindowEvents¶

标题栏¶

实例：titlebar¶

接口：Titlebar¶

方法：init¶

方法：toggleButtonHidden¶

方法：toggleButtonDisabled¶

方法：toggleWindowControlHidden¶

方法：toggleWindowControlDisabled¶

属性：state¶

属性：buttons¶

属性：searchbar¶

属性：avatar¶

属性：windowControls¶

属性：windowControlMinimize¶

属性：windowControlResize¶

属性：windowControlClose¶

接口：TitlebarButton¶

属性：id¶

属性：icon¶

属性：action¶

属性：tooltip¶

属性：hidden¶

属性：disabled¶

接口：TitlebarAvatar¶

属性：img¶

属性：action¶

属性：action¶

窗口背景¶

函数：initMica¶

多页面¶

事件¶

实例：pages¶

接口：IPages¶

方法：init¶

方法：home¶

方法：back¶

方法：open¶

方法：jump¶

方法：define¶

方法：on¶

方法：off¶

属性：history¶

属性：shortcutDisabled¶

接口：IPage¶

方法：onShow¶

方法：onHide¶

方法：onClose¶

接口：PageConstructor¶

构造函数¶

静态函数：getLayoutOptions¶

静态属性：SINGLETON_INSTANCE¶

静态属性：LAYOUT_TEMPLATE¶

接口：IPageUtils¶

方法：close¶

接口：IPagesEvent¶

方法：prevent¶

属性：target¶

属性：node¶

属性：type¶

接口：PagesEventMap¶

接口：PagesInitOptions¶

属性：home¶

属性：shortcutDisabled¶

接口：HeroOptions¶

属性：node¶

属性：rect¶

接口：BasicPageSwitchAnimationOptions¶

属性：hero¶

接口：EntrancePageSwitchAnimationOptions¶

属性：from¶

接口：SlidePageSwitchAnimationOptions¶

属性：from¶

接口：DrillPageSwitchAnimationOptions¶

属性：from¶

接口：FadePageSwitchAnimationOptions¶

属性：outroDuration¶

函数：`initWindowEvents`¶

实例：`titlebar`¶

接口：`Titlebar`¶

方法：`init`¶

方法：`toggleButtonHidden`¶

方法：`toggleButtonDisabled`¶

方法：`toggleWindowControlHidden`¶

方法：`toggleWindowControlDisabled`¶

属性：`state`¶

属性：`buttons`¶

属性：`searchbar`¶

属性：`avatar`¶

属性：`windowControls`¶

属性：`windowControlMinimize`¶

属性：`windowControlResize`¶

属性：`windowControlClose`¶

接口：`TitlebarButton`¶

属性：`id`¶

属性：`icon`¶

属性：`action`¶

属性：`tooltip`¶

属性：`hidden`¶

属性：`disabled`¶

接口：`TitlebarAvatar`¶

属性：`img`¶

属性：`action`¶

属性：`action`¶

函数：`initMica`¶

实例：`pages`¶

接口：`IPages`¶

方法：`init`¶

方法：`home`¶

方法：`back`¶

方法：`open`¶

方法：`jump`¶

方法：`define`¶

方法：`on`¶

方法：`off`¶

属性：`history`¶

属性：`shortcutDisabled`¶

接口：`IPage`¶

方法：`onShow`¶

方法：`onHide`¶

方法：`onClose`¶

接口：`PageConstructor`¶

静态函数：`getLayoutOptions`¶

静态属性：`SINGLETON_INSTANCE`¶

静态属性：`LAYOUT_TEMPLATE`¶

接口：`IPageUtils`¶

方法：`close`¶

接口：`IPagesEvent`¶

方法：`prevent`¶

属性：`target`¶

属性：`node`¶

属性：`type`¶

接口：`PagesEventMap`¶

接口：`PagesInitOptions`¶

属性：`home`¶

属性：`shortcutDisabled`¶

接口：`HeroOptions`¶

属性：`node`¶

属性：`rect`¶

接口：`BasicPageSwitchAnimationOptions`¶

属性：`hero`¶

接口：`EntrancePageSwitchAnimationOptions`¶

属性：`from`¶

接口：`SlidePageSwitchAnimationOptions`¶

属性：`from`¶

接口：`DrillPageSwitchAnimationOptions`¶

属性：`from`¶

接口：`FadePageSwitchAnimationOptions`¶

属性：`outroDuration`¶

属性：`introDuration`¶

属性：`introWhen`¶

接口：`PageSwitchAimationOptions`¶

函数：`initComponents`¶

函数：`initAllComponents`¶

类：`UILang`¶

方法：`update`¶

属性：`key`¶