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

utils.skill.md

View on GitHub
# @opentiny/utils 开发规范

## 适用场景

- 在 renderless 层或 vue-hooks 中编写与框架无关的纯逻辑
- 复用日期、字符串、DOM、校验等通用能力
- 新增跨组件工具函数

## 核心原则

### 1. 包定位

`packages/utils` 发布为 `@opentiny/utils`,**不依赖 Vue**,可被以下模块引用:

- `packages/renderless`(无渲染逻辑层,主要消费方)
- `packages/vue-hooks`
- `packages/vue-directive`
- `packages/vue-common`(适配层少量使用)

renderless 层约定:**除 `@opentiny/utils` 与 `@opentiny/vue-hooks` 外,不得依赖其它第三方包**。

### 2. 目录结构

```text
packages/utils/src/
├── index.ts          # 统一导出入口
├── array/            # 数组操作
├── bigInt/           # 大数/精度计算
├── calendar/         # 日历相关
├── crypt/            # sha256 等
├── date/             # 日期格式化、时区
├── date-util/        # 日期工具(与 date 部分能力重叠,待整理)
├── debounce/         # 防抖
├── throttle/         # 节流
├── dom/              # DOM 操作、样式、滚动
├── decimal/          # 小数精度
├── event/            # 事件派发
├── form/             # 表单常量(待迁移至组件内部)
├── function/         # noop、callInterceptor
├── globalConfig/     # isServer、browserInfo、globalConfig
├── logger/           # 日志
├── nanoid/           # 唯一 ID
├── object/           # 对象拷贝、合并、相等
├── string/           # 字符串格式化、驼峰/连字符
├── type/             # 类型判断
├── validate/         # 校验器 Validator
├── xss/              # XSS 过滤
├── tree-model/       # 树形数据结构
├── popper/           # Popper 定位
├── popup-manager/    # 弹层层级管理
└── ...               # 其它模块见 src/index.ts
```

新增工具时:在对应子目录实现,并在 `src/index.ts` 中导出。

### 3. 模块编写规范

1. **纯函数**:不持有组件状态,不 import Vue API
2. **SSR 安全**:涉及 `window`/`document` 时,使用 `isServer`(来自 `globalConfig`)做守卫
3. **单职责**:一个文件聚焦一类能力,避免在 utils 中写组件专属常量(`common/`、`form/` 中部分常量标注为「待移除」,新代码勿再扩展)
4. **测试**:在模块目录下补充 `__tests__` 或 `__test__`,在 `packages/utils` 目录执行 `pnpm test`,或在仓库根目录执行 `pnpm --filter @opentiny/utils test`

### 4. 常用 API 分类

| 分类      | 代表导出                                                                                            | 典型用途                               |
| --------- | --------------------------------------------------------------------------------------------------- | -------------------------------------- |
| 类型判断  | `isObject`, `isFunction`, `isDate`, `typeOf`                                                        | 参数校验                               |
| 字符串    | `camelize`, `hyphenate`, `formatString`, `guid`                                                     | 命名转换、展示格式化                   |
| 日期      | `formatDate`, `toDateStr`, `limitTimeRange`;`calendar` 的 `parseDate`;`date-util` 的 `parseDate1` | 日期/时间组件(注意两套 parse 勿混用) |
| 对象/数组 | `extend`, `merge`, `isEqual`, `find`, `unique`                                                      | 数据处理                               |
| DOM       | `on`, `off`, `addClass`, `getScrollParent`                                                          | 事件与布局                             |
| 性能      | `debounce`, `throttle`, `fastdom`                                                                   | 高频回调、布局批处理                   |
| 安全      | `xss`, `sha256`                                                                                     | 内容过滤、摘要                         |
| ID        | `nanoid`(`nanoid.api.nanoid(size)`)                                                               | 无障碍 id、唯一 key                    |

### 5. 在 renderless 中的引用方式

```typescript
// ✅ 正确:从 @opentiny/utils 按需导入
import { debounce } from '@opentiny/utils'
import { nanoid } from '@opentiny/utils'

// 使用 nanoid
const id = `tiny-alert-title-${nanoid.api.nanoid(8)}`

// ❌ 错误:在 renderless 中 import 'vue'
// ❌ 错误:在 utils 中 import '@opentiny/vue-common'
```

### 6. nanoid 使用说明

`nanoid` 以命名空间导出,推荐通过 `nanoid.api` 访问:

```typescript
import { nanoid } from '@opentiny/utils'

nanoid.api.nanoid(8) // 默认长度
nanoid.api.customAlphabet('abc', 10) // 自定义字母表
nanoid.random() // 0~1 随机数(SSR 下返回 0)
```

### 7. 禁止事项

- ❌ 不得在 utils 中引入 Vue、`@opentiny/vue-common`、`@opentiny/vue-hooks`
- ❌ 不得将仅某一组件使用的常量长期放在 `common/`、`form/`(应下沉到对应 renderless 或组件)
- ❌ 不得重复造轮子:新增前先检索 `src/index.ts` 是否已有同类方法
- ❌ 注意 `date` 与 `date-util` 存在部分重名导出(如 `toDate` / `toDate1`),优先使用语义清晰的现有 API,避免再增加别名

## 构建与发布

```bash
# 在 packages/utils 目录
pnpm build    # vite 构建
pnpm test     # vitest
pnpm pub      # 发布(维护者)
```

## 参考资源

- [统一导出](../../packages/utils/src/index.ts)
- [debounce 示例](../../packages/utils/src/debounce/index.ts)
- [renderless 中的引用](../../packages/renderless/src/alert/vue.ts)
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: 196kUpdated 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: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated 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: 193kUpdated Claude CodeCodexVerifiedInstall