兼容JS的類Web開發(fā)范式

JS FA應(yīng)用的JS模塊(entry/src/main/js/module)的典型開發(fā)目錄結(jié)構(gòu)如下：

1. 項目基本結(jié)構(gòu)

1.1. 目錄結(jié)構(gòu)

1.2. 項目文件分類如下：

• .hml結(jié)尾的HML模板文件，這個文件用來描述當(dāng)前頁面的文件布局結(jié)構(gòu)。

• .css結(jié)尾的CSS樣式文件，這個文件用于描述頁面樣式。

• .js結(jié)尾的JS文件，這個文件用于處理頁面和用戶的交互。

1.3. 目錄模塊劃分：

• app.js文件用于全局JavaScript邏輯和應(yīng)用生命周期管理。

• pages目錄用于存放所有組件頁面。

• common目錄用于存放公共資源文件，比如：媒體資源和JS文件。

• i18n目錄用于配置不同語言場景資源內(nèi)容，比如應(yīng)用文本詞條，圖片路徑等資源。

說明

• i18n是開發(fā)保留文件夾，不可重命名。

• 在使用DevEco Studio進行應(yīng)用開發(fā)時，目錄結(jié)構(gòu)中的可選文件夾需要開發(fā)者根據(jù)實際情況自行創(chuàng)建。

1.4. 文件訪問規(guī)則

應(yīng)用資源可通過絕對路徑或相對路徑的方式進行訪問，本開發(fā)框架中絕對路徑以"/"開頭，相對路徑以"./"或"../"。具體訪問規(guī)則如下：

• 引用代碼文件，需使用相對路徑，比如：../common/utils.js。

• 引用資源文件，推薦使用絕對路徑。比如：/common/xxx.png。

• 公共代碼文件和資源文件推薦放在common下，通過以上兩條規(guī)則進行訪問。

• CSS樣式文件中通過url()函數(shù)創(chuàng)建<url>數(shù)據(jù)類型，如：url(/common/xxx.png)。

說明

當(dāng)代碼文件A需要引用代碼文件B時：

• 如果代碼文件A和文件B位于同一目錄，則代碼文件B引用資源文件時可使用相對路徑，也可使用絕對路徑。

• 如果代碼文件A和文件B位于不同目錄，則代碼文件B引用資源文件時必須使用絕對路徑。因為Webpack打包時，代碼文件B的目錄會發(fā)生變化。

2. 語法

2.1. HML語法

HML是一套類HTML的標(biāo)記語言，通過組件，事件構(gòu)建出頁面的內(nèi)容。頁面具備數(shù)據(jù)綁定、事件綁定、列表渲染、條件渲染等高級能力。

2.1.1. 頁面結(jié)構(gòu)

<!-- 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. 數(shù)據(jù)綁定

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

說明

• 針對數(shù)組內(nèi)的數(shù)據(jù)修改，請使用splice方法生效數(shù)據(jù)綁定變更。

• hml中的js表達(dá)式不支持ES6語法。

2.1.3. 事件綁定

事件綁定的回調(diào)函數(shù)接收一個事件對象參數(shù)，可以通過訪問該事件對象獲取事件信息。

<!-- xxx.hml -->
<div><!-- 通過'@'綁定事件 --><div @click="clickfunc"></div><!-- 通過'on'綁定事件  --><div onclick="clickfunc"></div><!-- 通過'on'綁定事件，不推薦使用5+ --><div onclick="clickfunc"></div><!-- 使用事件冒泡模式綁定事件回調(diào)函數(shù)。5+ --><div on:click.bubble="clickfunc"></div><!-- on:{event}等價于on:{event}.bubble。5+ --><div on:click="clickfunc"></div><!-- 綁定事件回調(diào)函數(shù)，但阻止事件向上傳遞。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應(yīng)用，采用舊寫法（onclick）的事件綁定還是按事件不冒泡進行處理。但如果使用新版本SDK重新打包JS應(yīng)用，將舊寫法按事件冒泡進行處理。為了避免業(yè)務(wù)邏輯錯誤，建議將舊寫法（如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" /><!-- 傳遞額外參數(shù) --><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列表渲染 --><!-- 默認(rèn)$item代表數(shù)組中的元素, $idx代表數(shù)組中的元素索引 --><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循環(huán)的重渲染，旨在列表中的數(shù)據(jù)有變更時，提高重新渲染的效率。tid屬性是用來指定數(shù)組中每個元素的唯一標(biāo)識，如果未指定，數(shù)組中每個元素的索引為該元素的唯一id。例如上述tid="id"表示數(shù)組中的每個元素的id屬性為該元素的唯一標(biāo)識。for循環(huán)支持的寫法如下：

• for="array"：其中array為數(shù)組對象，array的元素變量默認(rèn)為$item。

• for="v in array"：其中v為自定義的元素變量，元素索引默認(rèn)為$idx。

• for="(i, v) in array"：其中元素索引為i，元素變量為v，遍歷數(shù)組對象array。

說明

• 數(shù)組中的每個元素必須存在tid指定的數(shù)據(jù)屬性，否則運行時可能會導(dǎo)致異常。

• 數(shù)組中被tid指定的屬性要保證唯一性，如果不是則會造成性能損耗。比如，示例中只有id和name可以作為tid字段，因為它們屬于唯一字段。

• tid不支持表達(dá)式。

2.1.5. 條件渲染

