k.site.formValues
站点表单提交记录(FormValue)的查询、写入、更新与删除
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
| KScript API / 服务端脚本 | 当前站点上下文;写入记录需提供目标表单 formId | 读取或管理站点表单提交数据 FormValue |
快速上手
先调用 add({ name, formId }) 创建记录,再写回 values 字段并用 update() 保存:
js
k.api.post(() => {
const name = "submission-" + Date.now()
const formId = k.request.form.formId
k.site.formValues.add({ name, formId })
const created = k.site.formValues.all().find((x) => x.name === name)
created.values["email"] = k.request.form.email
created.values["topic"] = k.request.form.topic
k.site.formValues.update(created)
const saved = k.site.formValues.get(created.id)
return { id: String(saved.id), values: saved.values }
})方法速查
| 方法 / 属性 | 说明 | 返回值 |
|---|---|---|
all() | 返回站点中全部表单提交记录 | FormValue[] |
get(nameOrId) | 按记录 GUID id 读取单个表单提交记录 | FormValue | null |
add(formValue) | 新增基础表单提交记录(勿直接传嵌套 values) | void |
update(formValue) | 持久化对 values 等字段的修改 | void |
delete(nameOrId) | 按记录 id 删除表单提交记录 | void |
getLogs(nameOrId) | 查询变更日志(表单提交值不生成日志,通常返回 null) | ChangeLog[] | null |
getByLog(logId) | 按日志编号读取历史版本(仅在有日志时有效) | FormValue | null |
注意事项
- 新增记录时不要直接向
k.site.formValues.add({ name, formId, values: { ... } })传入嵌套的values对象,否则会触发类型转换错误。请先调用add({ name, formId })创建记录,再从all()取回对象并填充item.values["字段名"],最后调用update(item)保存。 FormValue使用随机生成的 GUID 作为id,请通过id调用get(id)与delete(id)。- 表单提交值仓库不记录版本变更日志,调用
getLogs(id)会返回null。
详细方法
all() / get()
列出站点表单提交记录,或按记录 GUID id 读取单条提交。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
all() | 无 | FormValue[] | 返回全部表单提交记录 |
get(nameOrId) | nameOrId: string | FormValue | null | 按记录 id 读取单个表单提交记录 |
返回值:FormValue[] 或 FormValue | null
js
k.api.get(() => {
const items = k.site.formValues.all()
return {
count: items.length,
latest: items.slice(0, 5).map((item) => ({
id: String(item.id),
name: item.name,
formId: String(item.formId),
values: item.values
}))
}
})add() 与 update()
创建基础记录后填充 values 字典并通过 update() 持久化。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
formValue | { name?: string; formId: string } / FormValue | 是 | add 仅传入 name 与 formId;填充 values 后传入 update |
返回值:void
js
k.api.post(() => {
const item = k.site.formValues.get(k.request.form.id)
if (!item) return { found: false }
item.values["status"] = "reviewed"
k.site.formValues.update(item)
return { updated: true }
})delete() 与 getLogs()
按 id 删除提交记录,或查询日志接口行为。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
delete(nameOrId) | nameOrId: string | void | 按 id 删除表单提交记录 |
getLogs(nameOrId) | nameOrId: string | ChangeLog[] | null | FormValue 不生成历史修改日志,通常返回 null |
getByLog(logId) | logId: number | FormValue | null | 对应历史日志记录(若无日志则不可用) |
返回值:void / ChangeLog[] | null / FormValue | null
js
k.api.post(() => {
const id = k.request.form.id
k.site.formValues.delete(id)
return { deleted: !k.site.formValues.get(id) }
})TypeScript 定义
ts
interface FormValuesRepository {
all(): FormValue[];
get(nameOrId: string): FormValue | null;
add(formValue: { name?: string; formId: string }): void;
update(formValue: FormValue): void;
delete(nameOrId: string): void;
getLogs(nameOrId: string): ChangeLog[] | null;
getByLog(logId: number): FormValue | null;
}
interface FormValue {
id: string;
formId: string;
name: string;
values: Record<string, string>;
creationDate: Date;
lastModified: Date;
lastModifyTick: number;
}