欢迎进入新手引导小程序!您需要准备的材料包括:
Node
环境, 使用 npm i
或 yarn
安装依赖包。注意:如果开发者工具的运行结果与真机运行结果不一致,请以真机的调试运行结果为准。
❣️ 智能小程序基本 TYML、TYSS、相关语法.
❣️ 智能小程序页面、组件、组合开发。
❣️ 一些 API 的介绍和使用。
❣️ 内置的智能小程序扩展能力补充,包括 主题适配、多语言等。
❣️ 其他扩展能力,包括 组件库、手势库、图表库、动画库等。
app
和 page
两层。app
用来描述整个应用,page
用来描述各个页面。更多信息,请参考
框架概述。
component
将需要复用的功能模块抽象成自定义组件。因而,您可以在不同页面中复用这些组件,还可以将自定义组件发布到 NPM
上,然后在不同小程序中进行复用这些组件。更多信息,请参考 小程序组件。├── project.tuya.json
├── app.js
├── app.json
├── app.tyss
├── assets
│ └── images
│ └── tab
│ └─ component.png
├── i18n
│ └── strings.json
├── components
│ └── foo
│ ├── index.js
│ ├── index.json
│ ├── index.tyml
│ └── index.tyss
├── pages
│ └── page
│ ├── index.js
│ ├── index.json
│ ├── index.tyml
│ └── index.tyss
├── theme.json
├── package.json
└── node_modules
index.less
文件,index.tyss
仅支持
CSS
。Page
的 data
。Mustache
语法(双大括号)将变量包起来,可以作用于内容、组件属性(需要在双引号之内)、控制属性(需要在双引号之内)、关键字(需要在双引号之内)、运算、三元运算、算术运算、逻辑判断、字符串运算等。更多信息,请参考 TYML 语法参考。
<!--tyml-->
<view> {{message}} </view>
// page.js
Page({
data: {
message: "Hello MINA!",
},
});
如不提供 ty:key
,会报一个 warning
。如果已明确是静态列表,或者不必关注其顺序,可以选择忽略。更多信息,请参考 列表渲染。
<!--tyml-->
<view ty:for="{{array}}"> {{item}} </view>
// page.js
Page({
data: {
array: [1, 2, 3, 4, 5],
},
});
更多信息,请参考 条件渲染。
<!--tyml-->
<view ty:if="{{view == 'WEBVIEW'}}"> WEBVIEW </view>
<view ty:elif="{{view == 'APP'}}"> APP </view>
<view ty:else="{{view == 'MINA'}}"> MINA </view>
// page.js
Page({
data: {
view: "MINA",
},
});
更多信息,请查看 模板。
<!--tyml-->
<template name="staffName">
<view>
FirstName: {{firstName}}, LastName: {{lastName}}
</view>
</template>
<template is="staffName" data="{{...staffA}}"></template>
<template is="staffName" data="{{...staffB}}"></template>
<template is="staffName" data="{{...staffC}}"></template>
// page.js
Page({
data: {
staffA: { firstName: "Hulk", lastName: "Hu" },
staffB: { firstName: "Shang", lastName: "You" },
staffC: { firstName: "Gideon", lastName: "Lin" },
},
});
注册小程序。接受一个 Object 参数,其指定小程序的生命周期回调等。
注意:App()
必须在** app.js
中调用,必须调用且只能调用一次。不然会出现无法预期的效果。
onLaunch
:小程序初始化完成时触发,全局只触发一次。onShow
:小程序启动,或从后台进入前台显示时触发。onHide
:小程序从前台进入后台时触发。onError
:小程序发生脚本错误或 API 调用报错时触发。onPageNotFound
:小程序要打开的页面不存在时触发。onThemeChange
:系统切换主题时触发。更多信息,请查看 App。
示例代码
App({
onLaunch(options) {
// Do something initial when launch.
},
onShow(options) {
// Do something when show.
},
onHide() {
// Do something when hide.
},
onError(msg) {
console.log(msg);
},
globalData: "I am global data",
});
你可以在 js
中(page
或 component
)通过 getApp
方法获取到小程序全局唯一的
App
实例。
示例代码
// other.js
var appInstance = getApp();
console.log(appInstance.globalData); // I am global data
注册小程序中的一个页面。接受一个 Object
类型参数,其指定页面的初始数据、生命周期回调、事件处理函数等。更多信息,请查看 Page。
data
是页面第一次渲染使用的 初始数据。
示例代码
<view>{{text}}</view>
<view>{{array[0].msg}}</view>
Page({
data: {
text: "init data",
array: [{ msg: "1" }, { msg: "2" }],
},
});
Page
中可以定义组件事件处理函数。setData
,您可以异步地将数据变更后显示给视图。setData
为异步。示例代码
<view bind:tap="viewTap">{{num}}</view>
Page({
data: {
num: 0,
},
viewTap: function () {
this.setData({
num: this.data.num + 1,
});
},
});
onLoad
:页面加载时触发。一个页面只会调用一次,可以在 onLoad
的参数中获取打开当前页面路径中的参数。onShow
:页面显示/切入前台时触发。onReady
:页面初次渲染完成时触发。一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。onHide
:页面隐藏或切入后台时触发。onUnload
:页面卸载时触发。onPullDownRefresh
:监听用户下拉刷新事件。onReachBottom
:监听用户上拉触底事件。更多信息,请查看 页面事件处理函数。
示例代码
//index.js
Page({
data: {
text: "This is page data.",
},
onLoad: function (options) {
// Do some initialize when page load.
},
onShow: function () {
// Do something when page show.
},
onReady: function () {
// Do something when page ready.
},
onHide: function () {
// Do something when page hide.
},
onUnload: function () {
// Do something when page close.
},
onPullDownRefresh: function () {
// Do something when pull down.
},
onReachBottom: function () {
// Do something when page reach bottom.
},
});
创建自定义组件,接受一个 Object
类型的参数,用于描述组件的逻辑交互行为。更多信息,请查看 Component。
// 文件 /components/foo/index.js
Component({
options: Object,
properties: Object,
observers: Object,
data: Object,
methods: Object,
behaviors: Array,
lifetimes: Object,
pageLifetimes: Object,
relations: Array,
});
type
定义属性值的类型。更多信息,请查看 properties。properties
可通过 observer()
监听属性值的变化。示例代码
Component({
properties: {
myName: {
type: String,
value: "smart",
observer: function (newValue, oldValue) {
// do something
},
},
},
});
properties
)和数据(data
)字段的变化。更多信息,请查看 observers。 注意:如果在数据监听器函数中使用 setData
设置本身监听的数据字段,可能会导致死循环。Component({
observers: {
"value1, value2": function (value1, value2) {
// this.setData 对应数据时触发
},
"some.subfield": function (subfield) {
// 使用 setData 设置 this.data.some.subfield 时触发
// (除此以外,使用 setData 设置 this.data.some 也会触发)
subfield === this.data.some.subfield;
},
"arr[12]": function (arr12) {
// 使用 setData 设置 this.data.arr[12] 时触发
// (除此以外,使用 setData 设置 this.data.arr 也会触发)
arr12 === this.data.arr[12];
},
"some.field.**": function (field) {
// 使用 setData 设置 this.data.some.field 本身或其下任何子数据字段时触发
// (除此以外,使用 setData 设置 this.data.some 也会触发)
field === this.data.some.field;
},
"**": function () {
// 每次 setData 都触发
},
},
});
page
的数据对象。properties
共同用于组件模板的渲染。<view>{{name}}: {{age}}</view>
Component({
properties: {
'name': {
type: String,
value: 'smart'
}
}
data: { age: 18 },
});
created
:在组件实例刚刚被创建时执行。attached
:在组件实例进入页面节点树时执行。ready
:在组件在视图层布局完成后执行。moved
:在组件实例被移动到节点树另一个位置时执行。detached
:在组件实例被从页面节点树移除时执行。error
:每当组件方法抛出错误时执行。示例代码
Component({
lifetimes: {
attached: function () {
// 在组件实例进入页面节点树时执行
},
},
});
show
:组件所在的页面被展示时执行。hide
:组件所在的页面被隐藏时执行。resize
:组件所在的页面尺寸变化时执行。示例代码
Component({
pageLifetimes: {
show: function () {
// 组件所在的页面被展示时执行
},
},
});
组件间的常用通信方式包括以下 2 种方式:
TYML
数据绑定:用于父组件向子组件的指定属性设置数据,仅能设置 JSON 兼容数据。示例代码
<!-- 当自定义组件触发"myevent"事件时,调用"onMyEvent"方法 -->
<component-tag-name bind:myevent="onMyEvent" />
Page({
onMyEvent: function (e) {
e.detail; // 自定义组件触发事件时提供的detail对象
},
});
自定义组件触发事件时,需要使用 triggerEvent
方法,指定事件名、detail
对象和事件选项。
示例代码
<!-- 在自定义组件中 -->
<button bind:tap="onTap">点击这个按钮将触发"myevent"事件</button>
Component({
properties: {},
methods: {
onTap: function () {
var myEventDetail = {}; // detail 对象,提供给事件监听函数
var myEventOption = {}; // 触发事件的选项
this.triggerEvent("myevent", myEventDetail, myEventOption);
},
},
});
tyml
中可以包含 slot
节点,用于承载组件使用者提供的 tyml
结构。tyml
中支持有一个或者多个 slot
。tyml
中使用多个 slot
时,以不同的 name
来区分。使用时,用 slot
属性来将节点插入到不同的 slot
上。示例代码
<!-- 组件模板 -->
<view class="wrapper">
<slot name="before"></slot>
<view>这里是组件的内部细节</view>
<slot name="after"></slot>
</view>
<!-- 引用组件的页面模板 -->
<view>
<component-tag-name>
<!-- 这部分内容将被放置在组件 <slot name="before"> 的位置上 -->
<view slot="before">这里是插入到组件slot name="before"中的内容</view>
<!-- 这部分内容将被放置在组件 <slot name="after"> 的位置上 -->
<view slot="after">这里是插入到组件slot name="after"中的内容</view>
</component-tag-name>
</view>
默认情况下,自定义组件的样式只受到自定义组件 tyss
的影响。以下两种情况例外:
app.tyss
或页面的 tyss
中使用了标签名选择器(或一些其他特殊选择器)来直接指定样式。这些选择器会影响到页面和全部组件。通常情况下,这是不推荐的做法。
styleIsolation
。iconfont
时,由于 iconfont
的样式文件是全局。因此,在自定义组件中需要使用 iconfont
时,应关闭样式隔离。示例代码
Component({
options: {
styleIsolation: "isolated",
},
});
isolated
:启用样式隔离(默认值)。apply-shared
:页面 tyss
样式将影响到自定义组件,但自定义组件 tyss
中指定的样式不会影响页面。shared
:页面 tyss
样式将影响到自定义组件,自定义组件 tyss
中指定的样式也会影响页面和其他设置。示例代码
<!-- 组件 custom-component.tyml -->
<text class="red-text">这段文本的颜色由 `app.tyss` 和页面 `tyss` 中的样式定义来决定</text>
/* app.tyss */
.red-text {
color: red;
}
/* 组件 custom-component.js */
Component({
options: {
addGlobalClass: true,
},
});
url
应为绝对路径。ty.navigateTo
。<navigator open-type="navigateTo"/>
ty.redirectTo
。<navigator open-type="redirectTo"/>
ty.navigateBack
。<navigator open-type="navigateBack"/>
ty.switchTab
。<navigator open-type="switchTab"/>
ty.reLaunch
。<navigator open-type="reLaunch"/>
参数拼接:直接在路由url
后进行参数拼接,参数可以在生命周期中获得。
示例代码
ty.navigateTo({
url: 'test?id=1',
events: {
// 为指定事件添加一个监听器,获取被打开页面传送到当前页面的数据
acceptDataFromOpenedPage: function(data) {
console.log(data)
},
someEvent: function(data) {
console.log(data)
}
...
},
success: function(res) {
// 通过eventChannel向被打开页面传送数据
res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'test' })
}
})
//test.js
Page({
onLoad: function (option) {
console.log(option.query);
const eventChannel = this.getOpenerEventChannel();
eventChannel.emit("acceptDataFromOpenedPage", { data: "test" });
eventChannel.emit("someEvent", { data: "test" });
// 监听acceptDataFromOpenerPage事件,获取上一页面通过eventChannel传送到当前页面的数据
eventChannel.on("acceptDataFromOpenerPage", function (data) {
console.log(data);
});
},
});
基础库提供的 API,包括基础或应用级事件、界面动画相关、地图、音视频、画布、界面等能力。
App
必须集成的最小公共能力集合,这些能力通过插件方式提供给小程序、RN
、H5
等,让跨端业务可以跑在任意涂鸦系 App(IoT
设备)上。注意:使用一些 API,比如 navigateTo
,showToast
,showModal
,需要集成对应的 Kit 插件能力。
小程序资源存放目录为 /assets
。常用来存放资源图片、iconfont
、utils
等。
智能小程序多语言已经集成进框架,不需要额外引入包或者方法。
多语言的 key 值需要在 小程序开发者平台 中进行添加,选择对应的小程序后,单击侧边栏 多语言管理。
<text>{{I18n.t('TYTimer_day2')}}</text>
<text>{{i18n.t('TYTimer_day2')}}</text>
console.log(I18n.t("TYTimer_day2"));
console.log(i18n.t("TYTimer_day2"));
tyss/less
中,支持通过选择器 theme='dark' | 'light'
去切换主题。css变量
自动管理主题变量。示例代码
:root {
--main-bg-color: rgb(255, 255, 255); /* 浅色背景 */
--main-text-color: rgb(54, 54, 54); /* 深色文字 */
}
:root[theme="dark"] {
--main-bg-color: rgb(47, 58, 68); /* 深色背景 */
--main-text-color: rgb(197, 197, 197); /* 浅色文字 */
}
Dialog
、Loading
、Tabs
、Cell
等。npm
方式下载构建,npm
包名为 @tuya-miniapp/miniapp-components-plus
。json
文件加入 usingComponents
配置字段,usingComponents
必须是完整的路径。tyml
中直接使用该组件。示例代码
// index.json
"usingComponents": {
"mpdialog": "@tuya-miniapp/miniapp-components-plus/dialog/index"
}
<mpdialog title="test" show="{{true}}"
bind:buttontap="tapDialogButton" buttons="{{[{text: '取消'}, {text: '确认'}]}}">
<view>test content</view>
</mpdialog>
form
包裹在最外层,添加 bind:submit
和 bind:reset
属性。
属性名 |
类型 |
默认值 |
必填 |
说明 |
bind:submit |
eventhandle |
- |
否 |
携带 form 中的数据触发 submit 事件,event.detail 中可以取到 name 对应表单项的值 |
bind:reset |
eventhandle |
- |
否 |
表单重置时会触发 reset 事件 |
示例代码
<form bind:submit="handleSubmit"
bind:reset="handleReset">
<switch name="switch"></switch>
<button form-type="submit" data-info="提交的按钮" type="primary" class="submit-btn">提交</button>
<button form-type="reset" data-info="reset的按钮" class="reset-btn">重置</button>
</form>
Page({
data: {
resultData: [
{
name: "switch",
value: "",
},
],
},
handleSubmit(ev) {
const value = ev.detail.value;
console.log(value);
},
handleReset(ev) {
const value = ev.detail.value;
console.log(value);
},
});
涂鸦提供若干模板,供开发者进行学习。
智能小程序官方 Demo: 包含基础组件、扩展组件、API 的使用示例。您可以调试运行这些示例,帮助学习。