frontend: add the reference library, its tags, and a way in

参考文献 now sits in the header to the right of 论文 and 模板 — the library is
drawn *from* rather than worked in, so it is a button one step away. Its
own second-level menu marks out 文献列表 / 新增文献 / 标签管理 and then lists
the tags themselves, read from their store, so a label can be picked
straight from the rail.

A tag in the rail links to `/references?tag=<id>`, which makes the query
parameter part of the view rather than hidden filter state: the table's own
selector writes the same parameter, so the two cannot disagree and a
filtered view is a link someone can be sent.

The form keeps the order the feature intends — a tag is created before it
is applied, so no stored reference can point at a label that is not there —
and the citation count in a row opens the answer it exists to give (which
paper, which paragraph, which quoted passage).

Tag colours are painted from the row rather than a class map: the palette
is the writer's, and the chip has to be that hue in the table, in the rail
and in the picker.
This commit is contained in:
2026-09-22 17:55:20 +08:00
parent 6020310b3f
commit 872ad8cf3b
12 changed files with 2837 additions and 27 deletions
@@ -0,0 +1,875 @@
<script setup lang="ts">
/**
* Create / edit dialog for one reference in the library.
*
* The form is the field set of :mod:`app.models.reference` grouped the way a
* citation is read — what it is, who wrote it, where it was published, how to
* find it again — rather than one flat list of forty inputs. Everything except
* the title is optional, because the same schema has to hold a one-line journal
* article and a patent with a country, a number and a 公告日期.
*
* Two behaviours are deliberate:
*
* * **Tags are chosen, not typed into existence.** The picker offers the labels
* that exist; typing a new name is allowed, but the label is created through
* the tag API *before* the reference is saved, so a reference can never be
* stored pointing at a label that does not exist. Creating it first is also
* what lets the same label be applied to the next document from the list.
* * **Editing fetches the full row.** The table's shape deliberately drops the
* contributors, the abstract and the note, so the dialog asks for the detail
* rather than editing a list item and losing what it never carried.
*/
import { computed, reactive, ref, watch } from 'vue'
import { ArrowDown, ArrowUp, Delete, Plus } from '@element-plus/icons-vue'
import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
import { errorMessage } from '@/api/client'
import {
createReference,
getReference,
updateReference,
REFERENCE_AUTHOR_ROLE_OPTIONS,
REFERENCE_LANGUAGE_OPTIONS,
REFERENCE_TYPE_OPTIONS,
referenceTypeLabel,
referenceTypeMarker,
type ReferenceListItem,
type ReferencePayload,
} from '@/api/references'
import {
createReferenceTag,
TAG_COLOR_PRESETS,
type ReferenceTag,
} from '@/api/referenceTags'
import { useReferenceTagsStore } from '@/stores/referenceTags'
const props = defineProps<{
/** Visibility, used with `v-model`. */
modelValue: boolean
/** The reference being edited, or `null` to add a new one. */
reference: ReferenceListItem | null
}>()
const emit = defineEmits<{
'update:modelValue': [value: boolean]
/** Emitted after a successful write, so the table and the rail can refresh. */
saved: []
}>()
const tagsStore = useReferenceTagsStore()
const visible = computed({
get: () => props.modelValue,
set: (value: boolean) => emit('update:modelValue', value),
})
/** One contributor row as the form edits it. */
interface AuthorRow {
name: string
family_name: string
given_name: string
role: string
}
/** The text fields, all of them strings, `''` standing for "not filled in". */
interface FormState {
type: string
title: string
subtitle: string
title_translated: string
title_short: string
container_title: string
container_title_short: string
series_title: string
series_number: string
edition: string
volume: string
issue: string
pages: string
article_number: string
publisher: string
publisher_place: string
event_title: string
event_place: string
event_date: string
doi: string
isbn: string
issn: string
url: string
patent_country: string
patent_number: string
standard_number: string
report_number: string
arxiv_id: string
abstract: string
keywords: string
note: string
citation_key: string
language: string
}
function emptyForm(): FormState {
return {
type: 'journal-article',
title: '',
subtitle: '',
title_translated: '',
title_short: '',
container_title: '',
container_title_short: '',
series_title: '',
series_number: '',
edition: '',
volume: '',
issue: '',
pages: '',
article_number: '',
publisher: '',
publisher_place: '',
event_title: '',
event_place: '',
event_date: '',
doi: '',
isbn: '',
issn: '',
url: '',
patent_country: '',
patent_number: '',
standard_number: '',
report_number: '',
arxiv_id: '',
abstract: '',
keywords: '',
note: '',
citation_key: '',
language: '',
}
}
const formRef = ref<FormInstance>()
const loading = ref(false)
const saving = ref(false)
const activeTab = ref('basic')
const form = reactive<FormState>(emptyForm())
const authors = ref<AuthorRow[]>([])
/** Year / month / day are independently optional, exactly as the API stores them. */
const dates = reactive<{
year: number | undefined
month: number | undefined
day: number | undefined
accessed: string | null
}>({ year: undefined, month: undefined, day: undefined, accessed: null })
/**
* The chosen labels.
*
* A number is a tag that exists; a string is a name typed into the picker that
* has no id yet. The distinction is resolved on save, where a missing label is
* created first — which is what keeps "the tag exists" true for every stored
* reference.
*/
const tagValues = ref<(number | string)[]>([])
const rules: FormRules = {
title: [{ required: true, message: '请填写文献题名', trigger: 'blur' }],
}
const title = computed(() => (props.reference ? '编辑文献' : '新增文献'))
const tags = computed<ReferenceTag[]>(() => tagsStore.items)
/** An online resource is identified by its location and nothing else. */
const needsUrl = computed(() => form.type === 'web-page' || form.type === 'dataset')
/** What the chosen type prints after the title, so the writer can see the shape. */
const typeHint = computed(() => {
const marker = referenceTypeMarker(form.type)
const label = referenceTypeLabel(form.type)
return marker ? `${label} · GB/T 7714 标志 [${marker}]` : label
})
watch(
() => props.modelValue,
async (open) => {
if (!open) return
formRef.value?.clearValidate()
Object.assign(form, emptyForm())
authors.value = []
Object.assign(dates, { year: undefined, month: undefined, day: undefined, accessed: null })
tagValues.value = []
activeTab.value = 'basic'
loading.value = true
try {
void tagsStore.ensureLoaded()
if (props.reference) {
const detail = await getReference(props.reference.id)
Object.assign(form, {
type: detail.type,
title: detail.title,
subtitle: detail.subtitle ?? '',
title_translated: detail.title_translated ?? '',
title_short: detail.title_short ?? '',
container_title: detail.container_title ?? '',
container_title_short: detail.container_title_short ?? '',
series_title: detail.series_title ?? '',
series_number: detail.series_number ?? '',
edition: detail.edition ?? '',
volume: detail.volume ?? '',
issue: detail.issue ?? '',
pages: detail.pages ?? '',
article_number: detail.article_number ?? '',
publisher: detail.publisher ?? '',
publisher_place: detail.publisher_place ?? '',
event_title: detail.event_title ?? '',
event_place: detail.event_place ?? '',
event_date: detail.event_date ?? '',
doi: detail.doi ?? '',
isbn: detail.isbn ?? '',
issn: detail.issn ?? '',
url: detail.url ?? '',
patent_country: detail.patent_country ?? '',
patent_number: detail.patent_number ?? '',
standard_number: detail.standard_number ?? '',
report_number: detail.report_number ?? '',
arxiv_id: detail.arxiv_id ?? '',
abstract: detail.abstract ?? '',
keywords: detail.keywords ?? '',
note: detail.note ?? '',
citation_key: detail.citation_key ?? '',
language: detail.language ?? '',
})
authors.value = detail.authors.map((author) => ({
name: author.name,
family_name: author.family_name ?? '',
given_name: author.given_name ?? '',
role: author.role,
}))
dates.year = detail.publication_year ?? undefined
dates.month = detail.publication_month ?? undefined
dates.day = detail.publication_day ?? undefined
dates.accessed = detail.accessed_date
tagValues.value = detail.tags.map((tag) => tag.id)
} else {
// A journal article is what most additions are, and it is already the
// API's default; one contributor row is the minimum that reads as a
// form rather than an empty table.
authors.value = [{ name: '', family_name: '', given_name: '', role: 'author' }]
}
} catch (error) {
ElMessage.error(errorMessage(error))
} finally {
loading.value = false
}
},
)
function addAuthor(): void {
authors.value.push({ name: '', family_name: '', given_name: '', role: 'author' })
}
function removeAuthor(index: number): void {
authors.value.splice(index, 1)
}
/** Move a contributor one place, because the printed order is the stored order. */
function moveAuthor(index: number, delta: number): void {
const target = index + delta
const row = authors.value[index]
if (!row || target < 0 || target >= authors.value.length) return
authors.value.splice(index, 1)
authors.value.splice(target, 0, row)
}
/** A colour for a label created from the picker, cycling the shared palette. */
function nextTagColor(): string {
const preset = TAG_COLOR_PRESETS[tagsStore.items.length % TAG_COLOR_PRESETS.length]
return preset ?? '#409EFF'
}
/**
* Turn the picker's values into tag ids, creating labels that do not exist yet.
*
* Runs before the reference is written, so a failure here leaves nothing
* half-saved. A label that turns out to exist after all — typed twice, or added
* in another tab while this dialog was open — is matched by name instead of
* being reported as a conflict.
*/
async function resolveTagIds(values: (number | string)[]): Promise<number[]> {
const ids: number[] = []
for (const value of values) {
if (typeof value === 'number') {
ids.push(value)
continue
}
const name = value.trim()
if (!name) continue
const known = tagsStore.byName(name)
if (known) {
ids.push(known.id)
continue
}
try {
const created = await createReferenceTag({
name,
color: nextTagColor(),
note: null,
})
ids.push(created.id)
await tagsStore.reload()
} catch (error) {
await tagsStore.reload()
const raced = tagsStore.byName(name)
if (!raced) throw error
ids.push(raced.id)
}
}
// A label cannot be applied twice, and two ids can name the same row only by
// mistake — de-duplicate rather than sending a list the API would store once.
return [...new Set(ids)]
}
function optional(value: string): string | null {
const text = value.trim()
return text ? text : null
}
async function submit(): Promise<void> {
const valid = await formRef.value?.validate().catch(() => false)
if (!valid) return
const named = authors.value.filter((author) => author.name.trim())
const blank = authors.value.length - named.length
if (blank > 0) {
ElMessage.warning('有责任者还没填姓名,请补全或删掉那一行')
activeTab.value = 'authors'
return
}
saving.value = true
try {
const payload: ReferencePayload = {
type: form.type,
title: form.title.trim(),
subtitle: optional(form.subtitle),
title_translated: optional(form.title_translated),
title_short: optional(form.title_short),
container_title: optional(form.container_title),
container_title_short: optional(form.container_title_short),
series_title: optional(form.series_title),
series_number: optional(form.series_number),
edition: optional(form.edition),
volume: optional(form.volume),
issue: optional(form.issue),
pages: optional(form.pages),
article_number: optional(form.article_number),
publisher: optional(form.publisher),
publisher_place: optional(form.publisher_place),
event_title: optional(form.event_title),
event_place: optional(form.event_place),
event_date: optional(form.event_date),
publication_year: dates.year ?? null,
publication_month: dates.month ?? null,
publication_day: dates.day ?? null,
accessed_date: dates.accessed || null,
doi: optional(form.doi),
isbn: optional(form.isbn),
issn: optional(form.issn),
url: optional(form.url),
patent_country: optional(form.patent_country),
patent_number: optional(form.patent_number),
standard_number: optional(form.standard_number),
report_number: optional(form.report_number),
arxiv_id: optional(form.arxiv_id),
abstract: optional(form.abstract),
keywords: optional(form.keywords),
note: optional(form.note),
citation_key: optional(form.citation_key),
language: form.language || null,
authors: named.map((author, index) => ({
name: author.name.trim(),
family_name: optional(author.family_name),
given_name: optional(author.given_name),
role: author.role,
sort: index + 1,
})),
tag_ids: await resolveTagIds(tagValues.value),
}
if (props.reference) {
await updateReference(props.reference.id, payload)
ElMessage.success('文献已更新')
} else {
await createReference(payload)
ElMessage.success('文献已加入库中')
}
emit('saved')
visible.value = false
} catch (error) {
ElMessage.error(errorMessage(error))
} finally {
saving.value = false
}
}
</script>
<template>
<el-dialog
v-model="visible"
:title="title"
width="min(880px, 95vw)"
:close-on-click-modal="false"
append-to-body
class="reference-dialog"
>
<el-alert
v-if="needsUrl"
type="warning"
:closable="false"
show-icon
title="网页、数据集类型的文献必须至少填 URL 或 DOI"
class="form-alert"
/>
<el-form
ref="formRef"
v-loading="loading"
:model="form"
:rules="rules"
label-width="96px"
label-position="right"
>
<el-tabs v-model="activeTab" class="form-tabs">
<el-tab-pane label="基本信息" name="basic">
<div class="grid">
<el-form-item label="文献类型">
<el-select v-model="form.type" class="full">
<el-option
v-for="option in REFERENCE_TYPE_OPTIONS"
:key="option.value"
:value="option.value"
:label="`${option.label} [${option.marker}]`"
/>
</el-select>
<div class="field-hint">{{ typeHint }}</div>
</el-form-item>
<el-form-item label="语种">
<el-select v-model="form.language" clearable placeholder="未指定" class="full">
<el-option
v-for="option in REFERENCE_LANGUAGE_OPTIONS"
:key="option.value"
:value="option.value"
:label="option.label"
/>
</el-select>
</el-form-item>
</div>
<el-form-item label="文献题名" prop="title">
<el-input
v-model="form.title"
placeholder="如 技术惯性与冲量的耦合机制"
maxlength="512"
show-word-limit
clearable
/>
</el-form-item>
<div class="grid">
<el-form-item label="副题名">
<el-input v-model="form.subtitle" placeholder="冒号后的那半句" clearable />
</el-form-item>
<el-form-item label="并列题名">
<el-input v-model="form.title_translated" placeholder="另一个语种的题名" clearable />
</el-form-item>
<el-form-item label="简称">
<el-input v-model="form.title_short" placeholder="正文里简称它什么" clearable />
</el-form-item>
<el-form-item label="文献关键词">
<el-input
v-model="form.keywords"
placeholder="逗号分隔,如 技术演化, 惯性"
clearable
/>
</el-form-item>
</div>
<el-form-item label="标签">
<el-select
v-model="tagValues"
multiple
filterable
allow-create
default-first-option
:reserve-keyword="false"
placeholder="选择已有标签,或直接输入新名称"
class="full"
>
<el-option
v-for="tag in tags"
:key="tag.id"
:value="tag.id"
:label="tag.name"
>
<span class="tag-option">
<span class="tag-dot" :style="{ backgroundColor: tag.color }" />
<span>{{ tag.name }}</span>
<span v-if="tag.note" class="tag-option-note">{{ tag.note }}</span>
</span>
</el-option>
</el-select>
<div class="field-hint">
标签是给自己归档用的,不会出现在参考文献表里;输入库里没有的名称会在保存时自动建好。
也可以先去
<RouterLink to="/references/tags">标签管理</RouterLink>
里整理。
</div>
</el-form-item>
</el-tab-pane>
<el-tab-pane label="责任者" name="authors">
<div class="authors-head">
<span class="authors-hint">
按引用时打印的顺序排列;姓名是必填的,姓 / 名供需要缩写或倒装的格式使用。
</span>
<el-button :icon="Plus" size="small" @click="addAuthor">添加责任者</el-button>
</div>
<div v-if="authors.length === 0" class="authors-empty">
还没有责任者。机构作者(如 世界卫生组织)直接填姓名即可。
</div>
<div v-for="(author, index) in authors" :key="index" class="author-row">
<span class="author-order">{{ index + 1 }}</span>
<el-input v-model="author.name" placeholder="姓名,如 张三" class="author-name" />
<el-input v-model="author.family_name" placeholder="姓" class="author-part" />
<el-input v-model="author.given_name" placeholder="名" class="author-part" />
<el-select v-model="author.role" class="author-role">
<el-option
v-for="option in REFERENCE_AUTHOR_ROLE_OPTIONS"
:key="option.value"
:value="option.value"
:label="option.label"
/>
</el-select>
<div class="author-actions">
<el-button
link
:icon="ArrowUp"
:disabled="index === 0"
@click="moveAuthor(index, -1)"
/>
<el-button
link
:icon="ArrowDown"
:disabled="index === authors.length - 1"
@click="moveAuthor(index, 1)"
/>
<el-button link type="danger" :icon="Delete" @click="removeAuthor(index)" />
</div>
</div>
</el-tab-pane>
<el-tab-pane label="出版信息" name="publish">
<div class="grid">
<el-form-item label="刊名/书名">
<el-input v-model="form.container_title" placeholder="期刊名、论文集名、报纸名" clearable />
</el-form-item>
<el-form-item label="刊名缩写">
<el-input v-model="form.container_title_short" clearable />
</el-form-item>
<el-form-item label="丛书名">
<el-input v-model="form.series_title" clearable />
</el-form-item>
<el-form-item label="丛书号">
<el-input v-model="form.series_number" clearable />
</el-form-item>
<el-form-item label="版本">
<el-input v-model="form.edition" placeholder="如 3版 / 2nd ed." clearable />
</el-form-item>
<el-form-item label="文章编号">
<el-input v-model="form.article_number" placeholder="没有页码时用" clearable />
</el-form-item>
<el-form-item label="卷">
<el-input v-model="form.volume" placeholder="如 198、S1" clearable />
</el-form-item>
<el-form-item label="期">
<el-input v-model="form.issue" placeholder="如 3、Suppl." clearable />
</el-form-item>
<el-form-item label="页码">
<el-input v-model="form.pages" placeholder="如 122-141" clearable />
</el-form-item>
<el-form-item label="出版者">
<el-input v-model="form.publisher" placeholder="出版社 / 学校 / 发布机构" clearable />
</el-form-item>
<el-form-item label="出版地">
<el-input v-model="form.publisher_place" clearable />
</el-form-item>
<el-form-item label="引用日期">
<el-date-picker
v-model="dates.accessed"
type="date"
value-format="YYYY-MM-DD"
placeholder="在线资源的访问日期"
class="full"
/>
</el-form-item>
</div>
<div class="grid grid--dates">
<el-form-item label="出版年">
<el-input-number
v-model="dates.year"
:min="1"
:max="2999"
:controls="false"
placeholder="2024"
class="full"
/>
</el-form-item>
<el-form-item label="月">
<el-input-number
v-model="dates.month"
:min="1"
:max="12"
:controls="false"
placeholder="月"
class="full"
/>
</el-form-item>
<el-form-item label="日">
<el-input-number
v-model="dates.day"
:min="1"
:max="31"
:controls="false"
placeholder="日"
class="full"
/>
</el-form-item>
</div>
<p class="tab-note">
年月日各自独立,知道多少填多少:书通常只有年份,报纸文章有日期,专利填公告日期。
</p>
<el-divider content-position="left">会议(会议论文填这里)</el-divider>
<div class="grid">
<el-form-item label="会议名称">
<el-input v-model="form.event_title" clearable />
</el-form-item>
<el-form-item label="会议地点">
<el-input v-model="form.event_place" clearable />
</el-form-item>
<el-form-item label="会期">
<el-input v-model="form.event_date" placeholder="如 2024-05-01/03" clearable />
</el-form-item>
</div>
</el-tab-pane>
<el-tab-pane label="标识与链接" name="ids">
<div class="grid">
<el-form-item label="DOI">
<el-input
v-model="form.doi"
placeholder="10.1016/j.techfore.2024.123456"
clearable
/>
</el-form-item>
<el-form-item label="URL">
<el-input v-model="form.url" placeholder="https://…" clearable />
</el-form-item>
<el-form-item label="ISBN">
<el-input v-model="form.isbn" clearable />
</el-form-item>
<el-form-item label="ISSN">
<el-input v-model="form.issn" clearable />
</el-form-item>
<el-form-item label="专利国别">
<el-input v-model="form.patent_country" placeholder="如 中国" clearable />
</el-form-item>
<el-form-item label="专利号">
<el-input v-model="form.patent_number" placeholder="如 CN114000000A" clearable />
</el-form-item>
<el-form-item label="标准编号">
<el-input v-model="form.standard_number" placeholder="如 GB/T 7714-2015" clearable />
</el-form-item>
<el-form-item label="报告编号">
<el-input v-model="form.report_number" clearable />
</el-form-item>
<el-form-item label="arXiv">
<el-input v-model="form.arxiv_id" placeholder="如 arXiv:2405.12345" clearable />
</el-form-item>
<el-form-item label="引用键">
<el-input v-model="form.citation_key" placeholder="BibTeX key,供导出用" clearable />
</el-form-item>
</div>
<p class="tab-note">
DOI 会按规范存成不带 <code>https://doi.org/</code> 前缀的形式,粘贴时带前缀也没关系。
</p>
</el-tab-pane>
<el-tab-pane label="摘要与备注" name="notes">
<el-form-item label="摘要">
<el-input
v-model="form.abstract"
type="textarea"
:rows="5"
placeholder="文献摘要,选填"
/>
</el-form-item>
<el-form-item label="备注">
<el-input
v-model="form.note"
type="textarea"
:rows="4"
placeholder="为什么留这篇、PDF 放在哪、要引用哪一段……"
/>
</el-form-item>
</el-tab-pane>
</el-tabs>
</el-form>
<template #footer>
<el-button @click="visible = false">取消</el-button>
<el-button type="primary" :loading="saving" @click="submit">
{{ reference ? '保存修改' : '加入文献库' }}
</el-button>
</template>
</el-dialog>
</template>
<style scoped>
.form-alert {
margin-bottom: 12px;
}
/* The tab strip stays put; only the fields scroll, so the footer never moves
out of reach on a form this long. */
.form-tabs :deep(.el-tabs__content) {
max-height: min(62vh, 620px);
overflow-y: auto;
padding-right: 4px;
scrollbar-width: thin;
}
/* Two fields per row on a wide dialog, one on a narrow one, without a media
query: `auto-fit` collapses the columns when there is no room for two. */
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 0 16px;
}
.grid--dates {
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
}
.full {
width: 100%;
}
.field-hint {
width: 100%;
margin-top: 4px;
font-size: 12px;
line-height: 1.6;
color: var(--el-text-color-secondary);
}
.tab-note {
margin: 0 0 8px;
font-size: 12px;
line-height: 1.7;
color: var(--el-text-color-secondary);
}
.tag-option {
display: flex;
align-items: center;
gap: 6px;
}
.tag-dot {
width: 8px;
height: 8px;
border-radius: 50%;
flex: 0 0 auto;
}
.tag-option-note {
margin-left: auto;
padding-left: 12px;
font-size: 12px;
color: var(--el-text-color-placeholder);
}
.authors-head {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
margin-bottom: 10px;
}
.authors-hint {
font-size: 12px;
line-height: 1.6;
color: var(--el-text-color-secondary);
}
.authors-empty {
padding: 12px;
font-size: 13px;
color: var(--el-text-color-placeholder);
border: 1px dashed var(--el-border-color);
border-radius: 6px;
}
.author-row {
display: flex;
align-items: center;
gap: 8px;
margin-bottom: 8px;
}
.author-order {
flex: 0 0 auto;
width: 20px;
text-align: center;
font-size: 12px;
color: var(--el-text-color-placeholder);
font-variant-numeric: tabular-nums;
}
.author-name {
flex: 2 1 0;
min-width: 0;
}
.author-part {
flex: 1 1 0;
min-width: 0;
}
.author-role {
flex: 0 0 92px;
}
.author-actions {
flex: 0 0 auto;
display: flex;
align-items: center;
}
</style>