xqh-vue-ui

# 组件设计与开发

# 项目生成和配置

  1. vue-cli 初始化项目，选择配置 bable、CSS 预处理器、单元测试，CSS 预处理器选择 Sass/SCSS (with dart-sass)，单元测试选择 Mocha + Chai。

  2. 目录结构

    ├─public
│     favicon.ico
│     index.html
├─src
│  │  App.vue
│  │  main.js
│  │
│  ├─packages # 开发的组件
|  |    button
│  │      └─button.vue
│  │    index.js # 所有组件的入口
│  │
│  └─styles # 公共样式
│       _var.scss
|       icon.js # iconfont js文件
|─tests # 单元测试
|    └─unit
|       └─button.spec.js
│  .browserslistrc # 浏览器版本兼容设置
│  .gitignore # 忽略文件
│  .babelrc # babel的配置文件
│  package-lock.json
│  package.json
│  README.md

# 组件开发

三要素

  1. props：参考 ElementUI，需要从用户的角度考虑怎么使用方便和扩展性好，一般需要校验类型和有效值，设置默认值。
  2. slot：插槽内容分发，使用作用域插槽让 slot 也可以获得组件内部方法，让用户自定义的内容页能调用组件内部方法，比如 popover 弹出框中用户想自己加个按钮手动调用关闭。
  3. Event：组件事件。从用户角度考虑，比如 date-picker 组件中用户想在日期面板被打开或关闭的时候进行操作，一般用在交互类 UI 组件。

以 button 组件为例

  • API 设计

    参数 说明 类型 可选值 默认值
    type 按钮类型 String default / primary / link / ghost / delicate default
    status 按钮状态 String success / info / warning / danger default
    shape 按钮形状 String square / round / circle square
    size 按钮尺寸 String xs / ms / md / lg md
    icon 图标按钮 String 和图标的值一样 —
    iconPosition 图标位置 String left / right left
    loading 是否为加载状态 Boolean — false
    disabled 是否为禁用状态 Boolean — false

  • 基本结构

    以插槽（slot）的形式嵌套内容

    <template>
  <button
    class="x-button"
    :class="btnClass"
    :disabled="disabled || loading"
    @click="$emit('click', $event)"
  >
    <!-- 略，其他内容 -->
    <span v-if="$slots.default">
      <slot></slot>
    </span>
  </button>
</template>

  • 逻辑实现

    props、事件、功能逻辑

    <script>
import classNames from "@/utils/classNames";
export default {
  name: 'XButton',
  props: {
    type: {
      type: String,
      default: 'default'
    },
    status: {
      type: String,
      default: 'default'
    },
    shape: {
      type: String,
      default: 'square'
    },
    size: {
      type: String,
      default: 'md'
    },
    icon: {
      type: String,
      default: ''
    },
    iconPosition: {
      type: String,
      default: 'left',
    },
    loading: {
      type: Boolean,
      default: false
    },
    disabled: {
      type: Boolean,
      default: false
    }
  },
  computed: {
    btnClass () {
      return classNames([
        `x-button-type-${this.type}`,
        `x-button-status-${this.status}`,
        `x-button-shape-${this.shape}`,
        `x-button-size-${this.size}`,
        this.icon ? 'x-button-hasicon' : '',
        this.iconPosition ? `x-button-${this.iconPosition}` : '',
        this.disabled ? 'x-button-disabled' : ''
      ])
    }
  }
}
</script>

  • 样式设置

    全局样式定义 var.scss

    $primaryColor: #409eff;
$successColor: #67c23a;
$warningColor: #e6a23c;
$dangerColor: #f56c6c;
$infoColor: #909399;
$white: #ffffff;
$black: #000000;
$textBaseColor: #5f6266;
$borderBaseColor: #dcdfe6;
$delicateColor: #8e8e93;

* {
  margin: 0;
  padding: 0;
  font-family: Helvetica Neue, Helvetica, PingFang SC, Hiragino Sans GB, Microsoft YaHei, SimSun,
    sans-serif;
  font-weight: 400;
}

    Button 样式定义 button.scss

    .x-button {
  display: inline-flex;
  justify-content: center;
  align-items: center;
  height: fit-content;
  line-height: 1;
  white-space: nowrap;
  cursor: pointer;
  -webkit-appearance: none;
  text-align: center;
  box-sizing: border-box;
  outline: none;
  margin: 0;
  transition: 0.1s;
  font-weight: 400;
  -moz-user-select: none;
  -webkit-user-select: none;
  -ms-user-select: none;
  border-radius: 6px;
  border: 0;
  // ...
}

# 导出组件库

插件开发，导出 install 方法

src/packages/index.js

import XButton from './button/button.vue'

const components = [
  XButton,
  ...
]

// 全局注册组件
const install = Vue => {
  components.forEach(c => {
    Vue.component(c.name, c)
  })
}

