每周总结 函数方法注释规范/jQuery深拷贝/js补全函数/Vue文档学习

js代码规范

注释规范

函数说明注释：在函数声明上方键入 /** ,再按回车键：

/**
* @function 处理表格的行
* @description 合并Grid的行
* @param grid {Ext.Grid.Panel} 需要合并的Grid
* @param cols {Array} 需要合并列的Index(序号)数组；从0开始计数，序号也包含。
* @param isAllSome {Boolean} ：是否2个tr的cols必须完成一样才能进行合并。true：完成一样；false(默认)：不完全一样
* @return void
* @author polk6 2015/07/21 
* @example
* _________________ _________________
* | 年龄 | 姓名 | | 年龄 | 姓名 |
* ----------------- mergeCells(grid,[0]) -----------------
* | 18 | 张三 | => | | 张三 |
* ----------------- - 18 ---------
* | 18 | 王五 | | | 王五 |
* ----------------- -----------------
*/
function mergeCells(grid: Ext.Grid.Panel, cols: Number[], isAllSome: boolean = false) {
  // Do Something
}

javadoc参数说明：

• @see 生成文档中的“参见xx 的条目”的超链接，后边可以加上：“类名”、“完整类名”、“完整类名#方法”。可用于：类、方法、变量注释。

• @param 参数的说明。可用于：方法注释。

• @return 返回值的说明。可用于：方法注释。

• @exception 可能抛出异常的说明。可用于：方法注释。

• @version 版本信息。可用于：类注释。

• @author 作者名。可用于：类注释。

• @deprecated 对类或方法的说明 该类或方法不建议使用,引起不推荐使用的警告

• @note 表示注解，暴露给源码阅读者的文档

• @remark 表示评论，暴露给客户程序员的文档

• @since 表示从那个版本起开始有了这个函数

• @see 表示交叉参考

jQuery

jQuery深拷贝

jQuery.extend( [deep ], target, object1 [, objectN ] )

$.extend(true, obj1, obj2) 将 obj2 的对象属性深拷贝给 obj1

js

substring() 与 substr() 的主要区别

substring() 方法的参数表示起始和结束索引，substr() 方法的参数表示起始索引和要包含在生成的字符串中的字符的长度,示例如下：

vartext = 'Mozilla';
console.log(text.substring(2,5)); // => "zil"console.log(text.substr(2,3)); // => "zil"

关于 padStart

padStart 可以在字符串的开头进行字符补全。
语法如下：

str.padStart(targetLength [, padString])

其中：

• targetLength （可选）

targetLength 指目标字符串长度。然后，根据我的测试，targetLength 参数缺省也不会报错，原本的字符串原封不动返回，不过代码没有任何意义，因此，基本上没有使用的理由。

还有，targetLength 参数的类型可以是数值类型或者弱数值类型。在JavaScript中，1 == '1' ，1 是数值，'1' 虽然本质上是字符串，但也可以看成是弱数值。在 padStart() 方法中，数值类型或者弱数值类型都是可以。例如：
js 'zhangxinxu'.padStart('5');
因此，我们实际使用的时候，没必要对targetLength参数进行强制的类型转换。

最后，如果 targetLength 设置的长度比字符串本身还要小，则原本的字符串原封不动返回，例如：

'zhangxinxu'.padStart(5);    
// 结果还是'zhangxinxu'

• padString （可选）
  padString 表示用来补全长度的字符串。然而，虽然语义上是字符串，但是根据我的测试，任意类型的值都是可以的。无论是Chrome浏览器还是Firefox浏览器，都会尝试将这个参数转换成字符串进行补全。例如下面几个例子：

	'zhangxinxu'.padStart(15, false);
// 结果是'falsezhangxinxu'
	'zhangxinxu'.padStart(15, null);
// 结果是'nullnzhangxinxu'
	'zhangxinxu'.padStart(15, []);
