@allkit/shared 0.0.1 → 0.0.3

package/skills/references/date.md

@@ -0,0 +1,466 @@
+# date
+
+日期处理工具函数 / Date handling utilities
+
+基于 dayjs / Based on dayjs
+
+## Overview / 概述
+
+提供一系列日期处理函数，包括日期格式化、相对时间显示、时长格式化等。所有函数基于 [dayjs](https://dayjs.gitee.io/) 库。
+
+Provide a series of date handling functions including date formatting, relative time display, duration formatting, etc. All functions are based on [dayjs](https://dayjs.gitee.io/).
+
+## Functions
+
+### useDate
+
+使用 dayjs 实例 / Get dayjs instance
+
+```ts
+function useDate(date?: ConfigType, format?: OptionType, strict?: boolean): Dayjs
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `ConfigType` | `undefined` | 日期值，支持时间戳、Date 对象、字符串 |
+| `format` | `OptionType` | `undefined` | 日期格式 |
+| `strict` | `boolean` | `false` | 是否严格模式 |
+
+**Returns / 返回值**
+
+- `Dayjs`: dayjs 实例
+
+**Example / 示例**
+
+```ts
+// 默认当前时间
+useDate().format('YYYY-MM-DD HH:mm:ss')
+// '2024-03-02 15:30:00'
+
+// 时间戳
+useDate(1709286300000).format('YYYY-MM-DD')
+// '2024-03-02'
+
+// 字符串日期
+useDate('2024-03-02').format('YYYY-MM-DD')
+// '2024-03-02'
+
+// Date 对象
+useDate(new Date()).format('YYYY-MM-DD')
+```
+
+---
+
+### dateFormat
+
+日期转格式字符串 / Format date to string
+
+```ts
+function dateFormat(date: ConfigType, fmt?: string): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `ConfigType` | - | 日期值 |
+| `fmt` | `string` | `'YYYY-MM-DD HH:mm:ss'` | 格式化字符串 |
+
+**Format Tokens / 格式化占位符**
+
+| Token | Description | Example |
+|-------|-------------|---------|
+| `YYYY` | 4位年份 | 2024 |
+| `YY` | 2位年份 | 24 |
+| `MM` | 2位月份 | 03 |
+| `M` | 1-2位月份 | 3 |
+| `DD` | 2位日期 | 02 |
+| `D` | 1-2位日期 | 2 |
+| `HH` | 24小时制 | 15 |
+| `hh` | 12小时制 | 03 |
+| `mm` | 分钟 | 30 |
+| `ss` | 秒数 | 45 |
+
+**Example / 示例**
+
+```ts
+// 完整日期时间
+dateFormat(1709286300000, 'YYYY-MM-DD HH:mm:ss')
+// '2024-03-02 15:30:00'
+
+// 仅日期
+dateFormat(new Date(), 'YYYY-MM-DD')
+// '2024-03-02'
+
+// 中文格式
+dateFormat(new Date(), 'YYYY年MM月DD日')
+// '2024年03月02日'
+
+// 时间
+dateFormat(new Date(), 'HH:mm:ss')
+// '15:30:45'
+```
+
+---
+
+### minute
+
+返回当前时间（默认到分钟）/ Get current time (default to minute)
+
+```ts
+function minute(date?: ConfigType, fmt?: string): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `ConfigType` | `undefined` | 日期值 |
+| `fmt` | `string` | `'YYYY-MM-DD HH:mm'` | 格式化字符串 |
+
+**Example / 示例**
+
+```ts
+minute()
+// '2024-03-02 15:30'
+
+minute(new Date(), 'YYYY-MM-DD HH:mm:ss')
+// '2024-03-02 15:30:45'
+```
+
+---
+
+### dateMonthDays
+
+返回日期对应月份天数 / Get days in month
+
+```ts
+function dateMonthDays(date?: ConfigType): number
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `ConfigType` | `undefined` | 日期值，默认当前月份 |
+
+**Example / 示例**
+
+```ts
+dateMonthDays('2024-02-01')  // 29 (2024年是闰年)
+dateMonthDays('2023-02-01')  // 28
+dateMonthDays('2024-04-01')  // 30
+```
+
+---
+
+### getCurrDate
+
+返回前后 i 天的日期字符串 / Get date before/after i days
+
+```ts
+function getCurrDate(i?: number, format?: string): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `i` | `number` | `0` | 天数偏移量，正数为未来，负数为过去 |
+| `format` | `string` | `'YYYY-MM-DD'` | 格式化字符串 |
+
+**Example / 示例**
+
+```ts
+// 今天
+getCurrDate()
+// '2024-03-02'
+
+// 明天
+getCurrDate(1)
+// '2024-03-03'
+
+// 前天
+getCurrDate(-1)
+// '2024-03-01'
+
+// 一周后
+getCurrDate(7)
+// '2024-03-09'
+
+// 自定义格式
+getCurrDate(1, 'YYYY/MM/DD')
+// '2024/03/03'
+```
+
+---
+
+### dateDiff
+
+返回两个日期时间差 / Get date difference
+
+```ts
+function dateDiff(date1: ConfigType, date2?: ConfigType, unit?: QUnitType | OpUnitType): number
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `date1` | `ConfigType` | - | 第一个日期 |
+| `date2` | `ConfigType` | `undefined` | 第二个日期，默认当前时间 |
+| `unit` | `QUnitType \| OpUnitType` | `undefined` | 返回单位 |
+
+**Unit Options / 单位选项**
+
+| Unit | Description |
+|------|-------------|
+| `ms` / `millisecond` | 毫秒 |
+| `s` / `second` | 秒 |
+| `m` / `minute` | 分钟 |
+| `h` / `hour` | 小时 |
+| `d` / `day` | 天 |
+| `M` / `month` | 月 |
+| `y` / `year` | 年 |
+
+**Example / 示例**
+
+```ts
+// 相差天数
+dateDiff('2024-03-02', '2024-03-01')
+// 1
+
+// 相差小时
+dateDiff('2024-03-02 15:00', '2024-03-02 10:00', 'hour')
+// 5
+
+// 相差分钟
+dateDiff('2024-03-02 15:30:00', '2024-03-02 15:00:00', 'minute')
+// 30
+
+// 相对于当前时间
+dateDiff('2024-03-01')
+// -1 (昨天)
+// 或正数如果是未来
+```
+
+---
+
+### dateFromNow
+
+相对时间显示 / Relative time display
+
+```ts
+function dateFromNow(date: ConfigType, format?: Format): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `ConfigType` | - | 目标日期 |
+| `format` | `Format` | `undefined` | 自定义格式 |
+
+**Default Format / 默认格式**
+
+```ts
+{
+  zero: '刚刚',
+  minuteAgo: '${m}分钟前',
+  today: '今天 ${HH:mm}',
+  yesterday: '昨天 ${HH:mm}',
+  other: '${YYYY/MM/DD}',
+  future: '${YYYY/MM/DD}'
+}
+```
+
+**Example / 示例**
+
+```ts
+// 几分钟前
+dateFromNow('2024-03-02 15:25:00')
+// '5分钟前' (假设当前15:30)
+
+// 今天内
+dateFromNow('2024-03-02 10:00:00')
+// '今天 10:00'
+
+// 昨天
+dateFromNow('2024-03-01 10:00:00')
+// '昨天 10:00'
+
+// 更早
+dateFromNow('2024-02-15 10:00:00')
+// '2024/02/15'
+
+// 自定义格式
+dateFromNow('2024-03-02 10:00:00', {
+  today: '今日 ${HH:mm}',
+  yesterday: '昨日 ${HH:mm}'
+})
+// '今日 10:00'
+```
+
+---
+
+### dateDiffFormat
+
+计算两个日期之间的差值（自然年月日）/ Date difference in natural units
+
+```ts
+function dateDiffFormat(startDate: string | number | Date, endDate?: string | number | Date, format?: string): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `startDate` | `string \| number \| Date` | - | 起始日期 |
+| `endDate` | `string \| number \| Date` | `undefined` | 结束日期，默认当前时间 |
+| `format` | `string` | `'YY年MM个月DD天'` | 输出格式 |
+
+**Format Tokens / 格式化占位符**
+
+| Token | Description |
+|-------|-------------|
+| `YY` | 年 |
+| `MM` | 月 |
+| `DD` | 天 |
+| `HH` | 小时 |
+| `mm` | 分钟 |
+| `ss` | 秒 |
+
+**Example / 示例**
+
+```ts
+dateDiffFormat('2024-01-01', '2024-03-15')
+// '2月14天'
+
+dateDiffFormat('2024-01-01', '2024-03-15', 'YY年MM个月DD天')
+// '0年2个月14天'
+
+dateDiffFormat('2024-01-01 10:00', '2024-01-01 10:30', 'HH:mm')
+// '00:30'
+
+dateDiffFormat('2024-01-01', '2025-06-15', 'YY年MM个月DD天')
+// '1年5个月14天'
+```
+
+---
+
+### durationFormat
+
+格式化时长 / Format duration
+
+```ts
+function durationFormat(duration: string | number, config?: { unit?: DurationUnitType; format?: string | string[] }): string | string[]
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `duration` | `string \| number` | - | 时长数值 |
+| `config.unit` | `DurationUnitType` | `'ms'` | 输入数值的单位 |
+| `config.format` | `string \| string[]` | `'HH小时mm分钟'` | 输出格式 |
+
+**Unit Options / 单位选项**
+
+| Unit | Description |
+|------|-------------|
+| `d` / `D` | 天 |
+| `h` / `H` | 小时 |
+| `m` | 分钟 |
+| `s` | 秒 |
+| `ms` | 毫秒 |
+
+**Example / 示例**
+
+```ts
+// 毫秒转小时分钟
+durationFormat(3661000, { unit: 'ms' })
+// '1小时1分钟'
+
+// 指定格式
+durationFormat(61, { unit: 'm', format: 'HH:mm' })
+// '01:01'
+
+// 返回数组
+durationFormat(61, { unit: 'm', format: ['H', 'm'] })
+// ['1', '1']
+
+// 秒转时分秒
+durationFormat(3665, { unit: 's', format: 'HH:mm:ss' })
+// '01:01:05'
+```
+
+---
+
+### durationFormatNoZero
+
+格式化时长（去掉 0）/ Format duration without zero
+
+```ts
+function durationFormatNoZero(duration: string | number, config?: { unit?: DurationUnitType; format?: string }): string | string[]
+```
+
+**Example / 示例**
+
+```ts
+// 去掉为0的单位
+durationFormatNoZero(61, { unit: 'm' })
+// '1小时1分钟'
+
+// 长时间只显示天数
+durationFormatNoZero(3600000, { unit: 'ms', format: 'D天H小时m分钟' })
+// '1天'
+
+// 整天不带0
+durationFormatNoZero(86400000, { unit: 'ms', format: 'D天H小时m分钟' })
+// '1天'
+```
+
+---
+
+## Use Cases / 使用场景
+
+### 消息列表时间显示 / Message List Time Display
+
+```ts
+function formatMessageTime(date: string | Date) {
+  return dateFromNow(date)
+}
+```
+
+### 订单耗时显示 / Order Duration Display
+
+```ts
+function formatOrderDuration(startTime: number) {
+  const duration = Date.now() - startTime
+  return durationFormat(duration, { unit: 'ms', format: 'DD天HH小时mm分钟' })
+}
+```
+
+### 会员有效期 / Membership Validity
+
+```ts
+function getMembershipExpiry(startDate: string, months: number) {
+  const expiryDate = useDate(startDate).add(months, 'month')
+  return dateFormat(expiryDate, 'YYYY-MM-DD')
+}
+```
+
+### 聊天时间分割线 / Chat Time Divider
+
+```ts
+function shouldShowDateDivider(messages: Message[]) {
+  return messages.map((msg, index) => {
+    if (index === 0) return true
+    const prevDate = useDate(messages[index - 1].createdAt)
+    const currDate = useDate(msg.createdAt)
+    return !currDate.isSame(prevDate, 'day')
+  })
+}
+```

package/skills/references/device.md

@@ -0,0 +1,138 @@
+# device
+
+设备判断工具函数
+
+## Functions
+
+### isIos
+
+是否是 iOS 客户端
+
+```ts
+function isIos(): boolean
+```
+
+### isAndroid
+
+是否是 Android 客户端
+
+```ts
+function isAndroid(): boolean
+```
+
+### isWeChat
+
+是否是微信浏览器
+
+```ts
+function isWeChat(): boolean
+```
+
+### isWxMiniProgram
+
+是否是微信小程序
+
+```ts
+function isWxMiniProgram(): boolean
+```
+
+### isHarmony
+
+是否是鸿蒙系统
+
+```ts
+function isHarmony(): boolean
+```
+
+### getDeviceBrand
+
+获取设备厂商
+
+```ts
+function getDeviceBrand(): EnumDeviceBrand
+```
+
+**Return**
+
+```ts
+enum EnumDeviceBrand {
+  HUAWEI = 'HUAWEI',
+  XIAOMI = 'XIAOMI',
+  OPPO = 'OPPO',
+  VIVO = 'VIVO',
+  HONOR = 'HONOR',
+  SAMSUNG = 'SAMSUNG',
+  MEIZU = 'MEIZU',
+  ONEPLUS = 'ONEPLUS',
+  OTHER = 'OTHER'
+}
+```
+
+### isMobile
+
+是否是移动设备
+
+```ts
+function isMobile(): boolean
+```
+
+### isPC
+
+是否是 PC 设备
+
+```ts
+function isPC(): boolean
+```
+
+### isSafari
+
+是否是 Safari 浏览器
+
+```ts
+function isSafari(): boolean
+```
+
+### isChrome
+
+是否是 Chrome 浏览器
+
+```ts
+function isChrome(): boolean
+```
+
+### isFirefox
+
+是否是 Firefox 浏览器
+
+```ts
+function isFirefox(): boolean
+```
+
+### isEdge
+
+是否是 Edge 浏览器
+
+```ts
+function isEdge(): boolean
+```
+
+## Example
+
+```ts
+import { isIos, isAndroid, isWeChat, getDeviceBrand } from '@allkit/shared'
+
+if (isIos()) {
+  // iOS 特殊处理
+}
+
+if (isAndroid()) {
+  // Android 特殊处理
+}
+
+if (isWeChat()) {
+  // 微信浏览器特殊处理
+}
+
+const brand = getDeviceBrand()
+// 返回 EnumDeviceBrand 枚举值
+```

package/skills/references/element.md

@@ -0,0 +1,99 @@
+# element
+
+DOM 元素操作工具函数
+
+## Functions
+
+### getBoundingClientRect
+
+获取元素的位置和尺寸
+
+```ts
+function getBoundingClientRect(el: Element): DOMRect
+```
+
+### scrollTo
+
+平滑滚动到指定位置
+
+```ts
+function scrollTo(options?: ScrollToOptions): void
+```
+
+### addClass
+
+添加 CSS 类名
+
+```ts
+function addClass(el: HTMLElement, className: string | string[]): void
+```
+
+### removeClass
+
+移除 CSS 类名
+
+```ts
+function removeClass(el: HTMLElement, className: string | string[]): void
+```
+
+### toggleClass
+
+切换 CSS 类名
+
+```ts
+function toggleClass(el: HTMLElement, className: string): void
+```
+
+### hasClass
+
+检查是否包含 CSS 类名
+
+```ts
+function hasClass(el: HTMLElement, className: string): boolean
+```
+
+### style
+
+设置或获取元素样式
+
+```ts
+function style(el: HTMLElement, prop?: string, value?: string): string | void
+```
+
+### attr
+
+设置或获取元素属性
+
+```ts
+function attr(el: HTMLElement, name: string, value?: string): string | void
+```
+
+### remove
+
+移除元素
+
+```ts
+function remove(el: HTMLElement): void
+```
+
+### createEl
+
+创建 DOM 元素
+
+```ts
+function createEl(tag: string, className?: string, html?: string): HTMLElement
+```
+
+## Example
+
+```ts
+import { addClass, removeClass, hasClass, scrollTo } from '@allkit/shared'
+
+const el = document.querySelector('.box')
+
+addClass(el, 'active')
+removeClass(el, 'disabled')
+hasClass(el, 'active')
+
+scrollTo({ top: 0, behavior: 'smooth' })
+```