💻新组件贡献参考：RFC 骨架屏组件

[mengqiuleo]

背景及需求

相关issue：✨ [Feature]: Please provide Skeleton component

现有类似开源组件调研

• Skeleton 骨架屏 | Element Plus
• 骨架屏 Skeleton - Ant Design Vue
• Skeleton 骨架屏 | Vue DevUI
• 面向 Vue3 的 Material 风格移动端组件库
• Vant 4 - A lightweight, customizable Vue UI library for mobile web apps.

预期效果

Skeleton

1. loading：组件接收 loading 属性，为 true 时渲染骨架屏，页面加载完毕时为 false
2. active：是否显示动画效果
3. rows：骨架屏默认段落显示几行
4. rows-width: 接收数组，自定义每一行的宽度，不传显示默认宽度
5. avatar：skeleton组件默认是显示段落，当 avatar属性 为true时，段落左侧会出现头像，参考骨架屏 Skeleton - Ant Design Vue
6. slot属性：
7. default：默认插槽，加载完成后显示的内容
8. placeholder：用来自定义骨架屏结构

Skeleton-item

1. variant: 决定 skeleton-item 的形态，圆形/image/正常的长条
2. size：大小

补充: 实际效果

实现方案

参考文档：

GaoNeng：我是如何为OpenTiny贡献新组件的？
【我要做开源】OpenTiny开源指南02：适配多组件库的原理剖析

⚠opentiny组件库好像重构了，上述参考文档有出入。

组件设计

skeleton组件比较简单，且不涉及一些事件交互：

• skeleton组件 由多个 skeleton-item组件 组合
• skeleton-item 其实是一个 div，通过添加 css 样式来展示圆角、形状、大小
• 组件接收的 props 可以控制当前组件的 class 类名，在 class 类中增加对应的样式

关于 pc端 和 移动端：skeleton组件每个 item 的长度都是占父元素的百分之多少，所以不需要写 移动端模板

组件开发

step1: 组件模板+样式+交互逻辑

模板

首先执行命令 pnpm create:ui skeleton、pnpm create:ui skeleton-item，此时 pakcages/vue 文件夹下出现对应模板。

• 在 src 文件下，编写 index.ts 文件：写组件接受的props
• 在 src 文件夹下，编写对应的 vue 文件：组件模板，模板可以直接使用 state，不需要从renderless中引入
• 同时需要创建 test 文件，为组件的单测

样式

theme文件夹：创建对应组件的 样式：index.less 和 vars.less(变量文件)，命名规范参考：样式开发指南1、主题变量的命名规则，样式开发指南2、index.less的编写注意事项

BEM规范 ：

• 块（Block）: 块是页面上的独立组件，具有明确的语义和功能。每个块都有自己的名称空间，以便与其他块进行区分。块名通常使用小写字母，单词之间可以使用短横线（-）分隔。 例如：.block、.block-name
• 元素（Element）: 元素是组成块的子元素，通常用于定义块的内部结构和样式。元素名称以块名称为前缀，用双下划线（__）分隔。 例如：.block__element、.block-name__element-name
• 修饰符（Modifier）: 修饰符是用于修改块或元素的行为或样式的标记。修饰符名称以块/元素名称为前缀，用双连字符（--）分隔。 例如：.block--modifier、.block__element--modifier、.block-name__element-name--modifier

命名约定：在使用BEM时，建议遵循以下命名约定：

• 块名通常使用小写字母，单词之间可以使用短横线（-）分隔；
• 元素名以块名称为前缀，用双下划线（__）分隔；
• 修饰符名以块/元素名称为前缀，用双连字符（--）分隔。
  摘自 [干货]-BEM国际命名规范 +美团订单模块实战!!小白必学! - 掘金

renderless

renderless文件夹：相当于 vue 的 <script/>，在这里定义一些 state、watch、computed

• index.ts：写一些事件的纯函数
• vue.ts：所有纯函数、state导出的地方
  💡state 需要在模板中直接使用，不需要导入，eg: <div :class="state.active ? 'active': ''" />
  这里可以参考 GaoNeng 的 文章：renderless - 组件逻辑开发

export const api = [] // 允许暴露出去的api

export const renderless = (
  props, //组件的props
  context, // hooks
  { emit } // nextTick、attr……
): Record<string,any> => {
    const api = {};
    return api; // api 是我们给模板传递的状态、方法
}