// 结果是'zhangxinxu'，因为[]转换成字符串是空字符串
	'zhangxinxu'.padStart(15, {});
// 结果是'[objezhangxinxu'，只显示了'[object Object]'前5个字符

padString 参数默认值是普通空格' '（U+0020），也就是敲Space空格键出现的空格。

从上面几个案例可以看出，如果补全字符串长度不足，则不断循环补全；如果长度超出，则从左侧开始依次补全，没有补到的字符串直接就忽略。
此方法返回值是补全后的字符串。

常用缩写

diff $\to$ 比较

patch $\to$ 修改/补丁

vue命令的缩写或简写

v-on $\to$ @

v-bind $\to$ :

v-slot $\to$ #

Vue文档学习

可复用&组合

混入

我们可以预先设定一套或多套组件设置，可以任意组件选项：data，method，watch，钩子函数等等。如果任何组件想要使用某一套设置，就可以通过mixins选项来将它包含进来，为自己所用。我们称这套设置（对象）为混入对象。

// define a mixin object
const myMixin = {
  created() {
    this.hello()
  },
  methods: {
    hello() {
      console.log('hello from mixin!')
    }
  }
}

// define an app that uses this mixin
const app = Vue.createApp({
  mixins: [myMixin]
})

app.mount('#mixins-basic') // => "hello from mixin!"

如果混入对象的某一选项名与组件相同，则使用组件的选项。不过也可以自定义合并函数。

缺点：混入对象一旦定义就不能修改，缺少灵活性。在Vue3中可以使用组合式API来解决。

自定义指令

除了v-on、v-bind、v-slot外，Vue支持自定义指令，方便我们操作DOM元素。在组件的directives选项中可以自定义指令。注意在mounted的参数el是DOM元素而不是jquery元素。

全局注册指令

const app = Vue.createApp({})
// 注册一个全局自定义指令 `v-focus`
app.directive('focus', {
  // 当被绑定的元素插入到 DOM 中时……
  mounted(el) {
    // Focus the element
    el.focus()
  }
})

局部注册指令

directives: {
  focus: {
    // 指令的定义
    mounted(el) {
      el.focus()
    }
  }
}

使用自定义指令，该指令使元素自动聚焦。

<input v-focus />

在上面的例子中，我们使用了mounted的钩子函数，实际上，在一个指令定义对象还可以提供如下几个钩子函数：

• beforeMount：当指令第一次绑定到元素并且在挂载父组件之前调用。在这里你可以做一次性的初始化设置。
• mounted：在挂载绑定元素的父组件时调用。
• beforeUpdate：在更新包含组件的 VNode 之前调用。
• updated：在包含组件的VNode及其子组件的VNode更新后调用。
• beforeUnmount：在卸载绑定元素的父组件之前调用
• unmounted：当指令与元素解除绑定且父组件已卸载时，只调用一次。

除此之外，钩子函数还可以设置动态参数，在模板中以v-mydirective:[argument]="value"形式使用，argument为键，value为值。

<div id="dynamicexample">
  <h3>Scroll down inside this section ↓</h3>
  <p v-pin:[direction]="200">I am pinned onto the page at 200px to the left.</p>
</div>

const app = Vue.createApp({
  data() {
    return {
      direction: 'right'
    }
  }
})

app.directive('pin', {
  mounted(el, binding) {
    el.style.position = 'fixed'
    // binding.arg is an argument we pass to directive
    const s = binding.arg || 'top'
    el.style[s] = binding.value + 'px'
  }
})

app.mount('#dynamic-arguments-example')

如果自定义指令只关注mounted和updated两个钩子函数且内容一样，可以使用箭头函数简写。

app.directive('pin', (el, binding) => {
  el.style.position = 'fixed'
  const s = binding.arg || 'top'
  el.style[s] = binding.value + 'px'
})

注意

在具有多个根节点上使用自定义指令时可能出现问题，这与渲染函数有关，笔者不太了解，具体可查阅文档：自定义指令 | Vue3中文文档。

