Skip to content

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: stringFormValue | 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: stringvoid按 id 删除表单提交记录
getLogs(nameOrId)nameOrId: stringChangeLog[] | nullFormValue 不生成历史修改日志,通常返回 null
getByLog(logId)logId: numberFormValue | 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;
}

相关文档 ​