兼容JS的类Web开发范式
JS FA应用的JS模块(entry/src/main/js/module)的典型开发目录结构如下：
1. 项目基本结构
1.1. 目录结构
1.2. 项目文件分类如下：
-
.hml结尾的HML模板文件，这个文件用来描述当前页面的文件布局结构。
-
.css结尾的CSS样式文件，这个文件用于描述页面样式。
-
.js结尾的JS文件，这个文件用于处理页面和用户的交互。
1.3. 目录模块划分：
-
app.js文件用于全局JavaScript逻辑和应用生命周期管理。
-
pages目录用于存放所有组件页面。
-
common目录用于存放公共资源文件，比如：媒体资源和JS文件。
-
i18n目录用于配置不同语言场景资源内容，比如应用文本词条，图片路径等资源。
说明
-
i18n是开发保留文件夹，不可重命名。
-
在使用DevEco Studio进行应用开发时，目录结构中的可选文件夹需要开发者根据实际情况自行创建。
1.4. 文件访问规则
应用资源可通过绝对路径或相对路径的方式进行访问，本开发框架中绝对路径以"/"开头，相对路径以"./"或"../"。具体访问规则如下：
-
引用代码文件，需使用相对路径，比如：../common/utils.js。
-
引用资源文件，推荐使用绝对路径。比如：/common/xxx.png。
-
公共代码文件和资源文件推荐放在common下，通过以上两条规则进行访问。
-
CSS样式文件中通过url()函数创建<url>数据类型，如：url(/common/xxx.png)。
说明
当代码文件A需要引用代码文件B时：
-
如果代码文件A和文件B位于同一目录，则代码文件B引用资源文件时可使用相对路径，也可使用绝对路径。
-
如果代码文件A和文件B位于不同目录，则代码文件B引用资源文件时必须使用绝对路径。因为Webpack打包时，代码文件B的目录会发生变化。
2. 语法
2.1. HML语法
HML是一套类HTML的标记语言，通过组件，事件构建出页面的内容。页面具备数据绑定、事件绑定、列表渲染、条件渲染等高级能力。
2.1.1. 页面结构
<!-- xxx.hml -->
<div class="item-container">
<text class="item-title">Image Show</text>
<div class="item-content">
<image src="/common/xxx.png" class="image"></image>
</div>
</div>2.1.2. 数据绑定
<!-- xxx.hml -->
<div onclick="changeText">
<text> {{content[1]}} </text>
</div>
// xxx.js
export default {
data: {
content: ['Hello World!', 'Welcome to my world!']
},
changeText: function() {
this.content.splice(1, 1, this.content[0]);
}
}说明
-
针对数组内的数据修改，请使用splice方法生效数据绑定变更。
-
hml中的js表达式不支持ES6语法。
2.1.3. 事件绑定
事件绑定的回调函数接收一个事件对象参数，可以通过访问该事件对象获取事件信息。
<!-- xxx.hml -->
<div>
<!-- 通过'@'绑定事件 -->
<div @click="clickfunc"></div>
<!-- 通过'on'绑定事件 -->
<div onclick="clickfunc"></div>
<!-- 通过'on'绑定事件，不推荐使用5+ -->
<div onclick="clickfunc"></div>
<!-- 使用事件冒泡模式绑定事件回调函数。5+ -->
<div on:click.bubble="clickfunc"></div>
<!-- on:{event}等价于on:{event}.bubble。5+ -->
<div on:click="clickfunc"></div>
<!-- 绑定事件回调函数，但阻止事件向上传递。5+ -->
<div grab:click.bubble="clickfunc"></div>
<!-- grab:{event}等价于grab:{event}.bubble。5+ -->
<div grab:click="clickfunc"></div>
</div>// xxx.js
export default {
data: {
obj: '',
},
clickfunc: function(e) {
this.obj = 'Hello World';
console.log(e);
},
}说明
事件冒泡机制从API Version 5开始支持。升级SDK后，运行存量JS应用，采用旧写法（onclick）的事件绑定还是按事件不冒泡进行处理。但如果使用新版本SDK重新打包JS应用，将旧写法按事件冒泡进行处理。为了避免业务逻辑错误，建议将旧写法（如onclick）改成新写法（grab:click）。
示例：
<!-- xxx.hml -->
<div class="container">
<text class="title">{{count}}</text>
<div class="box">
<input type="button" class="btn" value="increase" onclick="increase" />
<input type="button" class="btn" value="decrease" @click="decrease" />
<!-- 传递额外参数 -->
<input type="button" class="btn" value="double" @click="multiply(2)" />
<input type="button" class="btn" value="decuple" @click="multiply(10)" />
<input type="button" class="btn" value="square" @click="multiply(count)" />
</div>
</div>// xxx.js
export default {
data: {
count: 0
},
increase() {
this.count++;
},
decrease() {
this.count--;
},
multiply(multiplier) {
this.count = multiplier * this.count;
}
};/* xxx.css */
.container {
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.title {
font-size: 30px;
text-align: center;
width: 200px;
height: 100px;
}
.box {
width: 454px;
height: 200px;
justify-content: center;
align-items: center;
flex-wrap: wrap;
}
.btn {
width: 200px;
border-radius: 0;
margin-top: 10px;
margin-left: 10px;
}2.1.4. 列表渲染
<!-- xxx.hml -->
<div class="array-container">
<!-- div列表渲染 -->
<!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 -->
<div class="item-container" for="{{array}}" tid="id" onclick="changeText">
<text>{{$idx}}.{{$item.name}}</text>
</div>
<!-- 自定义元素变量名称 -->
<div class="item-container" for="{{value in array}}" tid="id" onclick="changeText">
<text>{{$idx}}.{{value.name}}</text>
</div>
<!-- 自定义元素变量、索引名称 -->
<div class="item-container" for="{{(index, value) in array}}" tid="id" onclick="changeText">
<text>{{index}}.{{value.name}}</text>
</div>
</div>// xxx.js
export default {
data: {
array: [
{id: 1, name: 'jack', age: 18},
{id: 2, name: 'tony', age: 18},
],
},
changeText: function() {
if (this.array[1].name === "tony"){
this.array.splice(1, 1, {id:2, name: 'Isabella', age: 18});
} else {
this.array.splice(2, 1, {id:3, name: 'Bary', age: 18});
}
},
}.array-container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.item-container {
margin-top: 10px;
width: 200px;
height: 50px;
flex-direction: column;
}tid属性主要用来加速for循环的重渲染，旨在列表中的数据有变更时，提高重新渲染的效率。tid属性是用来指定数组中每个元素的唯一标识，如果未指定，数组中每个元素的索引为该元素的唯一id。例如上述tid="id"表示数组中的每个元素的id属性为该元素的唯一标识。for循环支持的写法如下：
-
for="array"：其中array为数组对象，array的元素变量默认为$item。
-
for="v in array"：其中v为自定义的元素变量，元素索引默认为$idx。
-
for="(i, v) in array"：其中元素索引为i，元素变量为v，遍历数组对象array。
说明
-
数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。
-
数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。
-
tid不支持表达式。
2.1.5. 条件渲染
条件渲染分为2种：if/elif/else和show。两种写法的区别在于：第一种写法里if为false时，组件不会在vdom中构建，也不会渲染，而第二种写法里show为false时虽然也不渲染，但会在vdom中构建；另外，当使用if/elif/else写法时，节点必须是兄弟节点，否则编译无法通过。实例如下：
<!-- xxx.hml -->
<div class="container">
<button class="btn" type="capsule" value="toggleShow" onclick="toggleShow"></button>
<button class="btn" type="capsule" value="toggleDisplay" onclick="toggleDisplay"></button>
<text if="{{show}}"> Hello-One </text>
<text elif="{{display}}"> Hello-Two </text>
<text else> Hello-World </text>
</div>// xxx.js
export default {
data: {
show: false,
display: true,
},
toggleShow: function() {
this.show = !this.show;
},
toggleDisplay: function() {
this.display = !this.display;
}
}优化渲染优化：show方法。当show为真时，节点正常渲染；当为假时，仅仅设置display样式为none。
<!-- xxx.hml -->
<div class="container">
<button class="btn" type="capsule" value="toggle" onclick="toggle"></button>
<text show="{{visible}}" > Hello World </text>
</div>
// xxx.js
export default {
data: {
visible: false,
},
toggle: function() {
this.visible = !this.visible;
},
}说明
-
禁止在同一个元素上同时设置for和if属性。
2.2. CSS语法
CSS是描述HML页面结构的样式语言。所有组件均存在系统默认样式，也可在页面CSS样式文件中对组件、页面自定义不同的样式。
2.2.1. 样式导入
为了模块化管理和代码复用，CSS样式文件支持 @import 语句，导入 CSS 文件。
2.2.2. 声明样式
每个页面目录下存在一个与布局hml文件同名的css文件，用来描述该hml页面中组件的样式，决定组件应该如何显示。
-
内部样式，支持使用style、class属性来控制组件的样式。例如：
<!-- index.hml --><div class="container"> <text style="color: red">Hello World</text></div> /* index.css */.container { justify-content: center;} -
文件导入，合并外部样式文件。例如，在common目录中定义样式文件style.css，并在index.css文件首行中进行导入：
/* style.css */.title { font-size: 50px;} /* index.css */@import '../../common/style.css';.container { justify-content: center;}
2.2.3. 选择器
css选择器用于选择需要添加样式的元素，支持的选择器如下表所示：
| 选择器 | 样例 | 样例描述 |
|---|---|---|
| .class | .container | 用于选择class="container"的组件。 |
| #id | #titleId | 用于选择id="titleId"的组件。 |
| , | .title, .content | 用于选择class="title"和class="content"的组件。 |
示例：
<!-- 页面布局xxx.hml --><div id="containerId" class="container"> <text id="titleId" class="title">标题</text> <div class="content"> <text id="contentId">内容</text> </div></div>
/* 页面样式xxx.css *//* 对class="title"的组件设置样式 */.title { font-size: 30px;}/* 对id="contentId"的组件设置样式 */#contentId { font-size: 20px;}/* 对所有class="title"以及class="content"的组件都设置padding为5px */.title, .content { padding: 5px;}2.2.4. 伪类
css伪类是选择器中的关键字，用于指定要选择元素的特殊状态。
| 名称 | 支持组件 | 描述 |
|---|---|---|
| :active | input[type="button"] | 表示被用户激活的元素，如：被用户按下的按钮。轻量级智能穿戴上伪类选择器上仅支持background-color 和background-image 的样式设置。 |
| :checked | input[type="checkbox"、type="radio"] | 表示checked属性为true的元素。轻量级智能穿戴上伪类选择器上仅支持background-color 和background-image 的样式设置。 |
伪类示例如下，设置按钮的:active伪类可以控制被用户按下时的样式：
<!-- index.hml --><div class="container"> <input type="button" class="button" value="Button"></input></div>
/* index.css */.button:active { background-color: #888888;/*按钮被激活时，背景颜色变为#888888 */}2.2.5. 样式预编译
预编译提供了利用特有语法生成css的程序，可以提供变量、运算等功能，令开发者更便捷地定义组件样式，目前支持less、sass和scss的预编译。使用样式预编译时，需要将原css文件后缀改为less、sass或scss，如index.css改为index.less、index.sass或index.scss。
-
当前文件使用样式预编译，例如将原index.css改为index.less：
/* index.less *//* 定义变量 */@colorBackground: #000000;.container { background-color: @colorBackground; /* 使用当前less文件中定义的变量 */} -
引用预编译文件，例如common中存在style.scss文件，将原index.css改为index.scss，并引入style.scss：
/* style.scss *//* 定义变量 */$colorBackground: #000000;在index.scss中引用：
/* index.scss *//* 引入外部scss文件 */@import '../../common/style.scss';.container { background-color: $colorBackground; /* 使用style.scss中定义的变量 */}
说明
引用的预编译文件建议放在common目录进行管理。
2.3. JS语法参考
JS文件用来定义HML页面的业务逻辑，支持ECMA规范的JavaScript语言。基于JavaScript语言的动态化能力，可以使应用更加富有表现力，具备更加灵活的设计。下面讲述JS文件的编译和运行的支持情况。
2.3.1. 语法
支持ES6语法。轻量级智能穿戴支持的ES6语法有限，仅支持以下ES6 语法：
-
let/const
-
arrow functions
-
class
-
default value
-
destructuring assignment
-
destructuring binding pattern
-
enhanced object initializer
-
for-of
-
rest parameter
-
template strings
-
模块声明
使用import方法引入功能模块：
import router from '@ohos.router'; -
代码引用
使用import方法导入js代码：
import utils from '../../common/utils.js';
2.3.2. 对象
-
页面对象
属性 类型 描述 data Object/Function 页面的数据模型，类型是对象或者函数，如果类型是函数，返回值必须是对象。属性名不能以$或_开头，不要使用保留字for, if, show, tid。 $refs Object 持有注册过ref 属性的DOM元素或子组件实例的对象。
2.3.4. 获取DOM元素
-
通过$refs获取DOM元素
<!-- index.hml --> <div class="container"> <image-animator class="image-player" ref="animator" images="{{images}}" duration="1s" onclick="handleClick"></image-animator> </div>// index.js export default { data: { images: [ { src: '/common/frame1.png' }, { src: '/common/frame2.png' }, { src: '/common/frame3.png' }, ], }, handleClick() { const animator = this.$refs.animator; // 获取ref属性为animator的DOM元素 const state = animator.getState(); if (state === 'paused') { animator.resume(); } else if (state === 'stopped') { animator.start(); } else { animator.pause(); } }, };
以上就是关于js在ArkUI方舟UI框架中的语法使用规则。
参考文档：
语法-框架说明-兼容JS的类Web开发范式 (ArkUI.Lite)-ArkTS组件-ArkUI API参考-开发 | 华为开发者联盟 (huawei.com)