Teleport | 传送

在我们定义组件的模板的时候，有时候需要模板上的一部分逻辑上属于模板，但是页面上呈现出来的效果不像镶嵌在组件中。比如点击出现一个全屏信息，这需要我们把这一部分传送到合适的DOM节点下，在Vue中我们使用<teleport>标签来传送到父组件中的DOM节点。

app.component('modal-button', {
  template: `
    <button @click="modalOpen = true">
        Open full screen modal! (With teleport!)
    </button>

    <teleport to="body">
      <div v-if="modalOpen" class="modal">
        <div>
          I'm a teleported modal! 
          (My parent is "body")
          <button @click="modalOpen = false">
            Close
          </button>
        </div>
      </div>
    </teleport>
  `,
  data() {
    return { 
      modalOpen: false
    }
  }
})

渲染函数 h()

内容较多，此文章介绍的比Vue中文文档清楚一点 Vue render函数 | 简书 。

简单总结以下，渲染函数是Vue中模板等编译为DOM元素的函数。

Vue在渲染过程中，有三种渲染模式：自定义render函数、<template>模板、el均可以渲染页面，对应三种写法如下：

自定义render函数

Vue.component('anchored-heading', {
    render: function (createElement) {
        return createElement (
            'h' + this.level,   // tag name标签名称
            this.$slots.default // 子组件中的阵列
        )
    },
    props: {
        level: {
            type: Number,
            required: true
        }
    }
})

template写法

let app = new Vue({
    template: `<div>{{ msg }}</div>`,
    data () {
        return {
            msg: ''
        }
    }
})

el写法

let app = new Vue({
    el: '#app',
    data () {
        return {
            msg: 'Hello Vue!'
        }
    }
})

而这三种渲染模式最终都是要得到render函数。

接下来讲一下render函数的三个参数：

1. （必选）标签tag，类型可以是{String | Object | Function}三种之一；

<div id="app">
    <custom-element></custom-element>
</div>

Vue.component('custom-element', {
    render: function (createElement) {
        return createElement('div')
    }
})

let app = new Vue({
    el: '#app'
})

2. （可选）属性prop，类型是对象Object；

<div id="app">
    <custom-element></custom-element>
</div>

Vue.component('custom-element', {
    render: function (createElement) {
        var self = this
        // 第一个参数是一个简单的HTML标签字符 “必选”
        // 第二个参数是一个包含模板相关属性的数据对象 “可选”
        return createElement('div', {
            'class': {
                foo: true,
                bar: false
            },
            style: {
                color: 'red',
                fontSize: '14px'
            },
            attrs: {
                id: 'boo'
            },
            domProps: {
                innerHTML: 'Hello Vue!'
            }
        })
    }
})

let app = new Vue({
    el: '#app'
})

3. （可选）子节点children，类型可以是{String | Array}两种之一。

<div id="app">
    <custom-element></custom-element>
</div>

Vue.component('custom-element', {
    render: function (createElement) {
        var self = this

        return createElement(
            'div', // 第一个参数是一个简单的HTML标签字符 “必选”
            {
                class: {
                    title: true
                },
                style: {
                    border: '1px solid',
                    padding: '10px'
                }
            }, // 第二个参数是一个包含模板相关属性的数据对象 “可选”
            [
                createElement('h1', 'Hello Vue!'),
                createElement('p', '开始学习Vue!')
            ] // 第三个参数是传了多个子元素的一个数组 “可选”
        )
    }
})

let app = new Vue({
    el: '#app'
})

在模板写法中，v-if、v-on、v-model等等指令或者自定义指令都会形成代码，Vue的渲染函数就不会提供专有的替代方法，但是我们也可以自己在渲染函数中实现一样的功能。这样做的优点是可以更加自如地定制指令的效果。具体的代码查看 使用 JavaScript 代替模板功能 | Vue3中文文档 。

插件

插件 | Vue中文文档