Skip to content

opentiny/tiny-vue / .agents/skills

tinyvue-develop-spec

Verified

tinyvue组件库开发规范

FileKindSize
SKILL.mdskill md3.4 KB
common.skill.mdmarkdown7.8 KB
design.skill.mdmarkdown9.9 KB
directive.skill.mdmarkdown6.0 KB
hooks.skill.mdmarkdown5.9 KB
i18n-workflow.skill.mdmarkdown9.9 KB
icon.skill.mdmarkdown1.3 KB
renderless.skill.mdmarkdown9.4 KB
testing-guide.skill.mdmarkdown11.2 KB
theme.skill.mdmarkdown11.5 KB
utils.skill.mdmarkdown5.7 KB
vue.skill.mdmarkdown9.1 KB

vue.skill.md

View on GitHub
# 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>
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall