提交 f3c000da 编写于 作者: L luoying_ace_admin

revise doc

Signed-off-by: Nluoying_ace_admin <luoying19@huawei.com>
上级 5fc996be
......@@ -4,7 +4,9 @@
> **说明:**
>
>从API Version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
> 从API Version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
>
> 此接口为系统接口。
## 属性
......
......@@ -5,9 +5,9 @@
- 语法
- [HML语法参考](js-service-widget-syntax-hml.md)
- [CSS语法参考](js-service-widget-syntax-css.md)
- [配置数据和事件](js-service-widget-configuration.md)
- [多语言支持](js-service-widget-multiple-languages.md)
- [低版本兼容](js-service-widget-version-compatibility.md)
- [版本兼容适配](js-service-widget-version-compatibility.md)
- [设置主题样式](js-service-widget-theme.md)
- 组件
- 通用
- [通用属性](js-service-widget-common-attributes.md)
......@@ -19,6 +19,7 @@
- [无障碍](js-service-widget-common-accessibility.md)
- [原子布局](js-service-widget-common-atomic-layout.md)
- 容器组件
- [badge](js-service-widget-container-badge.md)
- [div](js-service-widget-container-div.md)
- [list](js-service-widget-container-list.md)
- [list-item](js-service-widget-container-list-item.md)
......@@ -35,8 +36,5 @@
- [progress](js-service-widget-basic-progress.md)
- [span](js-service-widget-basic-span.md)
- [text](js-service-widget-basic-text.md)
- 自定义组件
- [自定义组件基本用法](js-service-widget-custom-basic-usage.md)
- [自定义事件](js-service-widget-custom-events.md)
- [Props](js-service-widget-custom-props.md)
- [自定义组件使用说明](js-service-widget-custom-basic-usage.md)
- [数据类型说明](js-service-widget-appendix-types.md)
# 媒体查询
媒体查询(Media Query)在移动设备上应用十分广泛,开发者经常需要根据设备的大致类型或者特定的特征和设备参数(例如屏幕分辨率)来修改应用的样式。为此媒体查询提供了如下功能:
媒体查询(MediaQuery)在移动设备上应用十分广泛,开发者经常需要根据设备的大致类型或者特定的特征和设备参数(例如屏幕分辨率)来修改应用的样式。为此媒体查询提供了如下功能:
1. 针对设备和应用的属性信息,可以设计出相匹配的布局样式。
......
# 配置数据和事件
卡片使用json文件配置卡片使用的变量和事件,变量的声明在data字段下,事件的声明在actions字段下。
示例:
```json
{
"data": {
"temperature": "35°C",
"city": "hangzhou"
},
"actions": {
"routerEventName": {
"action": "router",
"abilityName": "com.example.myapplication.FormAbility",
"params": {
"message": "weather",
"temperature": "{{temperature}}"
}
},
"messageEventName": {
"action": "message",
"params": {
"message": "weather update"
}
}
}
}
```
可参考示例:[input](./js-service-widget-basic-input.md)[list](js-service-widget-container-list.md)等组件中的用法。
\ No newline at end of file
# badge
应用中如果有需用户关注的新事件提醒,可以采用新事件标记来标识。
> **说明:**
>
> 从API Version 8 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
仅支持单个子组件。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外,还支持如下属性:
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| placement | string | rightTop | 否 | 事件提醒的数字标记或者圆点标记的位置,可选值为:<br/>-&nbsp;right:位于组件右边框。<br/>-&nbsp;rightTop:位于组件边框右上角。<br/>-&nbsp;left:位于组件左边框。 |
| count | number | 0 | 否 | 设置提醒的消息数,默认为0。当设置相应的提醒消息数大于0时,消息提醒会变成数字标记类型,未设置消息数或者消息数不大于0时,消息提醒将采用圆点标记。<br/>说明:当数字设置为大于maxcount时,将使用maxcount显示。count属性最大支持整数值为2147483647。 |
| visible | boolean | false | 否 | 是否显示消息提醒,当收到新信息提醒时可以设置该属性为true,显示相应的消息提醒,如果需要使用数字标记类型,同时需要设置相应的count属性。 |
| maxcount | number | 99 | 否 | 最大消息数限制,当收到新信息提醒大于该限制时,标识数字会进行省略,仅显示maxcount+。<br/>说明:maxcount属性最大支持整数值为2147483647。 |
| config | BadgeConfig | - | 否 | 设置新事件标记相关配置属性。 |
| label | string | - | 否 | 设置新事件提醒的文本值。<br/>说明:使用该属性时,count和maxcount属性不生效。 |
### BadgeConfig
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| badgeColor | &lt;color&gt; | #fa2a2d | 否 | 新事件标记背景色。 |
| textColor | &lt;color&gt; | #ffffff | 否 | 数字标记的数字文本颜色。 |
| textSize | &lt;length&gt; | 10px | 否 | 数字标记的数字文本大小。 |
| badgeSize | &lt;length&gt; | 6px | 否 | 圆点标记的大小。 |
## 样式
支持[通用样式](js-service-widget-common-styles.md)
## 事件
支持[通用事件](js-service-widget-common-events.md)
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<badge class="badge" config="{{badgeconfig}}" visible="true" count="100" maxcount="99">
<text class="text1">example</text>
</badge>
<badge class="badge" visible="true" count="1">
<text class="text2">example</text>
</badge>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
width: 100%;
align-items: center;
}
.badge {
width: 80px;
height: 60px;
margin-top: 30px;
}
.text1 {
background-color: #f9a01e;
font-size: 19fp;
}
.text2 {
background-color: #46b1e3;
font-size: 19fp;
}
```
```json
{
"data":{
"badgeconfig":{
"badgeColor":"#0a59f7",
"textColor":"#ffffff",
"textSize":"9px",
"badgeSize": "14px"
}
}
}
```
![badgeSample](figures/badgeSample.png)
\ No newline at end of file
# 自定义组件基本用法
# 自定义组件使用说明
> **说明:**
>
> 从API Version 8 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
自定义组件是用户根据业务需求,将已有的组件组合,封装成的新组件,可以在工程中多次调用,提高代码的可读性。自定义组件通过element引入到宿主页面,使用方法:
自定义组件是用户根据业务需求,将已有的组件组合,封装成的新组件,可以在工程中多次调用,提高代码的可读性。自定义组件通过element引入到宿主页面,使用方法:
```html
<element name='comp' src='../../common/component/comp.hml'></element>
......@@ -18,10 +19,176 @@
- 事件绑定:自定义组件中绑定子组件事件使用(on|\@)child1语法,子组件中通过{action:"proxy", method: "eventName"}触发事件并进行传值,父组件执行bindParentVmMethod方法并接收子组件传递的参数。
## 自定义组件配置文件标签
| 属性 | 类型 | 描述 |
| -------- | -------- | -------- |
| data | Object | 页面的数据模型,类型是对象。属性名不能以$或_开头,不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。 |
| props | Array/Object | props用于组件之间的通信,可以通过&lt;tag&nbsp;xxxx='value'&gt;方式传递给组件;props名称必须用小写,不能以$或_开头,不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。目前props的数据类型不支持Function。 |
## 添加自定义事件
自定义组件内支持自定义事件,该事件的标识需要action类型指定为proxy,事件名则通过method指定。使用该自定义组件的卡片页面可以通过该事件名注册相应的事件回调,当自定义组件内该自定义事件触发时,会触发卡片页面上注册的回调事件。
> **说明:**
>
> 事件名不支持大写字母。
**自定义子组件示例:**
```html
<!-- comp.hml -->
<div class="container">
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```css
/* comp.css */
.container {
flex-direction:column;
background-color: green;
width: 100%;
height: 100%;
}
.row-3 {
width: 100%;
height: 50px;
background-color: orange;
font-size:15px;
}
```
```json
{
"data": {
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method":"event_1"
}
}
}
```
**父组件示例:**
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp @event_1="click"></comp>
<button value="parentClick" @click="buttonClick"></button>
</div>
```
```css
/* xxx.css */
.container {
background-color: red;
height: 500px;
width: 500px;
}
```
```json
{
"data": {
},
"actions": {
"click": {
"action": "message",
"params": {
"message": "click event"
}
},
"buttonClick": {
"action": "message",
"params": {
"message": "click event 2"
}
}
}
}
```
## props
自定义组件可以通过props声明自定义属性,父组件通过设置属性向子组件传递参数。
### 添加默认值
子组件可以通过固定值default设置默认值,当父组件没有设置该属性时,将使用其默认值。此情况下props属性必须为对象形式,不能用数组形式,示例如下:
```html
<!-- comp.hml -->
<div class="container">
<div class="row-1">
<div class="box-1">
<text>xiaoziti</text>
</div>
<div class="box-2">
<text>{{text}}</text>
</div>
<div class="box-3">
<text>{{textdata[0]}}</text>
</div>
</div>
<div class="row-2" if="true">
<button value="{{progress}}"></button>
</div>
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```json
{
"data": {
"progress": {
"default": "80"
}
},
"props": {
"textdata": {
"default": ["a","b"]
},
"progress": {
"default": 60
},
"text": {
"default": "ha"
}
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method": "event_1"
}
}
}
```
引用子组件comp的父组件示例如下:
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp progress="{{clicknow}}" textdata="{{texts}}" if="false" @event_1="click"></comp>
</div>
```
### 数据单向性
父子组件之间数据的传递是单向的,只能从父组件传递给子组件,子组件不能直接修改父组件传递下来的值,可以将props传入的值用data接收后作为默认值,再对data的值进行修改。
更多说明请参考[props](../arkui-js/js-components-custom-props.md)文档。
\ No newline at end of file
# 自定义事件
自定义组件内支持自定义事件,该事件的标识需要action类型指定为proxy,事件名则通过method指定。使用该自定义组件的卡片页面可以通过该事件名注册相应的事件回调,当自定义组件内该自定义事件触发时,会触发卡片页面上注册的回调事件。
> **说明:**
>
> 事件名不支持大写字母。
## 子组件comp示例:
```html
<!-- comp.hml -->
<div class="container">
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```css
/* comp.css */
.container {
flex-direction:column;
background-color: green;
width: 100%;
height: 100%;
}
.row-3 {
width: 100%;
height: 50px;
background-color: orange;
font-size:15px;
}
```
```json
{
"data": {
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method":"event_1"
}
}
}
```
## 卡片页面示例
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp @event_1="click"></comp>
<button value="parentClick" @click="buttonClick"></button>
</div>
```
```css
/* xxx.css */
.container {
background-color: red;
height: 500px;
width: 500px;
}
```
```j&#39;so
{
"data": {
},
"actions": {
"click": {
"action": "message",
"params": {
"message": "click event"
}
},
"buttonClick": {
"action": "message",
"params": {
"message": "click event 2"
}
}
}
}
```
# Props
自定义组件可以通过props声明属性,父组件通过设置属性向子组件传递参数。通过父组件向下传递参数的示例如下:
## 添加默认值
子组件可以通过固定值default设置默认值,当父组件没有设置该属性时,将使用其默认值。此情况下props属性必须为对象形式,不能用数组形式,示例如下:
```html
<!-- comp.hml -->
<div class="container">
<div class="row-1">
<div class="box-1">
<text>xiaoziti</text>
</div>
<div class="box-2">
<text>{{text}}</text>
</div>
<div class="box-3">
<text>{{textdata[0]}}</text>
</div>
</div>
<div class="row-2" if="true">
<button value="{{progress}}"></button>
</div>
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```json
// comp.json
{
"data": {
"progress": {
"default": "80"
}
},
"props": {
"textdata": {
"default": ["a","b"]
},
"progress": {
"default": 60
},
"text": {
"default": "ha"
}
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method": "event_1"
}
}
}
```
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp progress="{{clicknow}}" textdata="{{texts}}" if="false" @event_1="click"></comp>
</div>
```
## 数据单向性
父子组件之间数据的传递是单向的,只能从父组件传递给子组件,子组件不能直接修改父组件传递下来的值,可以将props传入的值用data接收后作为默认值,再对data的值进行修改。
更多说明请参考[props](../arkui-js/js-components-custom-props.md)
\ No newline at end of file
......@@ -25,7 +25,7 @@ JS服务卡片(entry/src/main/js/Widget)的典型开发目录结构如下:
- .css结尾的CSS样式文件,这个文件用于描述页面样式。
- .json结尾的JSON文件,这个文件用于配置卡片中使用的变量action事件。
- .json结尾的JSON配置文件,这个文件用于配置卡片中使用的变量action事件。
各个文件夹的作用:
......@@ -41,11 +41,11 @@ JS服务卡片(entry/src/main/js/Widget)的典型开发目录结构如下:
- 引用代码文件,需使用相对路径,比如:../common/style.css。
- 引用资源文件,推荐使用绝对路径。比如:/common/xxx.png。
- 引用资源文件,推荐使用绝对路径。比如:/common/test.png。
- 公共代码文件和资源文件推荐放在common下,通过规则1和规则2进行访问。
- CSS样式文件中通过url()函数创建&lt;url&gt;数据类型,如:url(/common/xxx.png)。
- CSS样式文件中通过url()函数创建&lt;url&gt;数据类型,如:url(/common/test.png)。
> **说明:**
> 当代码文件A需要引用代码文件B时:
......
......@@ -24,15 +24,16 @@ HML(OpenHarmony Markup Language)是一套类HTML的标记语言,通过组
```html
<!-- xxx.hml -->
<div class="item-container">
<text>{{content}} </text> <!-- 输出:Hello World!-->
<text>{{key1}} {{key2}}</text> <!-- 输出:Hello World6+-->
<text>key1 {{key1}}</text> <!-- 输出:key1 Hello 6+-->
<text>{{flag1 && flag2}}</text> <!-- 输出:false 6+-->
<text>{{flag1 || flag2}}</text> <!-- 输出:true 6+-->
<text>{{!flag1}}</text> <!-- 输出:false 6+-->
<text>{{content}}</text> <!-- 输出:Hello World!-->
<text>{{key1}} {{key2}}</text> <!-- 输出:Hello World-->
<text>key1 {{key1}}</text> <!-- 输出:key1 Hello-->
<text>{{flag1 && flag2}}</text> <!-- 输出:false-->
<text>{{flag1 || flag2}}</text> <!-- 输出:true-->
<text>{{!flag1}}</text> <!-- 输出:false-->
</div>
```
卡片hml文件中的变量需要在json文件的data字段下进行声明:
```json
{
......@@ -46,18 +47,17 @@ HML(OpenHarmony Markup Language)是一套类HTML的标记语言,通过组
}
```
> **说明:**
> - key值支持对象操作符和数组操作符,如{{key.value}}、{{key[0]}}。
>
> - 从 API Version 6 开始支持字符串拼接、逻辑运算和三元表达式。
> - 支持字符串拼接、逻辑运算和三元表达式。
> - 字符串拼接:
> - 支持变量跟变量:{{key1}}{{key2}}等
> - 支持常量跟变量: "my name is {{name}}, i am from {{city}}." "key1 {{key1}}"
> - 逻辑运算:
> - 与:{{flag1 &amp;&amp; flag2}}(仅支持两个boolean变量间的与)
> - 或:{{flag1 || flag2}} (仅支持两个boolean变量间的或)
> - 非:{{!flag1}} (仅支持boolean变量的非运行
> - 与:{{flag1 &amp;&amp; flag2}}(仅支持两个boolean变量间的与逻辑运算
> - 或:{{flag1 || flag2}} (仅支持两个boolean变量间的或逻辑运算
> - 非:{{!flag1}} (仅支持boolean变量的非逻辑运算
> - 三元表达式
> - {{flag? key1:key2}}(flag为boolean变量,key1和key2可以是变量,也可以是常量)
> - 注意事项
......@@ -66,7 +66,7 @@ HML(OpenHarmony Markup Language)是一套类HTML的标记语言,通过组
## 事件绑定
卡片仅支持click通用事件,事件的定义只能是直接命令式,事件定义必须包含action字段,用以说明事件类型。卡片支持两种事件类型:跳转事件(router)和消息事件(message)。跳转事件可以跳转到卡片提供方的OpenHarmony应用,消息事件可以将开发者自定义信息传递给卡片提供方。事件参数支持变量,变量以"{{}}"修饰。跳转事件中若定义了params字段,则在被拉起应用的onStart的intent中,可用"params"作为key将跳转事件定义的params字段的值取到。
卡片的事件需要在json文件的actions字段下进行声明。卡片仅支持click通用事件,事件的定义只能是直接命令式,事件定义必须包含action字段,用以说明事件类型。卡片支持两种事件类型:跳转事件(router)和消息事件(message)。跳转事件可以跳转到卡片提供方的OpenHarmony应用,消息事件可以将开发者自定义信息传递给卡片提供方。事件参数支持变量,变量以"{{}}"修饰。跳转事件中若定义了params字段,则在被拉起应用的onStart的intent中,可用"params"作为key将跳转事件定义的params字段的值取到。
- 跳转事件格式
......@@ -99,20 +99,7 @@ HML(OpenHarmony Markup Language)是一套类HTML的标记语言,通过组
| 选择器 | 类型 | 默认值 | 样例描述 |
| ------ | ------ | -------- | ---------------------------------------- |
| action | string | "router" | 事件类型。<br>- "router":用于应用跳转。<br>- "message":自定义点击事件。 |
| want | Object | - | 跳转目标应用的信息,参考want格式表。 |
**表1** want格式
| 选择器 | 类型 | 默认值 | 样例描述 |
| ----------- | -------------------- | ------------ | ---------------------------------------- |
| bundleName | string | - | 表示包描述。如果在Want中同时指定了BundleName和AbilityName,则Want可以直接匹配到指定的Ability。 |
| abilityName | string | - | 表示待启动的Ability名称。 |
| action | string | - | 表示action选项描述。 |
| uri | string | - | 表示Uri描述。如果在Want中指定了Uri,则Want将匹配指定的Uri信息,包括scheme, schemeSpecificPart, authority和path信息。 |
| type | string | "text/plain" | 表示MIME type类型描述,比如:"text/plain" 、 "image/*"等。 |
| flags | number | - | 表示处理Want的方式。默认传数字,具体参考[flags说明](../apis/js-apis-featureAbility.md#flags说明)。 |
| entities | Array\<string> | - | 类别,用于指定Intent的操作类别。 |
| parameters | {[key: string]: any} | - | 表示WantParams描述。 |
| want | [Want](../apis/js-apis-application-Want.md) | - | 跳转目标应用的信息,参考want格式表。 |
```json
......
# 设置主题样式
卡片目前支持修改的主题样式如下:
| 名称 | 描述 |
| ------------------ | ----------------------------- |
| app_background | 设置卡片背景颜色。 |
修改主题样式需要在widget文件夹下手动创建与pages同级的resources文件夹,在widget/resources/styles/default.json文件中配置主题样式。例如,修改卡片默认的背景色为浅灰色:
```json
{
"style": {
"app_background": "#dcdcdc"
}
}
```
\ No newline at end of file
# 低版本兼容
# 版本兼容适配
卡片特性不断增加,使用了新特性的卡片,在不支持这些新特性的老系统上可能显示异常。可以在卡片工程中指定最小SDK版本,防止使用新特性的卡片推送安装在老的系统上。也可以参考本章节的内容,在卡片开发阶段做前向兼容适配。
> **说明:**
>
> 低版本兼容能力从 API Version 6 开始支持。
开发者可以通过JSON配置文件配置前向兼容能力。该文件提供了apiVersion属性用于兼容版本,该字段和卡片配置文件的数据字段data、事件字段actions同级。在apiVersion标签下定义的内容会基于当前运行版本信息,覆盖原始的data标签内容。
示例如下:
假设JS服务卡片框架从API Version 6开始,支持引用系统内置资源颜色,从API Version 7开始支持slider组件(仅用于举例,不代表实际情况),则可以按照如下的方式,做前向兼容。
假设JS服务卡片框架从API Version 9开始,支持设置webp格式的图源(仅用于举例,不代表实际情况),则可以按照如下的方式,做前向兼容。
```html
<!-- xxx.hml -->
<div style="background-color: {{myBackgroundColor}}">
<text>hello world</text>
<slider if="{{canUseSlider}}" min="0" max="100"></slider>
<div>
<image src="{{imageSrc}}" style="width: 100px;height: 100px;"></image>
</div>
```
xxx.json配置文件:
JSON配置文件:
```json
{
"data": {
"myBackgroundColor": "#87ceeb",
"canUseSlider": "false"
"imageSrc": "defaultSrc.png"
},
"apiVersion": {
"6": {
"myBackgroundColor": "@sys.color.fa_background"
},
"7": {
"canUseSlider": "true"
"9": {
"imageSrc": "newSrc.webp"
}
}
}
```
JS服务卡片开发框架会根据应用中的配置及当前系统运行版本,选取最合适的数据。
假设系统运行版本在8及以下,则实际解析的imageSrc值为defaultSrc.png;
假设系统运行版本在5及以下,则实际解析的myBackgroundColor值为\#87ceeb,canUseSlider值为false;
假设系统运行版本为6,则实际解析的myBackgroundColor值为\@sys.color.fa_background,canUseSlider值为false;
假设系统运行版本为7及以上,则实际解析的际解析的myBackgroundColor值为\@sys.color.fa_background,canUseSlider值为true。
假设系统运行版本为9,则实际解析的imageSrc值为newSrc.webp。
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册