HarmonyOS Developer 兼容JS的类Web开发范式

丶龙八夷

发布于 2023-3-24 17:25

浏览

0收藏

HML语法参考

HML（HarmonyOS Markup Language）是一套类HTML的标记语言，通过组件，事件构建出页面的内容。页面具备数据绑定、事件绑定、列表渲染、条件渲染和逻辑控制等高级能力。

页面结构

<!-- 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>

数据绑定

<!-- xxx.hml -->
<div onclick="changeText">
  <text> {{content[1]}} </text>
</div>

/*xxx.css*/
.container{
    margin: 200px;
}

// 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语法。

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

普通事件绑定

事件通过'on'或者'@'绑定在组件上，当组件触发事件时会执行JS文件中对应的事件处理函数。

事件支持的写法有：

"funcName"：funcName为事件回调函数名（在JS文件中定义相应的函数实现）。
"funcName(a,b)"：函数参数例如a，b可以是常量，或者是在JS文件中的data中定义的变量（前面不用写this.）。
示例

<!-- 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;
}

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

冒泡事件绑定⁵⁺

冒泡事件绑定包括：

绑定冒泡事件：on:{event}.bubble。on:{event}等价于on:{event}.bubble。
绑定并阻止冒泡事件向上冒泡：grab:{event}.bubble。grab:{event}等价于grab:{event}.bubble。

说明

冒泡事件是指多个组件嵌套时，组件之间会有层次关系，当这些组件注册了相同的事件时，这个事件会首先运行在该元素上的处理程序，然后运行其父元素上的处理程序，一直向上到其他祖先上的处理程序。如果当一个组件触发了这个事件，它会首先触发该组件的回调函数，然后触发其父元素上的回调函数，然后触发其他祖先上的处理程序。
详细冒泡事件说明参见通用事件章节。

示例

<!-- xxx.hml -->
<div>
   <!-- 使用事件冒泡模式绑定事件回调函数。5+ -->;
    <div on:touchstart.bubble="touchstartfunc"></div>
    <div on:touchstart="touchstartfunc"></div>
    <!-- 绑定事件回调函数，但阻止事件向上传递。5+ -->
    <div grab:touchstart.bubble="touchstartfunc"></div>
    <div grab:touchstart="touchstartfunc"></div>
    <!-- 使用事件冒泡模式绑定事件回调函数。6+ -->
    <div on:click.bubble="clickfunc"></div>
    <div on:click="clickfunc"></div>
    <!-- 绑定事件回调函数，但阻止事件向上传递。6+ -->
    <div grab:click.bubble="clickfunc"></div>
    <div grab:click="clickfunc"></div>
</div>

// xxx.js
export default {
    clickfunc: function(e) {
        console.log(e);
    },
    touchstartfuc: function(e) {
        console.log(e);
    },
}

说明

采用旧写法(onclick)的事件绑定在最小API版本6以下时采用不冒泡处理，在最小API版本为6及6以上时采用冒泡处理。

捕获事件绑定⁵⁺

Touch触摸类事件支持捕获，捕获阶段位于冒泡阶段之前，捕获事件先到达父组件然后达到子组件。

捕获事件绑定包括：

绑定捕获事件：on:{event}.capture。
绑定并阻止事件向下传递：grab:{event}.capture。
示例

<!-- xxx.hml -->
<div>
    <!-- 使用事件捕获模式绑定事件回调函数。5+ -->    
    <div on:touchstart.capture="touchstartfunc"></div>
    <!-- 绑定事件回调函数，但阻止事件向下传递。5+ -->
    <div grab:touchstart.capture="touchstartfunc"></div>
</div>

// xxx.js
export default {
    touchstartfuc: function(e) {
        console.log(e);
    },
}

列表渲染

<!-- xxx.hml -->
<div class="array-container" style="flex-direction: column;margin: 200px;">
  <!-- div列表渲染 -->
  <!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 -->
  <div for="{{array}}" tid="id" onclick="changeText">
    <text>{{$idx}}.{{$item.name}}</text>
  </div>
  <!-- 自定义元素变量名称 -->
  <div for="{{value in array}}" tid="id" onclick="changeText">    
    <text>{{$idx}}.{{value.name}}</text>
  </div>
  <!-- 自定义元素变量、索引名称 -->
  <div 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});
    }
  },
}

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不支持表达式。

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