條件渲染分為2種：if/elif/else和show。兩種寫法的區(qū)別在于：第一種寫法里if為false時，組件不會在vdom中構(gòu)建，也不會渲染，而第二種寫法里show為false時雖然也不渲染，但會在vdom中構(gòu)建；另外，當(dāng)使用if/elif/else寫法時，節(jié)點必須是兄弟節(jié)點，否則編譯無法通過。實例如下：

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

優(yōu)化渲染優(yōu)化：show方法。當(dāng)show為真時，節(jié)點正常渲染；當(dāng)為假時，僅僅設(shè)置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;},
}

說明

• 禁止在同一個元素上同時設(shè)置for和if屬性。

2.2. CSS語法

CSS是描述HML頁面結(jié)構(gòu)的樣式語言。所有組件均存在系統(tǒng)默認(rèn)樣式，也可在頁面CSS樣式文件中對組件、頁面自定義不同的樣式。

2.2.1. 樣式導(dǎo)入

為了模塊化管理和代碼復(fù)用，CSS樣式文件支持 @import 語句，導(dǎo)入 CSS 文件。

2.2.2. 聲明樣式

每個頁面目錄下存在一個與布局hml文件同名的css文件，用來描述該hml頁面中組件的樣式，決定組件應(yīng)該如何顯示。

1. 內(nèi)部樣式，支持使用style、class屬性來控制組件的樣式。例如：

   <!-- index.hml --><div class="container"> ?<text style="color: red">Hello World</text></div>
   /* index.css */.container { ?justify-content: center;}

2. 文件導(dǎo)入，合并外部樣式文件。例如，在common目錄中定義樣式文件style.css，并在index.css文件首行中進行導(dǎo)入：

   /* 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">標(biāo)題</text> ?<div class="content"> ? ?<text id="contentId">內(nèi)容</text> ?</div></div>
/* 頁面樣式xxx.css *//* 對class="title"的組件設(shè)置樣式 */.title {  font-size: 30px;}/* 對id="contentId"的組件設(shè)置樣式 */#contentId {  font-size: 20px;}/* 對所有class="title"以及class="content"的組件都設(shè)置padding為5px */.title, .content {  padding: 5px;}

2.2.4. 偽類

css偽類是選擇器中的關(guān)鍵字，用于指定要選擇元素的特殊狀態(tài)。

名稱	支持組件	描述
:active	input[type="button"]	表示被用戶激活的元素，如：被用戶按下的按鈕。輕量級智能穿戴上偽類選擇器上僅支持background-color 和background-image 的樣式設(shè)置。
:checked	input[type="checkbox"、type="radio"]	表示checked屬性為true的元素。輕量級智能穿戴上偽類選擇器上僅支持background-color 和background-image 的樣式設(shè)置。

偽類示例如下，設(shè)置按鈕的:active偽類可以控制被用戶按下時的樣式：

<!-- index.hml --><div class="container"> ?<input type="button" class="button" value="Button"></input></div>
/* index.css */.button:active {  background-color: #888888;/*按鈕被激活時，背景顏色變?yōu)?888888 */}

2.2.5. 樣式預(yù)編譯

預(yù)編譯提供了利用特有語法生成css的程序，可以提供變量、運算等功能，令開發(fā)者更便捷地定義組件樣式，目前支持less、sass和scss的預(yù)編譯。使用樣式預(yù)編譯時，需要將原css文件后綴改為less、sass或scss，如index.css改為index.less、index.sass或index.scss。

• 當(dāng)前文件使用樣式預(yù)編譯，例如將原index.css改為index.less：

  /* index.less *//* 定義變量 */@colorBackground: #000000;.container { ?background-color: @colorBackground; /* 使用當(dāng)前l(fā)ess文件中定義的變量 */}

• 引用預(yù)編譯文件，例如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中定義的變量 */}

說明

引用的預(yù)編譯文件建議放在common目錄進行管理。

2.3. JS語法參考

JS文件用來定義HML頁面的業(yè)務(wù)邏輯，支持ECMA規(guī)范的JavaScript語言。基于JavaScript語言的動態(tài)化能力，可以使應(yīng)用更加富有表現(xiàn)力，具備更加靈活的設(shè)計。下面講述JS文件的編譯和運行的支持情況。

2.3.1. 語法

支持ES6語法。輕量級智能穿戴支持的ES6語法有限，僅支持以下ES6 語法：

1. let/const

2. arrow functions

3. class

4. default value

5. destructuring assignment

6. destructuring binding pattern

7. enhanced object initializer

8. for-of

9. rest parameter

10. template strings

• 模塊聲明

  使用import方法引入功能模塊：

  import router from '@ohos.router';

• 代碼引用

  使用import方法導(dǎo)入js代碼：

  import utils from '../../common/utils.js';

2.3.2. 對象

• 頁面對象

  屬性	類型	描述
  data	Object/Function	頁面的數(shù)據(jù)模型，類型是對象或者函數(shù)，如果類型是函數(shù)，返回值必須是對象。屬性名不能以$或_開頭，不要使用保留字for, if, show, tid。
  $refs	Object	持有注冊過ref 屬性的DOM元素或子組件實例的對象。

2.3.4. 獲取DOM元素

1. 通過$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();}},
   };

以上就是關(guān)于js在ArkUI方舟UI框架中的語法使用規(guī)則。

參考文檔：

語法-框架說明-兼容JS的類Web開發(fā)范式 (ArkUI.Lite)-ArkTS組件-ArkUI API參考-開發(fā) | 華為開發(fā)者聯(lián)盟 (huawei.com)