import{At as e,E as t,Ot as n,Xt as r}from"./chunks/framework.ECw2lWOt.js";var i=JSON.parse(`{"title":"editorService方法","description":"","frontmatter":{},"headers":[],"relativePath":"api/editor/editorServiceMethods.md","filePath":"api/editor/editorServiceMethods.md"}`),a={name:`api/editor/editorServiceMethods.md`};function o(t,i,a,o,s,c){return r(),n(`div`,null,[...i[0]||=[e(`

editorService方法 ​

历史记录相关 options ​

下列 DSL 操作方法（add、remove、update 等）的 options / data 参数，以及 codeBlockService / dataSourceService 的 options，在 doNotPushHistory 之外还可传入：

编辑器内置交互（画布、树面板、配置面板、右键菜单、快捷键等）会自动传入对应的 historySource； 业务侧程序化调用时建议显式传入（如 api），便于历史面板区分来源。

历史记录 uuid 与 *AndGetHistoryId ​

每条历史记录入栈时都会自动生成一个唯一标识 uuid（见 StepValue），可用于精确引用 / 定位某一条历史记录（如埋点、回滚、跨端同步等）。

DSL 操作方法（add / remove / update 等）默认返回操作结果（节点 / 节点集合 / void），不会返回 uuid。若需要同时拿到原操作结果与本次写入历史记录的 uuid，可改用对应的 *AndGetHistoryId 方法：它们与原方法行为完全一致，返回值类型为 DslOpWithHistoryIdsResult<T>（result 为原方法返回值，historyIds 为本次写入的 uuid 列表）。当本次操作未写入历史（doNotPushHistory: true、无实际变更或提前返回）时 historyIds 为 []；单次操作通常返回含一个 uuid 的数组。

原方法取 uuid 的方法返回值
addaddAndGetHistoryIdPromise<DslOpWithHistoryIdsResult<MNode | MNode[]>>
removeremoveAndGetHistoryIdPromise<DslOpWithHistoryIdsResult<void>>
updateupdateAndGetHistoryIdPromise<DslOpWithHistoryIdsResult<MNode | MNode[]>>
moveLayermoveLayerAndGetHistoryIdPromise<DslOpWithHistoryIdsResult<void>>
moveToContainermoveToContainerAndGetHistoryIdPromise<DslOpWithHistoryIdsResult<MNode | MNode[]>>
dragTodragToAndGetHistoryIdPromise<DslOpWithHistoryIdsResult<void>>

dataSourceService / codeBlockService 也提供了同名约定的 *AndGetHistoryId 方法，返回值约定相同（result + historyIds）。

拿到 uuid 后，可在需要时按 uuid「回滚」对应的历史记录（类 git revert 语义，详见历史记录面板）。相比按 index 回滚，uuid 不会随栈内步骤增删而变化，更适合业务侧持有引用后再回滚：

查看 HistoryOpOptions / DslOpOptions / DslOpWithHistoryIdsResult / HistoryOpSource 类型定义
ts
/**
 * 历史记录写入相关的通用配置（codeBlock / dataSource / editor 共用）
 * - doNotPushHistory: 操作完成后是否不要将本次操作压入历史栈（撤销/重做记录），默认 false
 * - historyDescription: 入栈时附带的人类可读描述，用于历史面板展示；不影响 undo/redo 行为，缺省时面板会自动生成描述
 * - historySource: 操作途径，取值见 {@link HistoryOpSource}（画布 / 树面板 / 组件面板 / 配置面板 / 源码编辑器 / 右键菜单 / 工具栏 / 快捷键 / 回滚 / 接口 等），用于历史面板展示与埋点；不影响 undo/redo 行为
 */
export interface HistoryOpOptions {
  doNotPushHistory?: boolean;
  historyDescription?: string;
  historySource?: HistoryOpSource;
}
ts
/**
 * DSL 修改类操作的通用配置
 * - doNotSelect: 操作后是否不要自动触发选中（不调用 this.select / this.multiSelect / stage.select / stage.multiSelect）
 * - doNotSwitchPage: 操作若会引发当前页面切换（如新增 / 删除 / 跨页移动），是否跳过这次切换
 */
export interface DslOpOptions extends HistoryOpOptions {
  doNotSelect?: boolean;
  doNotSwitchPage?: boolean;
}
ts
/** *AndGetHistoryId 系列方法返回值：原操作结果 + 本次写入历史记录的 uuid 列表（未入栈时为 \`[]\`）。 */
export type DslOpWithHistoryIdsResult<T> = {
  result: T;
  historyIds: string[];
};
ts
/**
 * 历史记录的「操作途径」——标记本次变更由哪条交互入口触发，仅用于历史面板展示 / 业务埋点，
 * 不影响 undo/redo 行为。缺省（未传）时 UI 视为「未知」。
 *
 * - \`stage\`：画布（拖拽 / 缩放 / 排序等舞台直接操作）
 * - \`tree\`：树形面板（图层 / 数据源 / 代码块等树形结构里的拖拽 / 菜单操作）
 * - \`component-panel\`：组件面板（左侧组件列表点击 / 拖拽新增组件）
 * - \`props\`：配置面板表单（属性表单字段编辑）
 * - \`code\`：源码编辑器（配置面板「源码」面板里直接编辑 JSON/代码后保存）
 * - \`stage-contextmenu\`：画布右键菜单（舞台上节点的右键上下文菜单）
 * - \`tree-contextmenu\`：树面板右键菜单（图层 / 数据源 / 代码块等树形列表上的右键上下文菜单）
 * - \`toolbar\`：工具栏菜单（顶部导航工具栏按钮）
 * - \`shortcut\`：键盘快捷键
 * - \`rollback\`：历史回滚（历史面板里对某条历史「回滚」，反向应用为一条新记录，类 git revert）
 * - \`api\`：代码 / 接口调用（程序化触发）
 * - \`ai\`：AI 生成 / 智能助手触发的变更
 * - \`unknown\`：未知来源
 *
 * 通过 \`(string & {})\` 允许业务侧扩展自定义途径字符串，同时保留内置值的自动补全。
 */
export type HistoryOpSource =
  | 'initial'
  | 'stage'
  | 'tree'
  | 'component-panel'
  | 'props'
  | 'code'
  | 'root-code'
  | 'stage-contextmenu'
  | 'tree-contextmenu'
  | 'toolbar'
  | 'shortcut'
  | 'rollback'
  | 'api'
  | 'ai'
  // 同步
  | 'sync'
  | 'unknown'
  | (string & {});

get ​

js
import { editorService } from "@tmagic/editor";

const node = editorService.get("node");

set ​

js
import { editorService } from "@tmagic/editor";

const node = editorService.get("node");

editorService.set("node", {
  ...node,
  name: "new name",
});

getNodeInfo ​

TIP

如果raw为false，对获取到的对象进行操作会触发vue响应式处理

js
import { editorService } from "@tmagic/editor";

const info = editorService.getNodeInfo("text_123");

console.log(info.node);
console.log(info.parent);
console.log(info.page);

getNodeById ​

js
import { editorService } from "@tmagic/editor";

const node = editorService.getNodeById("text_123");

console.log(node);

getParentById ​

js
import { editorService } from "@tmagic/editor";

const parent = editorService.getParentById("text_123");

console.log(parent);

isOnDifferentPage ​

js
import { editorService } from "@tmagic/editor";

const otherPageNode = editorService.getNodeById("text_456");
if (editorService.isOnDifferentPage(otherPageNode)) {
  console.log("该节点在其它页面，操作会触发页面切换");
}

getLayout ​

js
import { editorService } from "@tmagic/editor";

const parent = editorService.getParentById("text_123");
editorService.getLayout(parent).then((layout) => {
  console.log(parent);
});

select ​

js
import { editorService } from "@tmagic/editor";

editorService.select("text_123");
editorService.get("stage")?.select("text_123");

multiSelect ​

js
import { editorService } from "@tmagic/editor";

editorService.multiSelect(["text_123", "button_123"]);
editorService.get("stage")?.multiSelect(["text_123", "button_123"]);

selectNextNode ​

selectNextPage ​

selectRoot ​

highlight ​

js
import { editorService } from "@tmagic/editor";

editorService.highlight("text_123");

doAdd ​

add ​

doRemove ​

remove ​

doUpdate ​

update ​

sort ​

copy ​

复制组件节点或节点集合

通过storageService.setItem,将组件节点配置存储到localStorage中

copyWithRelated ​

doPaste ​

粘贴前置操作：返回分配了新id以及校准了坐标的配置

paste ​

粘贴组件节点或节点集合

通过storageService.getItem,从localStorage中获取节点，然后添加到当前容器中

doAlignCenter ​

alignCenter ​

水平居中组件或者组件集合，仅在流式布局下有效

TIP

与doAlignCenter的区别：

alignCenter可以支持一次水平居中多个组件，alignCenter是通过调用doAlignCenter来获取到已设置好水平居中的位置信息的节点，然后调用update更新。

moveLayer ​

moveToContainer ​

dragTo ​

addAndGetHistoryId ​

js
import { editorService } from "@tmagic/editor";

const { result, historyIds } = await editorService.addAndGetHistoryId(
  { type: "text", text: "hello" },
  parent,
  { historySource: "api" },
);
console.log(result); // 新增节点
console.log(historyIds); // 本次新增对应的历史记录 uuid 列表，或 []

removeAndGetHistoryId ​

updateAndGetHistoryId ​

moveLayerAndGetHistoryId ​

moveToContainerAndGetHistoryId ​

dragToAndGetHistoryId ​

revertPageStepById ​

js
import { editorService } from "@tmagic/editor";

// 执行操作时拿到本次历史记录 uuid
const { historyIds } = await editorService.addAndGetHistoryId({ type: "text", text: "hello" });

// 之后任意时机按 uuid 回滚（支持单个或整批 historyIds）
await editorService.revertPageStepById(historyIds);

undo ​

redo ​

move ​

resetModifiedNodeId ​

重置当前记录的修改过的节点id记录，通常用于保存之后

setInvalidNode ​

js
import { editorService } from "@tmagic/editor";

// 标记 text_123 的属性表单校验错误
editorService.setInvalidNode("text_123", "props", "标题不能为空");

deleteInvalidNode ​

getInvalidNodeIds ​

js
import { editorService } from "@tmagic/editor";

// 保存前检查是否存在校验错误的组件
const invalidNodeIds = editorService.getInvalidNodeIds();
if (invalidNodeIds.size > 0) {
  const names = [...invalidNodeIds.keys()].map((id) => {
    const node = editorService.getNodeById(id);
    return node?.name ? \`\${node.name}(\${id})\` : \`\${id}\`;
  });
  console.warn(\`以下组件存在配置校验错误，请修复后再保存：\${names.join("、")}\`);
}

getInvalidNodeInfo ​

resetInvalidNodeId ​

resetState ​

清空state

destroy ​

usePlugin ​

每个支持扩展的方法都支持定制before、after两个hook来干预原有方法的行为，before可以用于修改传入参数，after可以用于修改返回的值

js
import { editorService } from "@tmagic/editor";

editorService.usePlugin({
  // 添加组件的时候设置一个添加时间
  beforeDoAdd: (config, parent) => {
    config.addTime = new Date().getTime();

    return [config, parent];
  },
});

removeAllPlugins ​

删掉当前设置的所有扩展

`,140)]])}var s=t(a,[[`render`,o]]);export{i as __pageData,s as default};