officialblock

OfficialBlock

一个基于 Vue 3 + TypeScript 的组件库，提供高质量的 UI 组件。

📖 文档

本项目包含完整的在线文档系统，类似 Element Plus 官方文档的设计：

• 开发指南：介绍、安装、快速开始
• 组件文档：每个组件的详细使用说明和 API 文档
• 在线演示：可交互的组件示例

本地查看文档

# 克隆项目
git clone <your-repo-url>
cd OfficialBlock

# 安装依赖
npm install

# 启动文档服务器
npm run dev

# 访问 http://localhost:5166

Installation

npm install officialblock

Usage

方式一：全部引入

import { createApp } from 'vue'
import OfficialBlock from 'officialblock'
import 'officialblock/style.css'

const app = createApp(App)
app.use(OfficialBlock)

// 现在可以在任何组件中使用
// <ArticleList model-value="test" />
// <HeroSlide />

方式二：按需引入组件

// Vue 3 Composition API
<template>
  <div>
    <ArticleList model-value="Hello" />
    <HeroSlide />
  </div>
</template>

<script setup>
import { ArticleList, HeroSlide } from 'officialblock'
import 'officialblock/style.css'
</script>

// Vue 3 Options API
import { ArticleList, HeroSlide } from 'officialblock'
import 'officialblock/style.css'

export default {
  components: {
    ArticleList,
    HeroSlide
  },
  data() {
    return {
      articleValue: 'Hello World'
    }
  }
}

方式三：按需引入插件

import { createApp } from 'vue'
import { ArticleListPlugin, HeroSlidePlugin } from 'officialblock'
import 'officialblock/style.css'

const app = createApp(App)
app.use(ArticleListPlugin)  // 只注册 ArticleList 组件
app.use(HeroSlidePlugin)    // 只注册 HeroSlide 组件

全局属性

当你使用 app.use(OfficialBlock) 安装插件时，会自动注册以下全局属性：

$device - 设备检测

在组件中可以直接使用 $device 来检测当前设备类型：

<template>
  <div>
    <div v-if="$device.isMobile">移动端内容</div>
    <div v-else-if="$device.isTablet">平板内容</div>
    <div v-else>桌面端内容</div>
  </div>
</template>

<script setup>
import { getCurrentInstance } from 'vue'

// 在 setup 中使用
const instance = getCurrentInstance()
const device = instance?.proxy?.$device

console.log('是否为移动设备:', device?.isMobile)
console.log('是否为平板:', device?.isTablet)
console.log('是否为移动设备或平板:', device?.isMobileOrTablet)
console.log('是否为桌面:', device?.isDesktop)
</script>

属性说明：

• $device.isMobile: 是否为移动设备 (宽度 < 768px)
• $device.isTablet: 是否为平板设备 (768px ≤ 宽度 < 1024px)
• $device.isMobileOrTablet: 是否为移动设备或平板 (宽度 < 1024px)
• $device.isDesktop: 是否为桌面设备 (宽度 ≥ 1024px)

TypeScript Support

This package includes TypeScript definitions.

import type {
  ComponentProps,
  ComponentEmits,
  ComponentSlots,
  HeroSlideProps,
  HeroSlideEmits,
  SlideItem
} from 'officialblock'

// 使用类型
const articleProps: ComponentProps = {
  modelValue: 'Hello',
  size: 'medium',
  disabled: false
}

const heroProps: HeroSlideProps = {
  autoPlayInterval: 5000,
  showIndicators: true,
  autoPlay: true
}

// $device 全局属性已自动包含类型定义
// 在 TypeScript 中可以直接使用，无需额外导入

Components

ArticleList 文章列表组件

<template>
  <ArticleList
    v-model="articleValue"
    size="medium"
    :disabled="false"
    @change="handleChange"
  >
    <template #header="{ title }">
      <h3>{{ title }}</h3>
    </template>
    <template #default="{ value }">
      <p>当前值: {{ value }}</p>
    </template>
  </ArticleList>
</template>

<script setup>
import { ref } from 'vue'
import { ArticleList } from 'officialblock'

const articleValue = ref('Hello World')

const handleChange = (value) => {
  console.log('值改变了:', value)
}
</script>

Props:

• modelValue: 双向绑定的值
• size: 组件尺寸 ('small' | 'medium' | 'large')
• disabled: 是否禁用

Events:

• change: 值改变时触发
• update:modelValue: v-model 更新事件

Slots:

• default: 默认内容插槽
• header: 头部内容插槽

HeroSlide 轮播图组件

<template>
  <HeroSlide
    :auto-play-interval="5000"
    :show-indicators="true"
    :auto-play="true"
    @change="handleSlideChange"
  />
</template>

<script setup>
import { HeroSlide } from 'officialblock'

const handleSlideChange = (index) => {
  console.log('切换到第', index + 1, '张')
}
</script>

Props:

• autoPlayInterval: 自动播放间隔时间（毫秒），默认 3000
• showIndicators: 是否显示指示器，默认 true
• autoPlay: 是否启用自动播放，默认 true

Events:

• change: 幻灯片切换时触发

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

License

MIT