/**
 * 有可能组件会通过script标签引入，如<script src='https://xxx/xqh-vue-ui'></script>
 */
if (typeof Window.Vue !== 'undefined') {
  install(Vue) // 全局直接通过script 引用的方式会默认调用install方法
}

export default {
  install
}

# 导入组件库

在 src/main.js 中导入组件库

import xqhVueUi from './packages'

Vue.use(xqhVueUi)

在 src/App.vue 中使用

<template>
  <x-button type="primary" status="success">success</x-button>
</template>

# 常用 API

  • target.addEventListener(type, listener[, useCapture])/removeEventListener 添加/移除事件监听

  • Node.contains() 返回的是一个布尔值，来表示传入的节点是否为该节点的后代节点。多用于事件监听判断是否点击了目标区域。

  • window.scrollY 获取文档垂直方向的滚动距离。

  • Element.getBoundingClientRect() 返回元素的大小及其相对于视口的位置，返回一个对象，包括 width/height/left/right/top/bottom。

  • $refs： 一个对象，持有注册过 ref 特性的所有 DOM 元素和组件实例。

  • $el: Vue 实例使用的根 DOM 元素。

  • provide & inject：需要一起使用，允许一个祖先组件向其所有子孙后代注入一个依赖，注意不是响应式的。注入的对象可以是个 vue 实例的 eventBus。

  • .sync：语法糖，单向数据流中，父组件监听到子组件修改 props 的意图后父组件修改传入的 props，用了.sync 不需要显式在父组件监听组件内部触发的自定义事件去修改值，父组件只要写:x.sync="bindValue"，此时子组件触发的事件必须是"update:x"，这样语法糖才生效。

  • $slots：获取默认插槽

  • $scopedSlots：获取作用域插槽

# 知识点总结

# 使用 SVG 引入图标

SVG 是一种可缩放矢量图形（Scalable Vector Graphics，SVG），是基于可扩展标记语言（XML），用于描述二维矢量图形的图形格式。简单理解是图形的另一种格式。

优点：

  • 内容可读，文件是纯粹的 XML。
  • 图像文件小，可伸缩性强。
  • 矢量放缩，能以不牺牲图像质量为前提，进行任意缩放。
  • 还能基于 DOM 模型实现动态和一些交互功能。

SVG vs iconfont

  • 渲染方式不同：iconfont 采用的是字体渲染，在一倍屏幕下渲染效果并不好，在细节部分锯齿还是很明显的；SVG 采用的是图形渲染。
  • iconfont 作为字体无法支持多色图形，只能单色。
  • iconfont 主要在页面用 Unicode 符号调用对应的图标，这种方式不管是浏览器，搜索引擎和对无障碍方面的能力都没有 SVG 好。

使用：

SVG 文件内容写入 HTML 文档中即可将 SVG 效果渲染展示到页面中。

<svg width="300" height="200">
    <rect width="100%" height="100%" fill="pink" />
    <circle cx="50" cy="50" r="50" fill="red"></circle>
</svg>

如何在项目中优雅地使用大量的 SVG 图片文件？

采用直接将 SVG 文件内容（实质的 XML 内容）写入到 HTML 文档对应位置去渲染我们所预期的图标图形这种方式，可行但不可取！为这种方式要求使用者在项目每个页面中每个需要展示 SVG 图标的位置，都要将图标文件内容完整的写入对应的 DOM 中，而且 SVG 内容较繁杂，直接写入 DOM 非常影响我们代码的美观和可阅读性。总之这样的操作太过笨重，严重缺乏灵活性和可扩展性。

**SVG Sprite：**symbol + use。我们可以把 SVG 元素看成一个舞台，而symbol则是舞台上一个一个组装好的元件，这些一个一个的元件就是我们即将使用的一个一个 SVG 图标。舞台上只是放置了图标，如果你不使用(use)，是看不见的。

  • 将项目中各个图标合并成一个包含多个 symbol 的 SVG 文件；在需要使用图标的地方，通过 use 元素引用对应的 symbol。

  • 原理：use 元素从 SVG 文档内取得目标节点，并且复制它的内容。效果等同于目标节点被克隆到一个不可见的 DOM 中，然后将其粘贴到 use 元素的位置上。

<!-- sprite.svg 文件目录：/dist/images/sprite.svg -->
<svg width="0" height="0" class="hidden">
  <symbol xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" id="add">
    <path fill="none" d="M0 0h24v24H0V0z"></path>
    <path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"></path>
  </symbol>
  <symbol xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" id="add_photo">
    <path d="M0 0h24v24H0V0z" fill="none" />
    <path
      d="M18 20H4V6h9V4H4c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2v-9h-2v9zm-7.79-3.17l-1.96-2.36L5.5 18h11l-3.54-4.71zM20 4V1h-2v3h-3c.01.01 0 2 0 2h3v2.99c.01.01 2 0 2 0V6h3V4h-3z"
    />
  </symbol>