条件渲染

条件渲染分为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="{{visible}}"> Hello-world1 </text>
  <text elif="{{display}}"> Hello-world2 </text>
  <text else> Hello-World </text>
</div>

/* xxx.css */
.container{
  flex-direction: column;
  align-items: center;
}
.btn{
  width: 280px;
  font-size: 26px;
  margin: 10px 0;
}

// xxx.js
export default {
  data: {
    visible: false,
    display: true,
  },
  toggleShow: function() {
    this.visible = !this.visible;
  },
  toggleDisplay: function() {
    this.display = !this.display;
  }
}

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

优化渲染优化：show方法。当show为true时，节点正常渲染；当为false时，仅仅设置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.css */
.container{
  flex-direction: column;
  align-items: center;
}
.btn{
  width: 280px;
  font-size: 26px;
  margin: 10px 0;
}

// xxx.js
export default {
  data: {
    visible: false,
  },
  toggle: function() {
    this.visible = !this.visible;
  },
}

说明

禁止在同一个元素上同时设置for和if属性。

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

逻辑控制块

<block>控制块使得循环渲染和条件渲染变得更加灵活；block在构建时不会被当作真实的节点编译。注意block标签只支持for和if属性。

<!-- xxx.hml -->
<list>
  <block for="glasses">
    <list-item type="glasses">
      <text>{{$item.name}}</text>
    </list-item>
    <block for="$item.kinds">
      <list-item type="kind">
        <text>{{$item.color}}</text>
      </list-item>
    </block>
  </block>
</list>

// xxx.js
export default {
  data: {
    glasses: [
      {name:'sunglasses', kinds:[{name:'XXX',color:'XXX'},{name:'XXX',color:'XXX'}]},
      {name:'nearsightedness mirror', kinds:[{name:'XXX',color:'XXX'}]},
    ],
  },
}

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

模板引用

HML可以通过element引用模板文件，详细介绍可参考自定义组件章节。

<!-- template.hml -->
<div class="item"> 
  <text>Name: {{name}}</text>
  <text>Age: {{age}}</text>
</div>

<!-- index.hml -->
<element name='comp' src='../../common/template.hml'></element>
<div>
  <comp name="Tony" age="18"></comp>
</div>

CSS语法参考

CSS是描述HML页面结构的样式语言。所有组件均存在系统默认样式，也可在页面CSS样式文件中对组件、页面自定义不同的样式。请参考通用样式了解兼容JS的类Web开发范式支持的组件样式。

尺寸单位

逻辑像素px（文档中以<length>表示）：

○ 默认屏幕具有的逻辑宽度为720px（配置见配置文件中的window小节），实际显示时会将页面布局缩放至屏幕实际宽度，如100px在实际宽度为1440物理像素的屏幕上，实际渲染为200物理像素（从720px向1440物理像素，所有尺寸放大2倍）。

○ 额外配置autoDesignWidth为true时（配置见配置文件中的window小节），逻辑像素px将按照屏幕密度进行缩放，如100px在屏幕密度为3的设备上，实际渲染为300物理像素。应用需要适配多种设备时，建议采用此方法。

百分比（文档中以<percentage>表示）：表示该组件占父组件尺寸的百分比，如组件的width设置为50%，代表其宽度为父组件的50%。

样式导入

为了模块化管理和代码复用，CSS样式文件支持 @import 语句，导入css文件。

声明样式

每个页面目录下存在一个与布局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;
}

选择器

css选择器用于选择需要添加样式的元素，支持的选择器如下表所示：

选择器	样例	样例描述
.class	.container	用于选择class="container"的组件。
#id	#titleId	用于选择id="titleId"的组件。
tag	text	用于选择text组件。
,	.title, .content	用于选择class="title"和class="content"的组件。
#id .class tag	#containerId .content text	非严格父子关系的后代选择器，选择具有id="containerId"作为祖先元素，class="content"作为次级祖先元素的所有text组件。如需使用严格的父子关系，可以使用“>”代替空格，如：#containerId>.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 */
/* 对所有div组件设置样式 */
div {
  flex-direction: column;
}
/* 对class="title"的组件设置样式 */
.title {
  font-size: 30px;
}
/* 对id="contentId"的组件设置样式 */
#contentId {
  font-size: 20px;
}
/* 对所有class="title"以及class="content"的组件都设置padding为5px */
.title, .content {
  padding: 5px;
}
/* 对class="container"的组件下的所有text设置样式 */
.container text {
  color: #007dff;
}
/* 对class="container"的组件下的直接后代text设置样式 */
.container > text {
  color: #fa2a2d;
}

