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

directive.skill.md

View on GitHub
# @opentiny/vue-directive 开发规范

## 适用场景

- 模板层需要声明式 DOM 行为(点击外部关闭、无限滚动、文本高亮、自动 Tooltip 等)
- 逻辑与具体组件解耦,可在多个 `pc.vue` / `mobile-first.vue` 中复用
- 不适合放入 renderless 的、强依赖 DOM 或全局监听的交互

## 核心原则

### 1. 包定位

`packages/vue-directive` 发布为 `@opentiny/vue-directive`。

- 指令实现放在 `src/<directive-name>.ts`
- 在 `index.ts` 统一导出
- 可依赖 `@opentiny/utils`、`@opentiny/vue-common`(如 `auto-tip` 使用 Tooltip 与 `hooks`)
- **业务逻辑仍应优先下沉 renderless**;指令只负责 DOM 绑定与事件桥接

### 2. 内置指令一览

| 导出                | 指令名                 | 说明                                                        |
| ------------------- | ---------------------- | ----------------------------------------------------------- |
| `Clickoutside`      | `v-clickoutside`       | 点击元素外部触发回调,支持 `.mousedown` / `.mouseup` 修饰符 |
| `AutoTip`           | `v-auto-tip`           | 文本溢出时自动展示 Tooltip                                  |
| `InfiniteScroll`    | `v-infinite-scroll`    | 滚动到底加载更多                                            |
| `HighlightQuery`    | `v-highlight-query`    | 高亮匹配关键字                                              |
| `ObserveVisibility` | `v-observe-visibility` | 元素可见性监听                                              |
| `RepeatClick`       | `v-repeat-click`       | 长按/重复点击                                               |

文档示例:[自定义指令](https://opentiny.design/tiny-vue/zh-CN/smb-theme/components/directives-auto-tip)

### 3. 在组件模板中注册(必须)

指令在 **vue 模板层** 注册,不在 renderless 中注册。

**Vue 3 写法**(推荐通过 `directive` 适配函数兼容 Vue 2 生命周期名):

```vue
<script lang="ts">
import { setup, directive, defineComponent } from '@opentiny/vue-common'
import { Clickoutside, AutoTip } from '@opentiny/vue-directive'

export default defineComponent({
  directives: directive({ Clickoutside, AutoTip }),
  setup(props, context) {
    return setup({ props, context, renderless, api })
  }
})
</script>

<template>
  <div v-clickoutside="handleClose" v-auto-tip>...</div>
</template>
```

**仅含 Vue 2 钩子(`bind`/`inserted`/`unbind`)的指令**,应通过 `directive({ ... })` 包装。部分指令(如 `ObserveVisibility`、`HighlightQuery`)已在实现内同时声明 Vue 2 / Vue 3 钩子,可直接注册:`directives: { ObserveVisibility }`。

`directive` 辅助函数位于适配层,用于统一 Vue 2 / Vue 3 指令钩子名:

```typescript
// packages/vue-common/src/adapter/vue3/index.ts
mapping(content, 'bind', 'beforeMount')
mapping(content, 'inserted', 'mounted')
mapping(content, 'update', 'updated')
mapping(content, 'unbind', 'unmounted')
```

### 4. 指令实现规范

#### 指令钩子写法

**推荐(新指令)**:实现 `bind` / `update` / `unbind`,由 `directive()` 映射为 Vue 3 的 `beforeMount` / `updated` / `unmounted`:

**特例 `RepeatClick`**:导出为函数而非对象,需手动包装:

```typescript
import { RepeatClick } from '@opentiny/vue-directive'

directives: {
  repeatClick: {
    bind: RepeatClick
  } // 模板中使用 v-repeat-click
}
```

**特例 `HighlightQuery` / `ObserveVisibility`**:实现内已同时声明 Vue 2 / Vue 3 钩子,可直接 `directives: { HighlightQuery }`,无需再经 `directive()` 转换。

新指令推荐模板:

```typescript
import { on, isServer } from '@opentiny/utils'

export default {
  bind(el, binding, vnode) {
    // 初始化
  },
  update(el, binding, vnode) {
    // 更新 binding
  },
  unbind(el) {
    // 清理监听、移除 DOM 副作用
  }
}
```

#### 全局监听

若需 `document` 级监听(如 `Clickoutside`),在模块顶层用 `isServer` 守卫,维护共享 `nodeList`,在 `unbind` 中务必移除引用,防止泄漏。

#### Shadow DOM

点击外部判断需使用 `event.composedPath()`,参考 `clickoutside.ts`。

### 5. 典型用法示例

**Clickoutside**

```html
<!-- 默认:外部按下并松开才触发 -->
<div v-clickoutside="handleClose"></div>
<!-- 修饰符 -->
<div v-clickoutside.mousedown="handleClose"></div>
<div v-clickoutside.mouseup="handleClose"></div>
```

**AutoTip**

```html
<div v-auto-tip>长文本...</div>
<div v-auto-tip="{ content: '自定义', placement: 'top', effect: 'dark' }"></div>
```

绑定值为 `false` / 空时禁用。模板内文字节点需用标签包裹,且避免指令节点直接包含裸文本节点(详见 `highlight-query.ts` 注释)。

**InfiniteScroll**

```html
<div v-infinite-scroll="loadMore" :infinite-scroll-disabled="loading"></div>
```

### 6. 新增指令流程

1. 在 `packages/vue-directive/src/` 新增实现,默认导出指令对象
2. 在 `packages/vue-directive/index.ts` 具名导出
3. 在使用的 `pc.vue` / `mobile-first.vue` 中 `import` 并通过 `directives: directive({ ... })` 注册
4. 优先使用 `@opentiny/utils` 的 `on`/`off`、`throttle`、`getScrollContainer` 等
5. 若需组件方法,通过 `binding.expression` 或 `binding.value` 与 `vnode.context` 通信(Vue 3 项目注意与 `setup` 返回方法的兼容方式,保持与现有指令一致)
6. 在 `examples/sites/demos` 补充演示(若对用户可见)

### 7. 禁止事项

- ❌ 不得在 renderless 的 `index.ts` 中注册或使用 `v-*` 指令
- ❌ 不得在指令中编写组件级业务状态机(应通过 binding 调用 renderless 暴露的方法)
- ❌ 不得跳过 `unbind` 清理
- ❌ 新增指令时避免直接 `import from 'vue'`,DOM 工具走 `@opentiny/utils`,组件/渲染走 `@opentiny/vue-common`

## 参考资源

- [Clickoutside](../../packages/vue-directive/src/clickoutside.ts)
- [AutoTip](../../packages/vue-directive/src/auto-tip.ts)
- [select pc 模板注册示例](../../packages/vue/src/select/src/pc.vue)
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