集成 Props

除 preset / features 外，以下 props 用于宿主集成，通常不触发 session 重建（getter 动态读取）。

上传

<YanivEditor
  :upload-image="async (file) => (await upload(file)).url"
  :upload-video="async (file) => (await upload(file)).url"
/>

未传时，本地上传回退为 URL.createObjectURL(file) 生成的 blob: 对象 URL，同时弹出一条「未配置上传处理器」提示。 该地址只在当前页面会话内有效（刷新即失效），不可持久化——生产集成必须传上传回调。

从剪贴板直接粘贴图片走的是另一条路径（PasteImage 扩展），插入的是 data: URL，与上传回调无关。

图库

<YanivEditor :gallery-images="images" />

见 模板与图库。

模板

<YanivEditor :custom-templates="templates" />

@ 提及候选项

slashCommand 能力开启时（notion preset 默认开），正文里输入 @ 会弹出候选菜单。 未传 mentionItems 时用的是内置占位数据（首页 / 文档 / 路线图 / 我），生产集成应传真实数据：

<YanivEditor
  preset="notion"
  :mention-items="[
    { id: 'u-1', label: 'Ada', href: '/people/ada', type: 'user' },
    { id: 'p-1', label: '发布计划', href: '/pages/release', type: 'page' },
  ]"
/>

该 prop 同时决定块菜单「页面链接」插入的节点内容；与上传 / 图库一致，变更不触发 session 重建。

AI 托管

<YanivEditor
  preset="full"
  :features="{ ai: true }"
  :ai-config="{
    provider: 'openai',
    apiKey: process.env.OPENAI_KEY,
    model: 'gpt-4o-mini',
    storageMode: 'memory',
    showSettings: false,
  }"
/>

见 AI 配置 API。

大纲初始展开

outline 能力开启时，面板默认收起。需要初始展开时：

<YanivEditor preset="full" :default-outline-expanded="true" />

该 prop 不触发 session rebuild。详见 大纲目录。

Z-Index

编辑器浮层默认基准为 1000，通过 zIndexBase prop 配置（YanivEditor / YanivInlineEditor 均支持；映射为 .yaniv-editor 上的 --ye-z-base）。宿主页面有高层级 UI 时可提高：

<YanivEditor :z-index-base="1500" />

浮层统一挂载在编辑器内部的 overlay portal（.yaniv-editor__overlay-portal），不挂 document.body。

完整 token 表、宿主层级协商与自定义 Shell 要求见 Z-Index 与浮层挂载。

受控内容

<YanivEditor :initial-content="doc" @update="doc = $event" />

Full Editor 内容协议为 JSON（JSONContent）。Inline 为 HTML（v-model:content）。

受控回写带签名去重，避免 emit 回流导致光标跳动。preview 模式下 ContentAdapter 仍可通过 raw transaction 写入；JSON 写入前会按当前 schema 清洗未知节点/mark。

Expose

const editorRef = ref<InstanceType<typeof YanivEditor>>();

editorRef.value?.getEditor(); // Tiptap Editor | null
editorRef.value?.getJSON();
editorRef.value?.getHTML();
editorRef.value?.getText();

高级运行时

自定义 shell 可使用：

import {
  resolveEditorProfile,
  buildExtensions,
  CAPABILITIES,
  ContentAdapter,
  applyPhaseTransition,
} from "@yanivjs/yaniv-editor";

见 Composables API 与 架构设计。