以上样式运行效果如下：

HarmonyOS Developer 兼容JS的类Web开发范式-鸿蒙开发者社区

其中“.container text”将“标题”和“内容”设置为蓝色，而“.container > text”直接后代选择器将“标题”设置为红色。2者优先级相同，但直接后代选择器声明顺序靠后，将前者样式覆盖（优先级计算见选择器优先级）。

选择器优先级

选择器的优先级计算规则与w3c规则保持一致（只支持：内联样式，id，class，tag，后代和直接后代），其中内联样式为在元素style属性中声明的样式。

当多条选择器声明匹配到同一元素时，各类选择器优先级由高到低顺序为：内联样式 > id > class > tag。

伪类

css伪类是选择器中的关键字，用于指定要选择元素的特殊状态。例如，:disabled状态可以用来设置元素的disabled属性变为true时的样式。

除了单个伪类之外，还支持伪类的组合，例如，:focus:checked状态可以用来设置元素的focus属性和checked属性同时为true时的样式。支持的单个伪类如下表所示，按照优先级降序排列：

名称	支持组件	描述
:disabled	支持disabled属性的组件	表示disabled属性变为true时的元素（不支持动画样式的设置）。
:active	支持click事件的组件	表示被用户激活的元素，如：被用户按下的按钮、被激活的tab-bar页签（不支持动画样式的设置）。
:waiting	button	表示waiting属性为true的元素（不支持动画样式的设置）。
:checked	input[type="checkbox"、type="radio"]、 switch	表示checked属性为true的元素（不支持动画样式的设置）。

伪类示例如下，设置按钮的:active伪类可以控制被用户按下时的样式：

<!-- index.hml -->
<div class="container">
  <input type="button" class="button" value="Button"></input>
</div>

/* index.css */
.button:active {
  background-color: #888888;/*按钮被激活时，背景颜色变为#888888 */
}

说明

针对弹窗类组件及其子元素不支持伪类效果，包括popup、dialog、menu、option、picker

样式预编译

预编译提供了利用特有语法生成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目录进行管理。

CSS样式继承⁶⁺

css样式继承提供了子节点继承父节点样式的能力，继承下来的样式在多选择器样式匹配的场景下，优先级排最低，当前支持以下样式的继承：

font-family
font-weight
font-size
font-style
text-align
line-height
letter-spacing
color
visibility

文章转载自：https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/js-framework-syntax-hml-0000001477981005-V3?catalogVersion=V3

分类

卡片开发

IDE

标签

HarmonyOS

已于2023-3-24 17:25:51修改

51CTO

51CTO博客

51CTO学堂

HarmonyOS Developer 兼容JS的类Web开发范式

HML语法参考

页面结构

数据绑定

普通事件绑定

冒泡事件绑定⁵⁺

捕获事件绑定⁵⁺

列表渲染

条件渲染

逻辑控制块

模板引用

CSS语法参考

尺寸单位

样式导入

声明样式

选择器

选择器优先级

伪类

样式预编译

CSS样式继承⁶⁺

目录

订阅鸿蒙技术特刊，精选内容抢先看

51CTO

51CTO博客

51CTO学堂

HarmonyOS Developer 兼容JS的类Web开发范式

HML语法参考

页面结构

数据绑定

普通事件绑定

冒泡事件绑定5+

捕获事件绑定5+

列表渲染

条件渲染

逻辑控制块

模板引用

CSS语法参考

尺寸单位

样式导入

声明样式

选择器

选择器优先级

伪类

样式预编译

CSS样式继承6+

目录

订阅鸿蒙技术特刊，精选内容抢先看

冒泡事件绑定⁵⁺

捕获事件绑定⁵⁺

CSS样式继承⁶⁺