#项目组织
#文件组织形式
以下文件组织规范为最佳实践的建议
所有项目源代码请放在项目根目录 src
目录下,项目所需最基本的文件包括 入口文件 以及 页面文件
- 入口文件为
app.js
- 页面文件建议放置在
src/pages
目录下
一个可靠的 Taro 项目可以按照如下方式进行组织
├── config 配置目录
| ├── dev.js 开发时配置
| ├── index.js 默认配置
| └── prod.js 打包时配置
├── src 源码目录
| ├── components 公共组件目录
| ├── pages 页面文件目录
| | ├── index index 页面目录
| | | ├── banner 页面 index 私有组件
| | | ├── index.js index 页面逻辑
| | | └── index.css index 页面样式
| ├── utils 公共方法库
| ├── app.css 项目总通用样式
| └── app.js 项目入口文件
└── package.json
#文件命名
Taro 中普通 JS/TS 文件以小写字母命名,多个单词以下划线连接,例如 util.js
、util_helper.js
Taro 组件文件命名遵循 Pascal 命名法,例如 ReservationCard.jsx
#文件后缀
Taro 中普通 JS/TS 文件以 .js
或者 .ts
作为文件后缀
Taro 组件则以 .jsx
或者 .tsx
作为文件后缀,当然这不是强制约束,只是作为一个实践的建议,组件文件依然可以以 .js
或者 .ts
作为文件后缀
#JavaScript 书写规范
在 Taro 中书写 JavaScript 请遵循以下规则
#基本书写
#使用两个空格进行缩进
不要混合使用空格与制表符作为缩进
function hello (name) {
console.log('hi', name)
console.log('hello', name)
}
#除了缩进,不要使用多个空格
const id = 1234
const id = 1234
#不要在句末使用分号
const a = 'a'
const a = 'a';
#字符串统一使用单引号
console.log('hello there')
const x = 'hello "world"'
const y = 'hello \'world\''
const z = `hello 'world'`
#代码块中避免多余留白
if (user) {
const name = getName()
}
if (user) {
const name = getName()
}
#关键字后面加空格
if (condition) { ... }
if(condition) { ... }
#函数声明时括号与函数名间加空格
function name (arg) { ... }
function name(arg) { ... }
run(function () { ... })
run(function() { ... })
#展开运算符与它的表达式间不要留空白
#遇到分号时空格要后留前不留
for (let i = 0 ;i < items.length ;i++) {...}
for (let i = 0; i < items.length; i++) {...}
#代码块首尾留空格
if (admin){...}
if (admin) {...}
#圆括号间不留空格
getName( name )
getName(name)
#属性前面不要加空格
#一元运算符前面跟一个空格
typeof!admin
typeof !admin
#注释首尾留空格
#模板字符串中变量前后不加空格
const message = `Hello, ${ name }`
const message = `Hello, ${name}`
#逗号后面加空格
const list = [1, 2, 3, 4]
function greet (name, options) { ... }
const list = [1,2,3,4]
function greet (name,options) { ... }
#不允许有连续多行空行
const value = 'hello world'
console.log(value)
const value = 'hello world'
console.log(value)
#单行代码块两边加空格
function foo () {return true}
function foo () { return true }
if (condition) { return true }
#不要使用非法的空白符
#始终将逗号置于行末
const obj = {
foo: 'foo'
,bar: 'bar'
}
const obj = {
foo: 'foo',
bar: 'bar'
}
#点号操作符须与属性需在同一行
console.log('hello')
console.
log('hello')
console
.log('hello')
#文件末尾留一空行
#函数调用时标识符与括号间不留间隔
console.log ('hello')
console.log('hello')
#键值对当中冒号与值之间要留空白
const obj = { 'key' : 'value' }
const obj = { 'key' :'value' }
const obj = { 'key':'value' }
const obj = { 'key': 'value' }
#变量定义
#使用 const/let 定义变量
当前作用域不需要改变的变量使用 const
,反之则使用 let
const a = 'a'
a = 'b'
let test = 'test'
var noVar = 'hello, world'
#每个 const/let 关键字单独声明一个变量
const silent = true
let verbose = true
const silent = true, verbose = true
let silent = true,
verbose = true
#不要重复声明变量
let name = 'John'
let name = 'Jane'
let name = 'John'
name = 'Jane'
#不要使用 undefined 来初始化变量
let name = undefined
let name
name = 'value'
#对于变量和函数名统一使用驼峰命名法
function my_function () { }
function myFunction () { }
const my_var = 'hello'
const myVar = 'hello'
#不要定义未使用的变量
function myFunction () {
const result = something()
}
#避免将变量赋值给自己
#基本类型
#不要省去小数点前面的 0
const discount = .5
const discount = 0.5
#字符串拼接操作符 (Infix operators) 之间要留空格
const x = 2
const message = 'hello, ' + name + '!'
const x=2
const message = 'hello, '+name+'!'
#不要使用多行字符串
const message = 'Hello \
world'
#检查 NaN 的正确姿势是使用 isNaN()
if (price === NaN) { }
if (isNaN(price)) { }
#用合法的字符串跟 typeof 进行比较操作
typeof name === undefined
typeof name === 'undefined'
#对象与数组
#对象中定义了存值器,一定要对应的定义取值器
const person = {
set name (value) {
this._name = value
}
}
const person = {
set name (value) {
this._name = value
},
get name () {
return this._name
}
}
#使用数组字面量而不是构造器
const nums = new Array(1, 2, 3)
const nums = [1, 2, 3]
#不要解构空值
const { a: {} } = foo
const { a: { b } } = foo
#对象字面量中不要定义重复的属性
const user = {
name: 'Jane Doe',
name: 'John Doe'
}
#不要扩展原生对象
Object.prototype.age = 21
#外部变量不要与对象属性重名
let score = 100
function game () {
score: while (true) {
score -= 10
if (score > 0) continue score
break
}
}
#对象属性换行时注意统一代码风格
const user = {
name: 'Jane Doe', age: 30,
username: 'jdoe86'
}
const user = { name: 'Jane Doe', age: 30, username: 'jdoe86' }
const user = {
name: 'Jane Doe',
age: 30,
username: 'jdoe86'
}
#避免使用不必要的计算值作对象属性
const user = { ['name']: 'John Doe' }
const user = { name: 'John Doe' }
#避免使用 arguments.callee 和 arguments.caller
function foo (n) {
if (n <= 0) return
arguments.callee(n - 1)
}
function foo (n) {
if (n <= 0) return
foo(n - 1)
}
#不要定义冗余的函数参数
function sum (a, b, a) {
}
function sum (a, b, c) {
}
#避免多余的函数上下文绑定
const name = function () {
getName()
}.bind(user)
const name = function () {
this.getName()
}.bind(user)
#不要使用 eval()
eval( "var result = user." + propName )
const result = user[propName]
#不要使用多余的括号包裹函数
const myFunc = (function () { })
const myFunc = function () { }
#避免对声明过的函数重新赋值
function myFunc () { }
myFunc = myOtherFunc
#注意隐式的 eval()
setTimeout("alert('Hello world')")
setTimeout(function () { alert('Hello world') })
#嵌套的代码块中禁止再定义函数
if (authenticated) {
function setAuthUser () {}
}
#禁止使用 Function 构造器
const sum = new Function('a', 'b', 'return a + b')
#禁止使用 Object 构造器
let config = new Object()
#自调用匿名函数 (IIFEs) 使用括号包裹
const getName = function () { }()
const getName = (function () { }())
const getName = (function () { })()
#不使用 Generator 函数语法
使用 Promise
或者 async functions
来实现异步编程
function* helloWorldGenerator() {
yield 'hello';
yield 'world';
return 'ending';
}
#正则中不要使用控制符
const pattern = /\x1f/
const pattern = /\x20/
#正则中避免使用多个空格
const regexp = /test value/
const regexp = /test {3}value/
const regexp = /test value/
#类定义
#类名要以大写字母开头
class animal {}
const dog = new animal()
class Animal {}
const dog = new Animal()
#避免对类名重新赋值
#子类的构造器中一定要调用 super
class Dog {
constructor () {
super()
}
}
class Dog extends Mammal {
constructor () {
super()
}
}
#使用 this 前请确保 super() 已调用
class Dog extends Animal {
constructor () {
this.legs = 4
super()
}
}
#禁止多余的构造器
class Car {
constructor () {
}
}
class Car {
constructor () {
super()
}
}
#类中不要定义冗余的属性
class Dog {
bark () {}
bark () {}
}
#无参的构造函数调用时要带上括号
function Animal () {}
const dog = new Animal
const dog = new Animal()
#new 创建对象实例后需要赋值给变量
new Character()
const character = new Character()
#同一模块有多个导入时一次性写完
import { myFunc1 } from 'module'
import { myFunc2 } from 'module'
import { myFunc1, myFunc2 } from 'module'
#import, export 和解构操作中,禁止赋值到同名变量
import { config as config } from './config'
import { config } from './config'
#避免在 return 语句中出现赋值语句
function sum (a, b) {
return result = a + b
}
#禁止使用 with
#不要使用标签语句
label:
while (true) {
break label
}
#不要随意更改关键字的值
#return,throw,continue 和 break 后不要再跟代码
function doSomething () {
return true
console.log('never called')
}
#逻辑与循环
#始终使用 === 替代 ==
例外: obj == null 可以用来检查 null || undefined
if (name === 'John')
if (name == 'John')
if (name !== 'John')
if (name != 'John')
#避免将变量与自己进行比较操作
#if/else 关键字要与花括号保持在同一行
if (condition) {
} else {
}
#多行 if 语句的的括号不能省略
if (options.quiet !== true) console.log('done')
if (options.quiet !== true) {
console.log('done')
}
if (options.quiet !== true)
console.log('done')
#对于三元运算符 ? 和 : 与他们所负责的代码处于同一行
const location = env.development ? 'localhost' : 'www.api.com'
const location = env.development
? 'localhost'
: 'www.api.com'
const location = env.development ?
'localhost' :
'www.api.com'
#请书写优雅的条件语句(avoid Yoda conditions)
if (42 === age) { }
if (age === 42) { }
#避免使用常量作为条件表达式的条件(循环语句除外)
if (false) {
}
if (x === 0) {
}
while (true) {
}
#循环语句中注意更新循环变量
for (let i = 0; i < items.length; j++) {...}
for (let i = 0; i < items.length; i++) {...}
#如果有更好的实现,尽量不要使用三元表达式
let score = val ? val : 0
let score = val || 0
#switch 语句中不要定义重复的 case 分支
switch (id) {
case 1:
case 1:
}
#switch 一定要使用 break 来将条件分支正常中断
switch (filter) {
case 1:
doSomething()
case 2:
doSomethingElse()
}
switch (filter) {
case 1:
doSomething()
break
case 2:
doSomethingElse()
}
switch (filter) {
case 1:
doSomething()
case 2:
doSomethingElse()
}
#避免不必要的布尔转换
const result = true
if (!!result) {
}
const result = true
if (result) {
}
#避免使用逗号操作符
if (doSomething(), !!test) {}
#错误处理
#不要丢掉异常处理中 err 参数
run(function (err) {
if (err) throw err
window.alert('done')
})
run(function (err) {
window.alert('done')
})
#catch 中不要对错误重新赋值
try {
} catch (e) {
e = 'new value'
}
try {
} catch (e) {
const newVal = 'new value'
}
#用 throw 抛错时,抛出 Error 对象而不是字符串
throw 'error'
throw new Error('error')
#finally 代码块中不要再改变程序执行流程
try {
} catch (e) {
} finally {
return 42
}
#使用 Promise 一定要捕捉错误
asyncTask('google.com').catch(err => console.log(err))
#组件及 JSX 书写规范
#基本书写
#组件创建
Taro 中组件以类的形式进行创建,并且单个文件中只能存在单个组件
#代码缩进
使用两个空格进行缩进,不要混合使用空格与制表符作为缩进
import Taro, { Component } from '@tarojs/taro'
import { View, Text } from '@tarojs/components'
class MyComponent extends Component {
render () {
return (
<View className='test'>
<Text>12</Text>
</View>
)
}
}
#单引号
JSX 属性均使用单引号
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
render () {
return (
<View className='test'>
<Text className="test_text">12</Text>
</View>
)
}
}
#对齐方式
多个属性,多行书写,每个属性占用一行,标签结束另起一行
<Foo superLongParam='bar'
anotherSuperLongParam='baz' />
<Foo
superLongParam='bar'
anotherSuperLongParam='baz'
/>
<Foo bar='bar' />
<Foo
superLongParam='bar'
anotherSuperLongParam='baz'
>
<Quux />
</Foo>
#空格使用
终始在自闭合标签前面添加一个空格
<Foo/>
<Foo />
<Foo
/>
<Foo />
#属性书写
属性名称始终使用驼峰命名法
<Foo
UserName='hello'
phone_number={12345678}
/>
<Foo
userName='hello'
phoneNumber={12345678}
/>
#JSX 与括号
用括号包裹多行 JSX 标签
render () {
return <MyComponent className='long body' foo='bar'>
<MyChild />
</MyComponent>
}
render () {
return (
<MyComponent className='long body' foo='bar'>
<MyChild />
</MyComponent>
)
}
render () {
const body = <div>hello</div>
return <MyComponent>{body}</MyComponent>
}
当标签没有子元素时,始终使用自闭合标签
<Foo className='stuff'></Foo>
<Foo className='stuff' />
如果控件有多行属性,关闭标签要另起一行
<Foo
bar='bar'
baz='baz' />
<Foo
bar='bar'
baz='baz'
/>
#书写顺序
在 Taro 组件中会包含类静态属性、类属性、生命周期等的类成员,其书写顺序最好遵循以下约定(顺序从上至下)
- static 静态方法
- constructor
- componentWillMount
- componentDidMount
- componentWillReceiveProps
- shouldComponentUpdate
- componentWillUpdate
- componentDidUpdate
- componentWillUnmount
- 点击回调或者事件回调 比如
onClickSubmit()
或者 onChangeDescription()
- render
#通用约束与建议
#所有内置组件均需要引入后再使用
import Taro, { Component } from '@tarojs/taro'
import { View } from '@tarojs/components'
class MyComponent extends Component {
render () {
return (
<View className='test'>
<Text>12</Text>
</View>
)
}
}
#推荐使用对象解构的方式来使用 state、props
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
state = {
myTime: 12
}
render () {
const { isEnable } = this.props
const { myTime } = this.state
return (
<View className='test'>
{isEnable && <Text className='test_text'>{myTime}</Text>}
</View>
)
}
}
#不要以 class/id/style 作为自定义组件的属性名
<Hello class='foo' />
<Hello id='foo' />
<Hello style='foo' />
#不要使用 HTML 标签
<div className='foo'></div>
<span id='foo' /></span>
#不要在调用 this.setState 时使用 this.state
由于 this.setState 异步的缘故,这样的做法会导致一些错误,可以通过给 this.setState 传入函数来避免
this.setState({
value: this.state.value + 1
})
this.setState(prevState => ({ value: prevState.value + 1 }))
#map 循环时请给元素加上 key 属性
list.map(item => {
return (
<View className='list_item' key={item.id}>{item.name}</View>
)
})
#尽量避免在 componentDidMount 中调用 this.setState
因为在 componentDidMount
中调用 this.setState
会导致触发更新
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
state = {
myTime: 12
}
componentDidMount () {
this.setState({
name: 1
})
}
render () {
const { isEnable } = this.props
const { myTime } = this.state
return (
<View className='test'>
{isEnable && <Text className='test_text'>{myTime}</Text>}
</View>
)
}
}
#不要在 componentWillUpdate/componentDidUpdate/render 中调用 this.setState
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
state = {
myTime: 12
}
componentWillUpdate () {
this.setState({
name: 1
})
}
componentDidUpdate () {
this.setState({
name: 1
})
}
render () {
const { isEnable } = this.props
const { myTime } = this.state
this.setState({
name: 11
})
return (
<View className='test'>
{isEnable && <Text className='test_text'>{myTime}</Text>}
</View>
)
}
}
#不要定义没有用到的 state
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
state = {
myTime: 12,
noUsed: true
}
render () {
const { myTime } = this.state
return (
<View className='test'>
<Text className='test_text'>{myTime}</Text>
</View>
)
}
}
#组件最好定义 defaultProps
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
static defaultProps = {
isEnable: true
}
state = {
myTime: 12
}
render () {
const { isEnable } = this.props
const { myTime } = this.state
return (
<View className='test'>
{isEnable && <Text className='test_text'>{myTime}</Text>}
</View>
)
}
}
#render 方法必须有返回值
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
state = {
myTime: 12
}
render () {
const { isEnable } = this.props
const { myTime } = this.state
<View className='test'>
{isEnable && <Text className="test_text">{myTime}</Text>}
</View>
}
}
#值为 true 的属性可以省略书写值
<Hello personal />
<Hello personal={false} />
#JSX 属性或者表达式书写时需要注意空格
属性书写不带空格,如果属性是一个对象,则对象括号旁边需要带上空格
<Hello name={ firstname } />
<Hello name={ firstname} />
<Hello name={firstname } />
<Hello name={{ firstname: 'John', lastname: 'Doe' }} />
#事件绑定均以 on 开头
在 Taro 中所有默认事件如 onClick
、onTouchStart
等等,均以 on
开头
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
class MyComponent extends Component {
state = {
myTime: 12
}
clickHandler (e) {
console.log(e)
}
render () {
const { myTime } = this.state
return (
<View className='test' onClick={this.clickHandler}>
<Text className='test_text'>{myTime}</Text>
</View>
)
}
}
#子组件传入函数时属性名需要以 on 开头
import Taro, { Component } from '@tarojs/taro'
import { View, Input } from '@tarojs/components'
import Tab from '../../components/Tab/Tab'
class MyComponent extends Component {
state = {
myTime: 12
}
clickHandler (e) {
console.log(e)
}
render () {
const { myTime } = this.state
return (
<View className='test'>
<Tab onChange={this.clickHandler} />
<Text className='test_text'>{myTime}</Text>
</View>
)
}
}
#Taro 自身限制规范
#不能使用 Array#map 之外的方法操作 JSX 数组
Taro 在小程序端实际上把 JSX 转换成了字符串模板,而一个原生 JSX 表达式实际上是一个 React/Nerv 元素(react-element)的构造器,因此在原生 JSX 中你可以随意地对一组 React 元素进行操作。但在 Taro 中你只能使用 map
方法,Taro 转换成小程序中 wx:for
以下代码会被 ESLint 提示警告,同时在 Taro(小程序端)也不会有效:
test.push(<View />)
numbers.forEach(number => {
if (someCase) {
a = <View />
}
})
test.shift(<View />)
components.find(component => {
return component === <View />
})
components.some(component => component.constructor.__proto__ === <View />.constructor)
以下代码不会被警告,也应当在 Taro 任意端中能够运行:
numbers.filter(Boolean).map((number) => {
const element = <View />
return <View />
})
解决方案
先处理好需要遍历的数组,然后再用处理好的数组调用 map
方法。
numbers.filter(isOdd).map((number) => <View />)
for (let index = 0; index < array.length; index++) {
}
const element = array.map(item => {
return <View />
})