Unit test

使用命令行创建的组件模板中是没有 测试相关的依赖的，
所以需要手动安装 @opentiny-internal/vue-test-utils 和 vitest
安装完成后， skeleton/packages.json 中会新增下面的内容

"devDependencies": {
    "@opentiny-internal/vue-test-utils": "workspace:*",
    "vitest": "^0.31.0"
  }

如何编写 ut ?
命令行中执行 pnpm test:unit3 skeleton
参考：前端Vuer，请收好这份《Vue组件单元测试》宝典，给自己多一些安全感 - 掘金

step2: 效果预览

组件注册：

1. packages/modules.json 中，我们需要同时添加 component 和 template
   如果注册之后，执行 pnpm run dev打开本地预览，此时报错找不到组件，那还是组件没有注册成功
   举一个例子：

 "Badge": {
    "path": "vue/src/badge/index.ts",
    "type": "component",
    "exclude": false,
    "mode": [
      "mobile-first",
      "mobile",
      "pc"
    ]
  },
  "BadgeMobile": {
    "path": "vue/src/badge/src/mobile.vue",
    "type": "template",
    "exclude": false
  },
  "BadgeMobileFirst": {
    "path": "vue/src/badge/src/mobile-first.vue",
    "type": "template",
    "exclude": false
  },
  "BadgePc": {
    "path": "vue/src/badge/src/pc.vue",
    "type": "template",
    "exclude": false
  },

2. examples/sites/demos/pc/app/menus.js注册该组件
3. 同时 mobile 和 mobile-first 中都要增加
4. 本地预览需要在 vue3、vue2.7、vue2 中分别测试 pc、mobile、mobile-first
5. 官网预览: pnpm run site 和 pnpm run site:mobile

step3：添加官网 e2e 测试 + 选项/组合式api

相关文档：
组件 demo 和 api 文档编写规范
E2E测试用例编写贡献指南

选项式：base-usage.vue
组合式：base-usage-composition-api.vue

e2e测试
推荐使用 vscode 插件测试，但是我新增的组件在 vscode测试目录中找不到。
所以改用执行命令测试：pnpm run test:e2e3 skeleton
⚠执行测试命令之前需要打开官网（执行 pnpm run site）

step4：添加 ts 类型声明

renderless/types 文件夹中增加对应组件的xx.type.ts
添加的主要内容：

• props
• $constants
• state
• renderless 的三个参数
• renderless 的返回值 api
• index.ts 中纯函数的参数

Q&A

1. mobile 和 mobile-first 有什么区别呢，里面只有部分组件？

2. theme-mobile 文件夹是干什么的，目前所有样式写在 mobile 中？

3. $constants 是什么用呢？

4. 在 pr 合并之前，如何在线预览新增组件？
   可以使用 surge 或者 vercel，貌似 vercel 更方便。
   eg: feat(index-bar): support anchor name slot varletjs/varlet#1400
   

5. 我自己写的组件，packages/vue/package.json中没有出现自动引入，我应该怎么做呢，参考：https://github.com/opentiny/tiny-vue/pull/471/files#diff-689b8ca0de6e456621f03976b3e1b483506098bcc36dcc6219554cdbf6b2d5d6

    "@opentiny/vue-detail-page": "workspace:~",
    "@opentiny/vue-dialog-box": "workspace:~",
    "@opentiny/vue-dialog-select": "workspace:~",
    "@opentiny/vue-divider": "workspace:~", //我的代码里面没有类似的
    "@opentiny/vue-drawer": "workspace:~",
    "@opentiny/vue-drop-roles": "workspace:~",
    "@opentiny/vue-drop-times": "workspace:~",

6. 通过 pnpm create ui: skeleton 创建的组件模板，组件的 packages.json 中缺失了一些依赖，比如：测试相关包的依赖、组件打包的脚本👇🏻。

"devDependencies": {
    "@opentiny-internal/vue-test-utils": "workspace:*",
    "vitest": "^0.31.0"
  },
  "scripts": {
    "build": "pnpm -w build:ui $npm_package_name",
    "//postversion": "pnpm build"
  },

我需要自己手动添加吗？还是等 pr 合并了，opentiny的内部工作人员处理

7. 我如何测试自己组件的测试覆盖率呢？目前只是测一下自己感觉比较重要的点

