# TinyVue 组件开发规范

## 核心原则

在 `packages/vue/src` 目录中，每个组件有一个独立的文件夹进行隔离。

每一个组件的结构为：

1.  index.ts: 整个组件的对外导出对象
2.  src/index.ts: 整合 pc/mobile-first 模板为一个统一的组件。通常要把pc/mobile-first模板的全量属性定义在这里并导出给2个模板使用
3.  src/pc.vue: pc 浏览器下的模板，需要引入外部的css样式文件。
4.  src/mobile-first.vue: 移动优先的浏览器模板， 使用tailwind进行内联类名。

## 详细解释每个文件的编写规范

1. index.ts

该文件是整个组件的对外导出对象，负责给组件添加install方法和veresion属性。 示例如下：

```typescript
import Alert from './src/index'
import { version } from './package.json'

Alert.install = function (Vue) {
  Vue.component(Alert.name, Alert)
}

Alert.version = version

if (process.env.BUILD_TARGET === 'runtime') {
  if (typeof window !== 'undefined' && window.Vue) {
    Alert.install(window.Vue)
  }
}

export default Alert
```

2. src/index.ts

整合 pc/mobile-first 模板为一个统一的组件。示例如下：

```typescript
import { $props, $prefix, $setup, defineComponent } from '@opentiny/vue-common'
import template from 'virtual-template?pc|mobile-first'

export const alertProps = {
  // ......
}

export default defineComponent({
  name: $prefix + 'Alert',
  props: alertProps,
  setup(props, context) {
    return $setup({ props, context, template })
  }
})
```

同时引入2个模板的语法为 `import template from 'virtual-template?pc|mobile-first'` ， 它是非标准的TS用法，有专门的`vite`插件会将其编译为两个模板的引入。 `template`是一个函数，它需要传入 `$setup`函数。

3. src/pc.vue 和 src/mobile-first.vue 的模板共同规范

这2个文件是组件的**视图模板**，

- 负责 UI 渲染和用户交互
- 通过适配层的 `setup` 调用 renderless 层的函数
- 可以包含2个跨端模板（如 `mobile-first.vue`、`pc.vue`）
- 禁止内联样式，需要从外部引入。比如：import '@opentiny/vue-theme/alert/index.less'
- 必须引入类型定义文件。 比如： import type { IAlertApi } from '@opentiny/vue-renderless/types/alert.type'

一个标准的模板文件写法如下：

```vue
<template>
  <!-- 模板内容 -->
</template>

<script lang="ts">
import { renderless, api } from '@opentiny/vue-renderless/alert/vue'
import { props, setup, defineComponent } from '@opentiny/vue-common'
import type { IAlertApi } from '@opentiny/vue-renderless/types/alert.type'
import '@opentiny/vue-theme/alert/index.less'

export default defineComponent({
  props: [...props /** 其它属性名 */],
  setup(props, context) {
    return setup({ props, context, renderless, api }) as unknown as IAlertApi
  }
})
</script>
```

**适配层 setup** 函数作用：

1. 纽带作用

我们从 '@opentiny/vue-common' 引入 `setup`函数， 它是联系`无渲染逻辑层` 和 `模板`的纽带。 将`无渲染逻辑层`的组件逻辑函数传入`setup`后，
setup内部会调用该函数，并传入组件实例的 porps, vue官方包对象，以及适配层构造的vm上下文对象，这样`无渲染逻辑层`的组件逻辑函数就会获得组件的所有令牌。 最后它会返回一个 {state,api} 对象，以便模板的绑定。

2. 处理模板选择

如果组件是跨端组件，那么它本质上是一个双层组件，父组件是用来选择使用 pc.vue ,mobile-first.vue 哪个模板， 子组件就是真实的组件。 `setup`函数内部负责向父组件同步状态和属性。此时 setup可选择性传入 `mono:false` 的属性，来告诉setup函数来同步这个状态和属性。

如果组件是一个单一组件，没有通用 `$setup` 来选择模板，那么在调用setup时， 必须传入 `mono:true` 来指示，它是一个单一组件。示例如下：

```typescript
  setup(props, context) {
    return setup({ props, context, renderless, api, mono:true }) as unknown as IAlertApi
  }
```

3. 向`无渲染逻辑层`的组件逻辑函数传入额外的数据

`无渲染逻辑层`的设计上，它不能依赖第三方的库，如果之它需要引入其它对象，需要在 `模板层` 引入它们，并通过`setup` 的`extendOptions`属性 传入 `无渲染逻辑层`的组件逻辑函数中，示例如下：

```typescript
  import FluentEditor from '@opentiny/fluent-editor'

  setup(props, context) {
    return setup({ props, context, renderless, api,
      extendOptions: {
        FluentEditor
      }})
  }
```

## 模板规范