</svg>

<div>
  <svg><use xlinkHref={`/dist/images/sprite.svg#add_photo`} /></svg>
</div>

如果 SVG Sprite 已经注入到了 HTML 文档中，use 元素的 xlinkHref 则可省去路径，直接使用 #id 去获取目标节点。

SVGIcon 图标组件

核心：

  • 基于 use 元素，封装一个通用灵活的图标组件。

  • 聚合 SVG 图标，生成 SVG Sprite 文件。

实现：

  1. 安装依赖：svg-sprite-loader

  2. 下载图标，将所有 svg 存入 src/icons/svg 中

  3. 在 vue.config.js 配置 loader

    const { defineConfig } = require('@vue/cli-service')
const path = require('path')

// 定义resolve方法，获取绝对路径
function resolve(dir) {
  return path.join(__dirname, dir)
}

module.exports = defineConfig({
  transpileDependencies: true,
  chainWebpack(config) {
    // 默认`vue-cli` 对svg做的处理，正则匹配后缀名为.svg的文件，匹配成功之后使用 url-loader 进行处理。
    // 为避免冲突我们修改如下规则配置：
    // 修改svg规则排除icons目录中svg文件
    config.module.rule('svg').exclude.add(resolve('src/icons')).end()
    // 新增icons规则，设置svg-sprite-loader处理icons目录中的svg
    config.module
      .rule('icons')
      .test(/\.svg$/)
      .include.add(resolve('src/icons'))
      .end()
      .use('svg-sprite-loader')
      .loader('svg-sprite-loader')
      .options({
        symbolId: 'icon-[name]'
      })
      .end()
  }
})

  4. 自动导入图标

    一个个 import svg 太麻烦了，所以使用到 webpack 的 require.context。

    • require.context("./svg", false, /.svg$/);这行代码就会去 svg 文件夹（不包含子目录）下面的找所有文件名以 .svg 结尾的文件能被 require 的文件。简单理解 ：通过正则匹配引入相应的文件模块。

    • equire.context 有三个参数：

      • directory：说明需要检索的目录
      • useSubdirectories：是否检索子目录
      • regExp: 匹配文件的正则表达式
    const req = require.context('@/icons/svg', false, /\.svg$/)
req.keys().map(req)

  5. icon 组件化

    <template>
  <svg
    class="x-icon"
    :class="`x-icon-${icon}`"
    aria-hidden="true"
    v-on="$listeners"
    :style="{ fill: color, width: `${size}px`, height: `${size}px` }"
  >
    <use :xlink:href="`#icon-${icon}`"></use>
  </svg>
</template>

<script>
export default {
  name: 'XIcon',
  props: {
    icon: {
      type: String,
      required: true
    },
    color: {
      type: String,
      default: 'black'
    },
    size: {
      type: Number,
      default: 24
    }
  }
  // mounted () {
  //   require('../style/icon');
  // },
}
</script>

  6. 聚合 SVG 图标：将多个图标合并成一个包含多个 symbol 的 SVG 文件

    • 手动合并，这是最简单易上手的方式。项目初期使用少量 icon 的情况可以使用。但是当项目逐渐庞大起来，一次性需要添加使用特别多 icon 的时候，手动合并明显不合时宜。
    • 利用插件合并，这无疑是最佳选择，合并 SVG 的插件特别多，可以自行选择喜欢的插件来进行合并。比如 svg-spreact。

# 文字偏上问题

设置了 line-height 等于 height 使文字居中，但是出现文字偏上的问题。

原因：

  • 文字小于 12px
  • font-size 为奇数

解决：

  • 使用 transform，定义大号字体，scale 缩小；或者多加一层容器，使用 table-cell 布局。
  • 如果一个行高为 20px 的文字是 15px，可能出现上下空间分配不均的问题，尤其是没有解决 1px border 问题时，这种情况可能会更加明显，建议使用淘宝的 lib-flexible 方案。

# $nextTick

**作用：**可以让我们在下次 DOM 更新循环结束之后执行延迟回调，用于获得更新后的 DOM

**原因：**Vue 中 DOM 更新是一个异步的过程。当数据变化时 Vue 不会立刻更新 DOM，而是开启⼀个队列，把组件更新函数保存在队列中，在同⼀事件循环中发生的所有数据变更会异步的批量更新。这⼀策略导致我们对数据的修改不会立刻体现在 DOM 上，此时如果想要获取更新后的 DOM 状态，就需要使用 nextTick。

**原理：**注册异步任务来对任务进行处理，nextTick 主要使用了宏任务和微任务的原理，根据执行环境降级判断 Promise.then 、MutationObserver 、setImmediate、setTimeout 这四种方法，如果支持的话，便会使用该方法调用 flushCallbacks 函数。

