feat: 更新附录交互组件和文档
This commit is contained in:
sanbuphy
@@ -0,0 +1,744 @@
|
||||
<template>
|
||||
<div class="api-compare-root">
|
||||
<div class="demo-header">
|
||||
<span class="title">📚 函数 API vs HTTP API</span>
|
||||
<span class="subtitle">本地调用 vs 网络请求，文档怎么看？</span>
|
||||
</div>
|
||||
|
||||
<div class="control-panel">
|
||||
<button
|
||||
v-for="tab in tabs"
|
||||
:key="tab.id"
|
||||
:class="['tab-btn', { active: activeTab === tab.id }]"
|
||||
@click="activeTab = tab.id"
|
||||
>
|
||||
{{ tab.icon }} {{ tab.name }}
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div class="visualization-area">
|
||||
<!-- 对比视图 -->
|
||||
<div v-if="activeTab === 'compare'" class="compare-view">
|
||||
<div class="compare-cards">
|
||||
<div class="compare-card">
|
||||
<div class="card-header function">
|
||||
<span class="card-icon">📦</span>
|
||||
<span class="card-title">函数 API</span>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<div class="feature-list">
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">调用方式</span>
|
||||
<span class="feature-value">直接函数调用</span>
|
||||
</div>
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">参数传递</span>
|
||||
<span class="feature-value">括号内传参</span>
|
||||
</div>
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">返回值</span>
|
||||
<span class="feature-value">直接获得结果</span>
|
||||
</div>
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">错误处理</span>
|
||||
<span class="feature-value">异常/返回值</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="code-block">
|
||||
<div class="code-label">Python 示例</div>
|
||||
<pre><code># 调用内置函数
|
||||
length = len("hello") # 返回 5
|
||||
|
||||
# 调用库函数
|
||||
import math
|
||||
result = math.sqrt(16) # 返回 4.0
|
||||
|
||||
# 调用自定义函数
|
||||
def add(a, b):
|
||||
return a + b
|
||||
sum = add(3, 5) # 返回 8</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="vs-divider">
|
||||
<span class="vs-text">VS</span>
|
||||
</div>
|
||||
|
||||
<div class="compare-card">
|
||||
<div class="card-header http">
|
||||
<span class="card-icon">🌐</span>
|
||||
<span class="card-title">HTTP API</span>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<div class="feature-list">
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">调用方式</span>
|
||||
<span class="feature-value">网络请求</span>
|
||||
</div>
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">参数传递</span>
|
||||
<span class="feature-value">URL/Body/Header</span>
|
||||
</div>
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">返回值</span>
|
||||
<span class="feature-value">JSON/XML 响应</span>
|
||||
</div>
|
||||
<div class="feature-item">
|
||||
<span class="feature-label">错误处理</span>
|
||||
<span class="feature-value">状态码判断</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="code-block">
|
||||
<div class="code-label">HTTP 请求示例</div>
|
||||
<pre><code>POST /v1/chat/completions HTTP/1.1
|
||||
Host: api.deepseek.com
|
||||
Authorization: Bearer sk-xxx
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"model": "deepseek-chat",
|
||||
"messages": [
|
||||
{"role": "user", "content": "你好"}
|
||||
]
|
||||
}</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 文档对比视图 -->
|
||||
<div v-if="activeTab === 'docs'" class="docs-view">
|
||||
<div class="docs-cards">
|
||||
<div class="doc-card">
|
||||
<div class="doc-header">
|
||||
<span class="doc-icon">📖</span>
|
||||
<span class="doc-title">函数文档怎么看</span>
|
||||
</div>
|
||||
<div class="doc-content">
|
||||
<div class="doc-section">
|
||||
<div class="doc-section-title">🔍 关注重点</div>
|
||||
<ul class="doc-list">
|
||||
<li><strong>函数签名</strong>：函数名和参数列表</li>
|
||||
<li><strong>参数类型</strong>：每个参数要什么类型</li>
|
||||
<li><strong>返回值</strong>：函数返回什么</li>
|
||||
<li><strong>异常说明</strong>：可能抛出什么错误</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="doc-example">
|
||||
<div class="doc-example-label">Python 文档示例</div>
|
||||
<pre><code>def open(file: str, mode: str = 'r') -> TextIO:
|
||||
"""
|
||||
打开文件并返回文件对象
|
||||
|
||||
Args:
|
||||
file: 文件路径
|
||||
mode: 打开模式 ('r', 'w', 'a')
|
||||
|
||||
Returns:
|
||||
文件对象
|
||||
|
||||
Raises:
|
||||
FileNotFoundError: 文件不存在
|
||||
"""</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="doc-card">
|
||||
<div class="doc-header">
|
||||
<span class="doc-icon">📡</span>
|
||||
<span class="doc-title">HTTP API 文档怎么看</span>
|
||||
</div>
|
||||
<div class="doc-content">
|
||||
<div class="doc-section">
|
||||
<div class="doc-section-title">🔍 关注重点</div>
|
||||
<ul class="doc-list">
|
||||
<li><strong>Endpoint</strong>：URL 路径和 HTTP 方法</li>
|
||||
<li><strong>认证方式</strong>：API Key / Token 怎么传</li>
|
||||
<li><strong>请求参数</strong>：Body / Query / Header</li>
|
||||
<li><strong>响应格式</strong>：成功和错误返回什么</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="doc-example">
|
||||
<div class="doc-example-label">API 文档示例</div>
|
||||
<pre><code>POST /v1/chat/completions
|
||||
|
||||
Headers:
|
||||
Authorization: Bearer {api_key}
|
||||
Content-Type: application/json
|
||||
|
||||
Body:
|
||||
{
|
||||
"model": "deepseek-chat",
|
||||
"messages": [...],
|
||||
"temperature": 0.7
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"choices": [{
|
||||
"message": {"content": "..."}
|
||||
}]
|
||||
}</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 快速判断视图 -->
|
||||
<div v-if="activeTab === 'quick'" class="quick-view">
|
||||
<div class="quick-cards">
|
||||
<div class="quick-card">
|
||||
<div class="quick-header">
|
||||
<span class="quick-icon">⚡</span>
|
||||
<span class="quick-title">快速判断指南</span>
|
||||
</div>
|
||||
<div class="quick-content">
|
||||
<div class="decision-tree">
|
||||
<div class="decision-item">
|
||||
<div class="decision-question">看到代码里有 <code>()</code> 调用？</div>
|
||||
<div class="decision-answer">→ 这是 <strong>函数 API</strong></div>
|
||||
<div class="decision-example">如：len(), print(), requests.get()</div>
|
||||
</div>
|
||||
<div class="decision-arrow">↓</div>
|
||||
<div class="decision-item">
|
||||
<div class="decision-question">看到 URL 和 HTTP 方法？</div>
|
||||
<div class="decision-answer">→ 这是 <strong>HTTP API</strong></div>
|
||||
<div class="decision-example">如：POST /api/users, GET https://...</div>
|
||||
</div>
|
||||
<div class="decision-arrow">↓</div>
|
||||
<div class="decision-item">
|
||||
<div class="decision-question">看到 SDK/Client 对象？</div>
|
||||
<div class="decision-answer">→ 这是 <strong>封装后的 HTTP API</strong></div>
|
||||
<div class="decision-example">如：client.chat.completions.create()</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="quick-card">
|
||||
<div class="quick-header">
|
||||
<span class="quick-icon">🎯</span>
|
||||
<span class="quick-title">使用场景对比</span>
|
||||
</div>
|
||||
<div class="quick-content">
|
||||
<div class="scenario-table">
|
||||
<div class="scenario-row header">
|
||||
<div class="scenario-cell">场景</div>
|
||||
<div class="scenario-cell">推荐方式</div>
|
||||
<div class="scenario-cell">原因</div>
|
||||
</div>
|
||||
<div class="scenario-row">
|
||||
<div class="scenario-cell">本地数据处理</div>
|
||||
<div class="scenario-cell"><span class="badge function">函数 API</span></div>
|
||||
<div class="scenario-cell">快速、无需网络</div>
|
||||
</div>
|
||||
<div class="scenario-row">
|
||||
<div class="scenario-cell">调用 AI 模型</div>
|
||||
<div class="scenario-cell"><span class="badge http">HTTP API</span></div>
|
||||
<div class="scenario-cell">模型在远程服务器</div>
|
||||
</div>
|
||||
<div class="scenario-row">
|
||||
<div class="scenario-cell">获取天气数据</div>
|
||||
<div class="scenario-cell"><span class="badge http">HTTP API</span></div>
|
||||
<div class="scenario-cell">数据在服务商那里</div>
|
||||
</div>
|
||||
<div class="scenario-row">
|
||||
<div class="scenario-cell">文件读写操作</div>
|
||||
<div class="scenario-cell"><span class="badge function">函数 API</span></div>
|
||||
<div class="scenario-cell">直接操作本地文件</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="info-box">
|
||||
<strong>核心要点：</strong>函数 API 是"本地办事"，HTTP API 是"远程通信"。看文档时，函数关注参数和返回值，HTTP API 关注 Endpoint、认证和请求/响应格式。
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import { ref } from 'vue'
|
||||
|
||||
const activeTab = ref('compare')
|
||||
|
||||
const tabs = [
|
||||
{ id: 'compare', name: '核心区别', icon: '🔍' },
|
||||
{ id: 'docs', name: '文档对比', icon: '📚' },
|
||||
{ id: 'quick', name: '快速判断', icon: '⚡' }
|
||||
]
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.api-compare-root {
|
||||
margin: 20px 0;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.demo-header {
|
||||
padding: 16px 20px;
|
||||
background: var(--vp-c-bg);
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.title {
|
||||
display: block;
|
||||
font-size: 1rem;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-1);
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.control-panel {
|
||||
display: flex;
|
||||
gap: 0;
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
background: var(--vp-c-bg);
|
||||
}
|
||||
|
||||
.tab-btn {
|
||||
flex: 1;
|
||||
padding: 12px 16px;
|
||||
background: transparent;
|
||||
border: none;
|
||||
border-right: 1px solid var(--vp-c-divider);
|
||||
font-size: 0.85rem;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.tab-btn:last-child {
|
||||
border-right: none;
|
||||
}
|
||||
|
||||
.tab-btn:hover {
|
||||
background: var(--vp-c-bg-mute);
|
||||
}
|
||||
|
||||
.tab-btn.active {
|
||||
background: var(--vp-c-brand);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.visualization-area {
|
||||
padding: 20px;
|
||||
background: var(--vp-c-bg);
|
||||
}
|
||||
|
||||
/* 对比视图 */
|
||||
.compare-view {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.compare-cards {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr auto 1fr;
|
||||
gap: 16px;
|
||||
align-items: stretch;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.compare-cards {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
.vs-divider {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
.compare-card {
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
background: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
.card-header {
|
||||
padding: 12px 16px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-weight: 600;
|
||||
font-size: 0.95rem;
|
||||
}
|
||||
|
||||
.card-header.function {
|
||||
background: linear-gradient(135deg, #10b981 0%, #059669 100%);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.card-header.http {
|
||||
background: linear-gradient(135deg, #3b82f6 0%, #2563eb 100%);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.card-icon {
|
||||
font-size: 1.2rem;
|
||||
}
|
||||
|
||||
.card-body {
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
.feature-list {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 12px;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
@media (max-width: 480px) {
|
||||
.feature-list {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
.feature-item {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 4px;
|
||||
padding: 10px 12px;
|
||||
background: var(--vp-c-bg);
|
||||
border-radius: 6px;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.feature-label {
|
||||
font-size: 0.7rem;
|
||||
color: var(--vp-c-text-3);
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
}
|
||||
|
||||
.feature-value {
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-1);
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.code-block {
|
||||
background: #0a0a0a;
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.code-label {
|
||||
padding: 8px 12px;
|
||||
background: #18181b;
|
||||
color: #71717a;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 600;
|
||||
border-bottom: 1px solid #27272a;
|
||||
}
|
||||
|
||||
.code-block pre {
|
||||
margin: 0;
|
||||
padding: 12px;
|
||||
color: #e4e4e7;
|
||||
font-size: 0.8rem;
|
||||
line-height: 1.6;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.code-block code {
|
||||
font-family: 'Menlo', 'Monaco', 'Courier New', monospace;
|
||||
}
|
||||
|
||||
.vs-divider {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.vs-text {
|
||||
width: 40px;
|
||||
height: 40px;
|
||||
border-radius: 50%;
|
||||
background: var(--vp-c-bg-alt);
|
||||
border: 2px solid var(--vp-c-divider);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
font-weight: 700;
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
/* 文档视图 */
|
||||
.docs-view {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.docs-cards {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 20px;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.docs-cards {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
.doc-card {
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
background: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
.doc-header {
|
||||
padding: 14px 16px;
|
||||
background: var(--vp-c-bg-alt);
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-weight: 600;
|
||||
font-size: 0.95rem;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.doc-icon {
|
||||
font-size: 1.2rem;
|
||||
}
|
||||
|
||||
.doc-content {
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
.doc-section {
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.doc-section-title {
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-1);
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
.doc-list {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.doc-list li {
|
||||
padding: 6px 0;
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
border-bottom: 1px dashed var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.doc-list li:last-child {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
.doc-list strong {
|
||||
color: var(--vp-c-brand);
|
||||
}
|
||||
|
||||
.doc-example {
|
||||
background: #0a0a0a;
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
.doc-example-label {
|
||||
padding: 8px 12px;
|
||||
background: #18181b;
|
||||
color: #71717a;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 600;
|
||||
border-bottom: 1px solid #27272a;
|
||||
}
|
||||
|
||||
.doc-example pre {
|
||||
margin: 0;
|
||||
padding: 12px;
|
||||
color: #e4e4e7;
|
||||
font-size: 0.75rem;
|
||||
line-height: 1.6;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.doc-example code {
|
||||
font-family: 'Menlo', 'Monaco', 'Courier New', monospace;
|
||||
}
|
||||
|
||||
/* 快速判断视图 */
|
||||
.quick-view {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.quick-cards {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 20px;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.quick-cards {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
.quick-card {
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
background: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
.quick-header {
|
||||
padding: 14px 16px;
|
||||
background: var(--vp-c-bg-alt);
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-weight: 600;
|
||||
font-size: 0.95rem;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.quick-icon {
|
||||
font-size: 1.2rem;
|
||||
}
|
||||
|
||||
.quick-content {
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
.decision-tree {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.decision-item {
|
||||
padding: 14px;
|
||||
background: var(--vp-c-bg);
|
||||
border-radius: 8px;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.decision-question {
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
|
||||
.decision-question code {
|
||||
background: var(--vp-c-bg-mute);
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-size: 0.8rem;
|
||||
}
|
||||
|
||||
.decision-answer {
|
||||
font-size: 0.9rem;
|
||||
color: var(--vp-c-text-1);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.decision-example {
|
||||
font-size: 0.75rem;
|
||||
color: var(--vp-c-text-3);
|
||||
margin-top: 6px;
|
||||
padding-top: 6px;
|
||||
border-top: 1px dashed var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.decision-arrow {
|
||||
text-align: center;
|
||||
color: var(--vp-c-text-3);
|
||||
font-size: 1.2rem;
|
||||
}
|
||||
|
||||
.scenario-table {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 1px;
|
||||
background: var(--vp-c-divider);
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.scenario-row {
|
||||
display: grid;
|
||||
grid-template-columns: 1.2fr 1fr 1.2fr;
|
||||
gap: 12px;
|
||||
padding: 12px;
|
||||
background: var(--vp-c-bg);
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.scenario-row.header {
|
||||
background: var(--vp-c-bg-alt);
|
||||
font-weight: 600;
|
||||
font-size: 0.8rem;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.scenario-cell {
|
||||
font-size: 0.8rem;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.badge {
|
||||
display: inline-block;
|
||||
padding: 4px 10px;
|
||||
border-radius: 4px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.badge.function {
|
||||
background: rgba(16, 185, 129, 0.15);
|
||||
color: #059669;
|
||||
}
|
||||
|
||||
.badge.http {
|
||||
background: rgba(59, 130, 246, 0.15);
|
||||
color: #2563eb;
|
||||
}
|
||||
|
||||
/* Info Box */
|
||||
.info-box {
|
||||
display: flex;
|
||||
gap: 0.5rem;
|
||||
padding: 14px 20px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border-top: 1px solid var(--vp-c-divider);
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.info-box strong {
|
||||
white-space: nowrap;
|
||||
flex-shrink: 0;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,652 @@
|
||||
<template>
|
||||
<div class="doc-types-root">
|
||||
<div class="demo-header">
|
||||
<span class="title">📋 不同文档类型怎么看</span>
|
||||
<span class="subtitle">函数文档、REST API 文档、SDK 文档，各有侧重点</span>
|
||||
</div>
|
||||
|
||||
<div class="control-panel">
|
||||
<button
|
||||
v-for="doc in docTypes"
|
||||
:key="doc.id"
|
||||
:class="['doc-tab', { active: activeDoc === doc.id }]"
|
||||
@click="activeDoc = doc.id"
|
||||
>
|
||||
<span class="tab-icon">{{ doc.icon }}</span>
|
||||
<span class="tab-name">{{ doc.name }}</span>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div class="visualization-area">
|
||||
<div class="doc-display">
|
||||
<!-- 文档头部信息 -->
|
||||
<div class="doc-info-bar">
|
||||
<div class="info-item">
|
||||
<span class="info-label">文档类型</span>
|
||||
<span class="info-value">{{ currentDoc.name }}</span>
|
||||
</div>
|
||||
<div class="info-item">
|
||||
<span class="info-label">适用场景</span>
|
||||
<span class="info-value">{{ currentDoc.scenario }}</span>
|
||||
</div>
|
||||
<div class="info-item">
|
||||
<span class="info-label">阅读难度</span>
|
||||
<span class="info-value">
|
||||
<span class="difficulty-stars">{{ currentDoc.difficulty }}</span>
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 关键信息区 -->
|
||||
<div class="key-points">
|
||||
<div class="point-section">
|
||||
<div class="point-title">🔍 看文档时重点关注</div>
|
||||
<div class="point-tags">
|
||||
<span v-for="(point, idx) in currentDoc.keyPoints" :key="idx" class="point-tag">
|
||||
{{ point }}
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 文档示例区 -->
|
||||
<div class="doc-example-area">
|
||||
<div class="example-header">
|
||||
<span class="example-icon">📝</span>
|
||||
<span class="example-title">文档示例</span>
|
||||
</div>
|
||||
<div class="example-content">
|
||||
<pre><code>{{ currentDoc.example }}</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 阅读技巧 -->
|
||||
<div class="reading-tips">
|
||||
<div class="tips-header">
|
||||
<span class="tips-icon">💡</span>
|
||||
<span class="tips-title">阅读技巧</span>
|
||||
</div>
|
||||
<ul class="tips-list">
|
||||
<li v-for="(tip, idx) in currentDoc.tips" :key="idx">{{ tip }}</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 对比总结 -->
|
||||
<div class="comparison-summary">
|
||||
<div class="summary-header">
|
||||
<span class="summary-icon">📊</span>
|
||||
<span class="summary-title">三种文档快速对比</span>
|
||||
</div>
|
||||
<div class="summary-table">
|
||||
<div class="summary-row header">
|
||||
<div class="summary-cell">对比项</div>
|
||||
<div class="summary-cell">函数文档</div>
|
||||
<div class="summary-cell">REST API 文档</div>
|
||||
<div class="summary-cell">SDK 文档</div>
|
||||
</div>
|
||||
<div class="summary-row">
|
||||
<div class="summary-cell label">核心关注</div>
|
||||
<div class="summary-cell">参数、返回值</div>
|
||||
<div class="summary-cell">Endpoint、请求体</div>
|
||||
<div class="summary-cell">初始化、方法链</div>
|
||||
</div>
|
||||
<div class="summary-row">
|
||||
<div class="summary-cell label">代码示例</div>
|
||||
<div class="summary-cell">函数调用</div>
|
||||
<div class="summary-cell">HTTP 请求</div>
|
||||
<div class="summary-cell">对象方法</div>
|
||||
</div>
|
||||
<div class="summary-row">
|
||||
<div class="summary-cell label">错误处理</div>
|
||||
<div class="summary-cell">异常/返回值</div>
|
||||
<div class="summary-cell">状态码</div>
|
||||
<div class="summary-cell">异常对象</div>
|
||||
</div>
|
||||
<div class="summary-row">
|
||||
<div class="summary-cell label">先看什么</div>
|
||||
<div class="summary-cell">函数签名</div>
|
||||
<div class="summary-cell">Base URL + Auth</div>
|
||||
<div class="summary-cell">Quick Start</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="info-box">
|
||||
<strong>阅读建议：</strong>函数文档看签名，API 文档看请求格式，SDK 文档看示例。遇到不会的，先找「Quick Start」或「Getting Started」章节。
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import { ref, computed } from 'vue'
|
||||
|
||||
const activeDoc = ref('function')
|
||||
|
||||
const docTypes = [
|
||||
{
|
||||
id: 'function',
|
||||
icon: '📦',
|
||||
name: '函数文档',
|
||||
scenario: '使用标准库/第三方库函数',
|
||||
difficulty: '⭐⭐',
|
||||
keyPoints: ['函数签名', '参数类型', '返回值', '异常说明', '示例代码'],
|
||||
example: `### json.loads(s, *, cls=None, object_hook=None...)
|
||||
|
||||
将 JSON 字符串解析为 Python 对象
|
||||
|
||||
**参数：**
|
||||
- s (str): 要解析的 JSON 字符串
|
||||
- cls (JSONDecoder): 自定义解码器类
|
||||
- object_hook (callable): 可选的转换函数
|
||||
|
||||
**返回值：**
|
||||
- dict | list: 解析后的 Python 对象
|
||||
|
||||
**异常：**
|
||||
- JSONDecodeError: 字符串格式非法
|
||||
|
||||
**示例：**
|
||||
>>> import json
|
||||
>>> json.loads('{"name": "Alice"}')
|
||||
{'name': 'Alice'}`,
|
||||
tips: [
|
||||
'先看函数签名，了解需要什么参数',
|
||||
'注意参数的类型和是否必填',
|
||||
'查看返回值类型，方便后续处理',
|
||||
'关注可能抛出的异常，做好错误处理'
|
||||
]
|
||||
},
|
||||
{
|
||||
id: 'rest',
|
||||
icon: '🌐',
|
||||
name: 'REST API 文档',
|
||||
scenario: '调用远程 HTTP 接口',
|
||||
difficulty: '⭐⭐⭐',
|
||||
keyPoints: ['Base URL', '认证方式', 'Endpoint', '请求参数', '响应格式', '错误码'],
|
||||
example: `## POST /v1/chat/completions
|
||||
|
||||
创建聊天完成请求
|
||||
|
||||
### 认证
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
### 请求参数
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| model | string | 是 | 模型名称 |
|
||||
| messages | array | 是 | 消息列表 |
|
||||
| temperature | float | 否 | 采样温度 (0-2) |
|
||||
|
||||
### 请求示例
|
||||
{
|
||||
"model": "deepseek-chat",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello"}
|
||||
],
|
||||
"temperature": 0.7
|
||||
}
|
||||
|
||||
### 响应示例
|
||||
{
|
||||
"choices": [{
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Hello! How can I help you?"
|
||||
}
|
||||
}]
|
||||
}`,
|
||||
tips: [
|
||||
'先找到 Base URL 和认证方式（通常是 API Key）',
|
||||
'确认 HTTP 方法（GET/POST/PUT/DELETE）',
|
||||
'看清参数是放在 URL、Header 还是 Body 里',
|
||||
'注意必填参数和可选参数的区别',
|
||||
'查看错误码列表，了解各种异常情况'
|
||||
]
|
||||
},
|
||||
{
|
||||
id: 'sdk',
|
||||
icon: '📚',
|
||||
name: 'SDK 文档',
|
||||
scenario: '使用官方封装好的开发工具包',
|
||||
difficulty: '⭐⭐',
|
||||
keyPoints: ['安装方式', '初始化', '核心类/方法', '配置选项', '最佳实践'],
|
||||
example: `## OpenAI Python SDK
|
||||
|
||||
### 安装
|
||||
pip install openai
|
||||
|
||||
### 初始化客户端
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key="your-api-key",
|
||||
base_url="https://api.deepseek.com/v1"
|
||||
)
|
||||
|
||||
### 创建聊天完成
|
||||
response = client.chat.completions.create(
|
||||
model="deepseek-chat",
|
||||
messages=[
|
||||
{"role": "user", "content": "Hello!"}
|
||||
],
|
||||
temperature=0.7,
|
||||
max_tokens=1000
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
|
||||
### 流式响应
|
||||
stream = client.chat.completions.create(
|
||||
model="deepseek-chat",
|
||||
messages=[...],
|
||||
stream=True
|
||||
)
|
||||
|
||||
for chunk in stream:
|
||||
print(chunk.choices[0].delta.content, end="")`,
|
||||
tips: [
|
||||
'先看 Quick Start / Getting Started 章节',
|
||||
'了解如何初始化和配置客户端',
|
||||
'关注核心类和方法的使用方式',
|
||||
'查看高级配置选项（如超时、重试）',
|
||||
'参考官方示例代码，理解最佳实践'
|
||||
]
|
||||
},
|
||||
{
|
||||
id: 'websocket',
|
||||
icon: '🔌',
|
||||
name: 'WebSocket 文档',
|
||||
scenario: '实时双向通信',
|
||||
difficulty: '⭐⭐⭐⭐',
|
||||
keyPoints: ['连接地址', '连接建立', '消息格式', '事件处理', '心跳机制', '断开重连'],
|
||||
example: `## WebSocket API
|
||||
|
||||
### 连接地址
|
||||
wss://api.example.com/v1/stream
|
||||
|
||||
### 连接流程
|
||||
|
||||
1. **建立连接**
|
||||
- 发送握手请求
|
||||
- 服务端返回连接确认
|
||||
|
||||
2. **发送消息**
|
||||
{
|
||||
"type": "subscribe",
|
||||
"channel": "price_updates",
|
||||
"symbol": "BTC-USD"
|
||||
}
|
||||
|
||||
3. **接收推送**
|
||||
{
|
||||
"type": "update",
|
||||
"data": {
|
||||
"symbol": "BTC-USD",
|
||||
"price": "45000.00",
|
||||
"timestamp": 1703001600
|
||||
}
|
||||
}
|
||||
|
||||
### 心跳机制
|
||||
客户端每 30 秒发送 ping：
|
||||
{"type": "ping"}
|
||||
|
||||
服务端返回 pong：
|
||||
{"type": "pong"}`,
|
||||
tips: [
|
||||
'注意 ws:// 和 wss:// 的区别（是否加密）',
|
||||
'了解连接建立和关闭的时机',
|
||||
'明确消息的数据格式和类型',
|
||||
'实现心跳检测，保持连接活跃',
|
||||
'处理好断线重连逻辑',
|
||||
'关注并发连接数限制'
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
const currentDoc = computed(() => {
|
||||
return docTypes.find(d => d.id === activeDoc.value) || docTypes[0]
|
||||
})
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.doc-types-root {
|
||||
margin: 20px 0;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.demo-header {
|
||||
padding: 16px 20px;
|
||||
background: var(--vp-c-bg);
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.title {
|
||||
display: block;
|
||||
font-size: 1rem;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-1);
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.control-panel {
|
||||
display: flex;
|
||||
gap: 0;
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
background: var(--vp-c-bg);
|
||||
}
|
||||
|
||||
.doc-tab {
|
||||
flex: 1;
|
||||
padding: 14px 12px;
|
||||
background: transparent;
|
||||
border: none;
|
||||
border-right: 1px solid var(--vp-c-divider);
|
||||
font-size: 0.85rem;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s;
|
||||
color: var(--vp-c-text-2);
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
}
|
||||
|
||||
.doc-tab:last-child {
|
||||
border-right: none;
|
||||
}
|
||||
|
||||
.doc-tab:hover {
|
||||
background: var(--vp-c-bg-mute);
|
||||
}
|
||||
|
||||
.doc-tab.active {
|
||||
background: var(--vp-c-brand);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.tab-icon {
|
||||
font-size: 1.4rem;
|
||||
}
|
||||
|
||||
.tab-name {
|
||||
font-size: 0.8rem;
|
||||
}
|
||||
|
||||
.visualization-area {
|
||||
padding: 20px;
|
||||
background: var(--vp-c-bg);
|
||||
}
|
||||
|
||||
.doc-display {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 16px;
|
||||
}
|
||||
|
||||
.doc-info-bar {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
@media (max-width: 600px) {
|
||||
.doc-info-bar {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
.info-item {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 6px;
|
||||
padding: 14px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border-radius: 8px;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.info-label {
|
||||
font-size: 0.7rem;
|
||||
color: var(--vp-c-text-3);
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
}
|
||||
|
||||
.info-value {
|
||||
font-size: 0.9rem;
|
||||
color: var(--vp-c-text-1);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.difficulty-stars {
|
||||
color: #f59e0b;
|
||||
}
|
||||
|
||||
.key-points {
|
||||
background: var(--vp-c-bg-soft);
|
||||
border-radius: 8px;
|
||||
padding: 16px;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.point-title {
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-1);
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
.point-tags {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.point-tag {
|
||||
padding: 6px 12px;
|
||||
background: var(--vp-c-brand);
|
||||
color: white;
|
||||
border-radius: 4px;
|
||||
font-size: 0.8rem;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.doc-example-area {
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
background: #0a0a0a;
|
||||
}
|
||||
|
||||
.example-header {
|
||||
padding: 12px 16px;
|
||||
background: #18181b;
|
||||
border-bottom: 1px solid #27272a;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.example-icon {
|
||||
font-size: 1rem;
|
||||
}
|
||||
|
||||
.example-title {
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
color: #a1a1aa;
|
||||
}
|
||||
|
||||
.example-content pre {
|
||||
margin: 0;
|
||||
padding: 16px;
|
||||
color: #e4e4e7;
|
||||
font-size: 0.8rem;
|
||||
line-height: 1.7;
|
||||
overflow-x: auto;
|
||||
white-space: pre-wrap;
|
||||
word-wrap: break-word;
|
||||
}
|
||||
|
||||
.example-content code {
|
||||
font-family: 'Menlo', 'Monaco', 'Courier New', monospace;
|
||||
}
|
||||
|
||||
.reading-tips {
|
||||
background: linear-gradient(135deg, rgba(59, 130, 246, 0.05) 0%, rgba(139, 92, 246, 0.05) 100%);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
.tips-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
.tips-icon {
|
||||
font-size: 1rem;
|
||||
}
|
||||
|
||||
.tips-title {
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.tips-list {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.tips-list li {
|
||||
padding: 10px 12px;
|
||||
background: var(--vp-c-bg);
|
||||
border-radius: 6px;
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
border-left: 3px solid var(--vp-c-brand);
|
||||
}
|
||||
|
||||
.comparison-summary {
|
||||
margin: 0 20px 20px;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
background: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
.summary-header {
|
||||
padding: 14px 16px;
|
||||
background: var(--vp-c-bg-alt);
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-weight: 600;
|
||||
font-size: 0.9rem;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.summary-icon {
|
||||
font-size: 1.1rem;
|
||||
}
|
||||
|
||||
.summary-table {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
|
||||
.summary-row {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1.2fr 1.2fr 1.2fr;
|
||||
gap: 1px;
|
||||
background: var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.summary-row:not(.header) {
|
||||
background: var(--vp-c-divider);
|
||||
}
|
||||
|
||||
.summary-row.header {
|
||||
background: var(--vp-c-bg-alt);
|
||||
}
|
||||
|
||||
.summary-row.header .summary-cell {
|
||||
background: var(--vp-c-bg-alt);
|
||||
font-weight: 600;
|
||||
font-size: 0.8rem;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.summary-cell {
|
||||
padding: 12px;
|
||||
background: var(--vp-c-bg);
|
||||
font-size: 0.8rem;
|
||||
color: var(--vp-c-text-1);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.summary-cell.label {
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-2);
|
||||
background: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.summary-row {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.summary-row.header {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.summary-cell {
|
||||
padding: 8px 12px;
|
||||
}
|
||||
|
||||
.summary-cell::before {
|
||||
content: attr(data-label);
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-2);
|
||||
margin-right: 8px;
|
||||
}
|
||||
}
|
||||
|
||||
.info-box {
|
||||
display: flex;
|
||||
gap: 0.5rem;
|
||||
padding: 14px 20px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border-top: 1px solid var(--vp-c-divider);
|
||||
font-size: 0.85rem;
|
||||
color: var(--vp-c-text-2);
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.info-box strong {
|
||||
white-space: nowrap;
|
||||
flex-shrink: 0;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
</style>
|
||||
Reference in New Issue
Block a user