1. 必须使用 vue2, vue3同时兼容的模板语法。
2. 必须是单根节点
3. 不允许 v-if / v-for在同一个节点上， 建议使用 <template> 来使用 v-if / v-for
4. 不允许使用 `id` 等属性
5. 允许使用 Teleport 组件， 但必须从 '@opentiny/vue-common' 包中导入。
6. 模板中可以使用 `a函数`，比如： ` v-bind="a($attrs, ['class', 'style', 'title', 'id'], true)"` ， `a 函数`的意思是从$attrs上过滤出一些属性绑定到元素上。 最后一个参数为true的话，表示这些属性要保留下来，如果为false，则表示这些属性要过滤掉，其它的属性才保留下来。
7. 模板中可以使用 `t函数`, 它是用来加载国际化内容。 比如： `{{ t('ui.base.cancel') }}`
8. 模板中建议增加 `aria-*`的 无障碍信息，尤其是表单元素和图标元素等。

### mobile-first.vue的规范

1. 它使用 `tailwind css`进行模板开发，不依赖外部的样式库。
2. 如果模板中的类名过长，可以将类名转换为变量，约定这些变量存放在 `tokens.ts` 文件中， 示例如下

```typescript token.ts
export const classes = {
  'button': 'inline-block.....',
  'size-default': 'h-10 text-sm sm:h-7'
  // ....
}
```

3. mobile-first模板中，由于不能使用类名表示节点的作用，建议给关键的dom元素，增加 `data-tag`属性来表示dom的作用。根结点统一要增加 data-tag, 示例如下：

```html
<button data-tag="tiny-button"></button>
```

## 参考资源

- [最终导出示例](../../packages/vue/src/button/index.ts)
- [整合模板为一个统一的组件示例](../../packages/vue/src/button/src/index.ts)
- [Button pc模板示例](../../packages/vue/src/button/src/pc.vue)
- [Button mobile-first模板示例](../../packages/vue/src/button/src/mobile-first.vue)

## 多模式介绍

TinyVue 提供了 PC 和 Mobile 组件库，两套组件库对外是同一份依赖`@opentiny/vue`，同名组件通过`tiny_mode`切换组件模式。  
针对 SaaS 业务场景，TinyVue 提供了基于`tailwind`实现的多端组件，  
在 TinyVue 基础上新增`多端模式`，支持业务切换同名组件，同名组件默认情况下是`桌面模式`即`PC 组件`。

### 模式分类

AUI 组件库提供了三种组件模式：`桌面模式`、`多端模式(移动优先)`

| 模式     | 模式介绍 | 模式配置     |
| -------- | -------- | ------------ |
| 桌面模式 | 纯 PC    | pc           |
| 多端模式 | 多端一致 | mobile-first |

### 模式切换

AUI 组件模式设置优先级

`单组件切换` > `模式透传` > `全局切换` > `组件默认模式`

#### 单组件切换

可在组件标签上配置`tiny_mode`属性，指定组件模式，就会选择对应模板渲染：

- 桌面模式：`pc`
- 多端模式：`mobile-first`

参考示例如下：

```html
<tiny-button tiny_mode="mobile-first">默认按钮</tiny-button>
```

#### 全局切换

通过在 Vue 的原型上全局设置`tiny_mode`，可以指定所有同名组件的默认模式。  
在项目入口  `src/main.js`  文件中导入 Vue 依赖后，增加如下配置：

```js
// Vue 2.0
Vue.prototype.tiny_mode = { value: 'mobile-first' }

// Vue 3.0
app.config.globalProperties.tiny_mode = { value: 'mobile-first' }
```

#### 模式透传

如果想在页面部分区域切换模式，如卡片级控制，  
可以在外层 AUI 组件上添加`tiny_mode_root`属性，透传当前 AUI 组件的`tiny_mode`配置到所有子级 AUI 组件上，  
参考 demo 示例如下：

```html
<template>
  <div>
    <tiny-layout>
      <tiny-row tiny_mode="pc" tiny_mode_root>
        <tiny-button>PC 按钮</tiny-button>
        <tiny-button type="primary" native-type="submit">主要按钮</tiny-button>
        <tiny-button type="success">成功按钮</tiny-button>
        <tiny-button type="info">信息按钮</tiny-button>
        <tiny-button type="warning">警告按钮</tiny-button>
        <tiny-button type="danger">危险按钮</tiny-button>
      </tiny-row>
      <tiny-row tiny_mode="mobile-first" tiny_mode_root>
        <tiny-button>多端按钮</tiny-button>
        <tiny-button type="primary" native-type="submit">主要按钮</tiny-button>
        <tiny-button type="success">成功按钮</tiny-button>
        <tiny-button type="info">信息按钮</tiny-button>
        <tiny-button type="warning">警告按钮</tiny-button>
        <tiny-button type="danger">危险按钮</tiny-button>
      </tiny-row>
    </tiny-layout>
  </div>
</template>

<script>
  import { Button, Layout, Row } from '@opentiny/vue'

  export default {
    components: {
      TinyButton: Button,
      TinyLayout: Layout,
      TinyRow: Row
    }
  }
</script>
```