[kagol]

1. mobile 和 mobile-first 有什么区别呢，里面只有部分组件？

目前TinyVue一共有三套内置模板：

• pc - PC端组件模板
• mobile - 移动端组件模板
• mobile-first - 移动优先，能自适应屏幕的模板

一个组件可以同时有3套模板，视需求而定，有些组件只有pc模板，有些只有mobile模板，有些两种模板都有，也有些有mobile-first模板。

拿 Skeleton 组件为例，由于 skeleton 组件每个 item 的长度都是占父元素的百分之多少，所以不需要写mobile和mobile-first模板，天然就是自适应屏幕的。

[kagol]

2. theme-mobile 文件夹是干什么的，目前所有样式写在 mobile 中？

theme 子包用来存放 PC 端组件的样式和主题，theme-mobile 用来存放移动端组件的样式和主题。

Skeleton 只有 pc 模板，所以它的样式写在 theme 子包中，不需要在 theme-mobile 写样式，因为它没有 mobile 模板。

[mengqiuleo]

关于依赖

现状

使用组件库脚手架创建的组件，版本号有误，且缺少以下相关依赖：
目前的组件配置模版：

{
  "name": "@opentiny/vue-[[NAME]]",
  "version": "5.[[MINOR]].0", // 版本号为 5.x.0，而目前组件库只有 3.x.x
  "description": "",
  "main": "lib/index.js",
  "module": "index.ts",
  "sideEffects": false,
  "type": "module",
  "dependencies": {
    "@opentiny/vue-renderless": "~5.[[MINOR]].0",
    "@opentiny/vue-theme": "~5.[[MINOR]].0",
    "@opentiny/vue-common": "~5.[[MINOR]].0"
  },
  "license": "MIT"
}

1. 创建新组件后，需要手动在 packages/vue/package.json 中添加新组件到依赖

"@opentiny/new-conponent": "workspace:~",  // packages/vue/package.json

2. 新组件的 package.json 中也是缺少依赖的

"devDependencies": {
    "@opentiny-internal/vue-test-utils": "workspace:*",
    "vitest": "^0.31.0"
  },

所以需要手动添加和 执行 pnpm add xxx

[mengqiuleo]

我正在尝试 fix bug:

1. 修复组件的 package.json 模板(版本号 + 添加测试相关依赖)
2. 对于 创建新组件模板后，脚手架是否自动安装依赖/用户手动执行 pnpm add xxx 需要讨论。

如果脚手架自动安装依赖，安装依赖耗时较长，可能开发者会认为是 脚手架有bug???

[kagol]

对于 创建新组件模板后，脚手架是否自动安装依赖/用户手动执行 pnpm add xxx 需要讨论。

我觉得不需要自动执行 pnpm add xxx，因为 pnpm create:ui 的定位是创建空的组件模板，除了这个职责之外的其他职责都不应该承担。
@mengqiuleo

[kagol]

3. $constants 是什么用呢？

@zzcr 可以回答下

[kagol]

4. 在 pr 合并之前，如何在线预览新增组件？

目前不支持这个功能，感兴趣可以参加贡献。

[mengqiuleo]

pr 预览的 github action 已经写好了，现在需要将 surge 的 SURGE_TOKEN 写到 github上，麻烦 kagol 老师处理一下

[kagol]

pr 预览的 github action 已经写好了，现在需要将 surge 的 SURGE_TOKEN 写到 github上，麻烦 kagol 老师处理一下

好的，我今天处理下，感谢贡献！

[kagol]

5. 我自己写的组件，packages/vue/package.json中没有出现自动引入，我应该怎么做呢
6. 通过 pnpm create ui: skeleton 创建的组件模板，组件的 packages.json 中缺失了一些依赖，比如：测试相关包的依赖、组件打包的脚本。我需要自己手动添加吗？还是等 pr 合并了，opentiny的内部工作人员处理

这两个问题都是 create:ui 脚本不完善导致的，可以先优化下这个脚本。能通过脚本添加的话，尽量通过脚本添加。

[kagol]

7. 我如何测试自己组件的测试覆盖率呢？目前只是测一下自己感觉比较重要的点

可以先凭自己感觉编写E2E测试用例和单元测试用例，后续可以考虑Playwright和vitest有没有什么工具可以测试覆盖率。
@zzcr 可以考虑下