文档是 Nuxt 开发者体验的核心。为了持续改进文档,我们需要一种简单有效的方式,能直接在每个页面收集用户反馈。以下是我们设计并实现反馈小组件的过程,灵感来自 Plausible 的隐私优先理念。
为什么需要反馈小组件?
当前,用户可以通过创建 GitHub issue 或直接联系我们来提供文档反馈。虽然这些渠道很有价值且依然重要,但它们要求用户离开当前上下文,需要经过多个步骤才能分享想法。
我们想要的是不同的方案:
- 上下文相关:直接集成在每个文档页面中
- 无障碍的:最多 2 次点击即可提交反馈
- 尊重隐私:无个人追踪,设计上符合 GDPR
技术架构
我们的解决方案包含三个主要部分:
1. 结合 Motion 动画的前端
界面结合了 Vue 3 的 Composition API 与 Motion for Vue,打造引人入胜的用户体验。该小组件使用布局动画实现状态平滑过渡,并采用弹簧物理效果营造自然反馈。useFeedback
组合函数负责所有状态管理,并在用户切换页面时自动重置。
例如,以下是成功状态的动画:
<template>
<!-- ... -->
<motion.div
v-if="isSubmitted"
key="success"
:initial="{ opacity: 0, scale: 0.95 }"
:animate="{ opacity: 1, scale: 1 }"
:transition="{ duration: 0.3 }"
class="flex items-center gap-3 py-2"
role="status"
aria-live="polite"
aria-label="反馈提交成功"
>
<motion.div
:initial="{ scale: 0 }"
:animate="{ scale: 1 }"
:transition="{ delay: 0.1, type: 'spring', visualDuration: 0.4 }"
class="text-xl"
aria-hidden="true"
>
✨
</motion.div>
<motion.div
:initial="{ opacity: 0, x: 10 }"
:animate="{ opacity: 1, x: 0 }"
:transition="{ delay: 0.2, duration: 0.3 }"
>
<div class="text-sm font-medium text-highlighted">
感谢您的反馈!
</div>
<div class="text-xs text-muted mt-1">
您的意见帮助我们改进文档。
</div>
</motion.div>
</motion.div>
<!-- ... -->
</template>
反馈小组件的源码可在此处查看。
2. 受 Plausible 启发的匿名化处理
难点在于如何在保护隐私的前提下检测重复(用户更改意见)。我们借鉴了 Plausible 关于无 Cookie 统计独立访客的思路。
export async function generateHash(
today: string,
ip: string,
domain: string,
userAgent: string
): Promise<string> {
const data = `${today}+${domain}+${ip}+${userAgent}`
const buffer = await crypto.subtle.digest(
'SHA-1',
new TextEncoder().encode(data)
)
return [...new Uint8Array(buffer)]
.map(b => b.toString(16).padStart(2, '0'))
.join('')
}
该方法通过结合以下信息生成每日唯一标识:
- IP + User-Agent:由每个 HTTP 请求自然发送
- 域名:实现环境隔离
- 当前日期:确保标识每日更换
为何安全?
- IP 和 User-Agent 从不存储于数据库
- 哈希值每日变化,防止长期追踪
- 几乎无法从哈希值反推原始数据
- 设计符合 GDPR(无持久个人数据)
3. 具有冲突处理的数据库持久化
首先,我们定义反馈表的架构,并在 path
和 fingerprint
列上添加唯一约束。
export const feedback = sqliteTable('feedback', {
id: integer('id').primaryKey({ autoIncrement: true }),
rating: text('rating').notNull(),
feedback: text('feedback'),
path: text('path').notNull(),
title: text('title').notNull(),
stem: text('stem').notNull(),
country: text('country').notNull(),
fingerprint: text('fingerprint').notNull(),
createdAt: integer({ mode: 'timestamp' }).notNull(),
updatedAt: integer({ mode: 'timestamp' }).notNull()
}, table => [uniqueIndex('path_fingerprint_idx').on(table.path, table.fingerprint)])
随后,服务器侧使用 Drizzle 结合 UPSERT
策略:
await drizzle.insert(tables.feedback).values({
rating: data.rating,
feedback: data.feedback || null,
path: data.path,
title: data.title,
stem: data.stem,
country: event.context.cf?.country || 'unknown',
fingerprint,
createdAt: new Date(),
updatedAt: new Date()
}).onConflictDoUpdate({
target: [tables.feedback.path, tables.feedback.fingerprint],
set: {
rating: data.rating,
feedback: data.feedback || null,
country,
updatedAt: new Date()
}
})
这种方法支持用户当天更改意见时更新数据,新反馈则创建,同时实现了每页每用户的自动去重。
服务器端源码可在此处查看。
共享类型确保一致性
我们使用 Zod 进行运行时校验及类型生成:
export const FEEDBACK_RATINGS = [
'very-helpful',
'helpful',
'not-helpful',
'confusing'
] as const
export const feedbackSchema = z.object({
rating: z.enum(FEEDBACK_RATINGS),
feedback: z.string().optional(),
path: z.string(),
title: z.string(),
stem: z.string()
})
export type FeedbackInput = z.infer<typeof feedbackSchema>
该做法确保前端、API 和数据库之间的类型一致。
下一步计划
该小组件现已在所有文档页面上线。我们的下一目标是在 nuxt.com 内部构建一个管理界面,分析反馈模式,识别需要改进的页面。这样可基于真实用户反馈,不断提升文档质量。
完整源码可在 GitHub 上获取,欢迎参考和贡献!