**应用场景：**需要在视图更新之后，基于新的视图进行操作。

  • created()钩子函数进行的 DOM 操作一定要放在 Vue.nextTick()的回调函数中
  • 更改数据后当你想立即使用 js 操作新的视图的时候需要使用它

注意 mounted 不会承诺所有的子组件也都一起被挂载。如果希望等到整个视图都渲染完毕，可以用 vm.$nextTick 替换掉 mounted

mounted: function () {
  this.$nextTick(function () {
    // Code that will run only after the entire view has been rendered
  })
}

# v-clickoutside

自定义指令的钩子函数：

  • bind：只调用一次，指令第一次绑定到元素时调用。在这里可以进行一次性的初始化设置。

  • inserted：被绑定元素插入父节点时调用 (仅保证父节点存在，但不一定已被插入文档中)。

  • update：所在组件的 VNode 更新时调用，但是可能发生在其子 VNode 更新之前。指令的值可能发生了改变，也可能没有。但是你可以通过比较更新前后的值来忽略不必要的模板更新 (详细的钩子函数参数见下)。

  • componentUpdated：指令所在组件的 VNode 及其子 VNode 全部更新后调用。

  • unbind：只调用一次，指令与元素解绑时调用。

所有的钩子函数的参数都有以下：

  • el：指令所绑定的元素，可以用来直接操作 DOM。
  • binding：一个对象，包含以下 property：
    • name：指令名，不包括 v- 前缀。
    • value：指令的绑定值，例如：v-my-directive="1 + 1" 中，绑定值为 2。
    • oldValue：指令绑定的前一个值，仅在 update 和 componentUpdated 钩子中可用。无论值是否改变都可用。
    • expression：字符串形式的指令表达式。例如 v-my-directive="1 + 1" 中，表达式为 "1 + 1"。
    • arg：传给指令的参数，可选。例如 v-my-directive:foo 中，参数为 "foo"。
    • modifiers：一个包含修饰符的对象。例如：v-my-directive.foo.bar 中，修饰符对象为 { foo: true, bar: true }。
    • vnode：Vue 编译生成的虚拟节点。移步 VNode API 来了解更多详情。
    • oldVnode：上一个虚拟节点，仅在 update 和 componentUpdated 钩子中可用。
import Vue from 'vue'
//自定义指令-点击div区域之外触发

// 提交验证
Vue.directive('clickOutside', {
  // 初始化指令
  bind(el, binding) {
    function clickHandler(e) {
      // 这里判断点击的元素是否是本身，是本身，则返回
      if (el.contains(e.target)) {
        return false
      }
      // 判断指令中是否绑定了函数
      if (binding.expression) {
        // 如果绑定了函数 则调用那个函数，此处binding.value就是handleClose方法
        binding.value(e)
      }
    }
    // 给当前元素绑定个私有变量，方便在unbind中可以解除事件监听
    el.__vueClickOutside__ = clickHandler
    document.addEventListener('click', clickHandler)
  },
  update() {},
  unbind(el) {
    // 解除事件监听
    document.removeEventListener('click', el.__vueClickOutside__)
    delete el.__vueClickOutside__
  }
})

//自定义指令引入
import './directive/directive'

// 使用
 <div v-click-outside="outsideClick">

# Infinite-scroll 无限滚动

**原理：**当滚动条到底的时候就加载。所以很关键的一点是要知道滚动条和底部的距离。

知识点：

  • scrollHeight：只读属性，是一个元素内容高度的度量，包括由于溢出导致的视图中不可见内容。
  • scrollTop：可以获取或设置一个元素的内容垂直滚动的像素数。
  • clientHeight：只读属性，对于没有定义 CSS 或者内联布局盒子的元素为 0，否则，它是元素内部的高度(单位像素)，包含内边距，但不包括水平滚动条、边框和外边距。

javascript-InfiniteScroll-eg1

通过计算就可以得到滚动条到底部的距离：

distance = Element.scrollHeight - Element.scrollTop - Element.clientHeight

# 报错

  1. Object/Array 类型的 Props 必须使用工厂函数返回默认值。
Invalid default value for prop "data": Props with type Object/Array must use a factory function to r

解决：将默认的值以函数的方式进行返回。

  1. lang="scss"没写，导致样式加载错误。
  2. slot 的新旧语法混用在一个组件标签上
Debug：Unexpected mixed usage of different slot syntaxes

解决：

  • 第一种写法：slot="xxx" slot-scope="xx"

  • 第二种写法：v-slot:xxx="{xx}"

  1. 增加按需引入，增加每个组件的单独导出文件，修改 webpack 打包配置，需要注意目录结构、文件名，打包后使用报栈溢出，原因是插件式组件重复注册，导出与普通组件不同！

单元测试 →