packages/ui/docs/README.md
# 通过pnpm安装(推荐)
pnpm add @prompt-optimizer/ui
# 或通过npm安装
npm install @prompt-optimizer/ui
<template>
<div>
<!-- 上下文编辑器 -->
<ContextEditor
v-model:visible="showEditor"
:state="contextState"
@save="handleSave"
/>
<!-- 工具调用显示 -->
<ToolCallDisplay
:tool-calls="toolCalls"
:collapsed="false"
/>
<!-- 可访问性支持 - 使用 composable 方式 -->
<!-- <ScreenReaderSupport> 组件已移除,请使用 useAccessibility -->
<!--
<ScreenReaderSupport
:enhanced="true"
:show-navigation-help="true"
/>
-->
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import {
ContextEditor,
ToolCallDisplay,
// ScreenReaderSupport, // 已移除,使用 useAccessibility composable
useAccessibility,
type ContextState,
type ToolCall
} from '@prompt-optimizer/ui'
// 引入样式
import '@prompt-optimizer/ui/dist/style.css'
// 上下文状态
const showEditor = ref(false)
const contextState = ref<ContextState>({
messages: [
{ role: 'user', content: 'Hello World' }
],
variables: {},
tools: [],
showVariablePreview: true,
showToolManager: true,
mode: 'edit'
})
// 工具调用数据
const toolCalls = ref<ToolCall[]>([
{
id: 'call_1',
name: 'get_weather',
arguments: { location: 'Beijing' },
result: { temperature: 25 },
status: 'success',
timestamp: Date.now()
}
])
// 可访问性支持
const { announce } = useAccessibility('MyApp')
const handleSave = (context: ContextState) => {
console.log('Context saved:', context)
announce('上下文已保存', 'polite')
showEditor.value = false
}
</script>
| 组件名 | 用途 | 主要特性 |
|---|---|---|
ContextEditor | 上下文编辑 | 消息管理、变量处理、工具配置 |
ToolCallDisplay | 工具调用显示 | 折叠面板、状态显示、错误处理 |
ScreenReaderSupport | 屏幕阅读器支持 | 实时通知、键盘快捷键、导航提示 |
| 函数名 | 用途 | 返回值 |
|---|---|---|
useAccessibility | 可访问性支持 | 键盘导航、ARIA管理、消息通知 |
useFocusManager | 焦点管理 | 焦点陷阱、键盘导航、自动恢复 |
useAccessibilityTesting | 可访问性测试 | WCAG合规检查、问题报告 |
<template>
<div>
<!-- ✅ 正确:提供ARIA标签 -->
<button
:aria-label="aria.getLabel('save', '保存')"
@click="handleSave"
>
保存
</button>
<!-- ❌ 错误:缺少语义化标签 -->
<div @click="handleSave">保存</div>
</div>
</template>
<script setup lang="ts">
import { useAccessibility } from '@prompt-optimizer/ui'
const { aria, announce } = useAccessibility('MyComponent')
const handleSave = () => {
// 保存逻辑
announce('内容已保存', 'polite')
}
</script>
<template>
<div class="responsive-container">
<!-- 使用响应式组件属性 -->
<ContextEditor
v-model:visible="showEditor"
:size="isMobile ? 'small' : 'large'"
:state="contextState"
/>
</div>
</template>
<script setup lang="ts">
import { useResponsive } from '@prompt-optimizer/ui'
const { isMobile, isTablet, modalWidth } = useResponsive()
</script>
<style scoped>
.responsive-container {
/* 移动端 */
@media (max-width: 767px) {
padding: 8px;
}
/* 桌面端 */
@media (min-width: 1024px) {
padding: 24px;
}
}
</style>
<template>
<div>
<!-- 大量数据使用虚拟滚动 -->
<ToolCallDisplay
:tool-calls="largeDataset"
:max-items="100"
virtual-scroll
/>
<!-- 使用防抖搜索 -->
<NInput
:value="searchQuery"
@input="debouncedSearch"
placeholder="搜索..."
/>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { useDebounceThrottle } from '@prompt-optimizer/ui'
const { debounce } = useDebounceThrottle()
const searchQuery = ref('')
const largeDataset = ref([]) // 假设有大量数据
const handleSearch = (query: string) => {
// 执行搜索逻辑
console.log('搜索:', query)
}
const debouncedSearch = debounce((value: string) => {
searchQuery.value = value
handleSearch(value)
}, 300)
</script>
A: 使用 useAccessibility composable:
const { isAccessibilityMode } = useAccessibility()
// 自动检测或手动启用
isAccessibilityMode.value = true
A: 使用虚拟化和分页:
<template>
<ToolCallDisplay
:tool-calls="paginatedData"
virtual-scroll
:max-items="50"
/>
</template>
A: 通过CSS变量覆盖默认主题:
:root {
--primary-color: #1890ff;
--border-radius: 4px;
--font-size: 14px;
}
A: 配置i18n实例:
import { createI18n } from 'vue-i18n'
const i18n = createI18n({
locale: 'zh-CN',
messages: {
'zh-CN': { /* 中文消息 */ },
'en-US': { /* 英文消息 */ }
}
})
// 旧版本
import ContextEditor from './components/ContextEditor.vue'
// 新版本
import { ContextEditor } from '@prompt-optimizer/ui'
<!-- 旧版本 -->
<ContextEditor :dialogVisible="visible" />
<!-- 新版本 -->
<ContextEditor v-model:visible="visible" />
<template>
<div>
<ContextEditor v-model:visible="visible" />
<ScreenReaderSupport enhanced />
</div>
</template>
完整的TypeScript类型定义:
import type {
ContextState,
ToolCall,
AccessibilityFeatures,
FocusManagerOptions
} from '@prompt-optimizer/ui'
启用调试模式:
import { setDebugMode } from '@prompt-optimizer/ui'
// 开发环境下启用
if (process.env.NODE_ENV === 'development') {
setDebugMode(true)
}
使用内置的测试工具:
import { useAccessibilityTesting } from '@prompt-optimizer/ui'
const { runTest } = useAccessibilityTesting()
// 运行可访问性测试
const result = await runTest({
wcagLevel: 'AA',
scope: document.body
})
欢迎贡献代码和改进建议!
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)最后更新: 2024年XX月XX日