跳转到主要内容
命令菜单项 是用户与前端组件之间的桥梁。 它会在 Twenty 的命令菜单（Cmd+K）中注册该组件，并可选地将其作为页面右上角的固定快速操作按钮。
src/command-menu-items/open-dashboard.command-menu-item.ts
import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  label: 'Open Dashboard',
  shortLabel: 'Dashboard',
  icon: 'IconLayoutDashboard',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

​
配置字段

字段必填描述
universalIdentifier是该命令的稳定唯一 ID
label是在命令菜单（Cmd+K）中显示的完整标签
frontComponentUniversalIdentifier是此命令打开的前端组件的 universalIdentifier
shortLabel否固定的快速操作按钮上显示的较短标签
icon否显示在标签旁边的图标名称（例如 'IconBolt'、'IconSend'）
isPinned否为 true 时，会将该命令显示为页面右上角的快速操作按钮
availabilityType否控制命令出现的位置：‘GLOBAL’（始终可用）、‘RECORD_SELECTION’（仅在选择了记录时），或 ‘FALLBACK’（当没有其他命令匹配时显示）
availabilityObjectUniversalIdentifier否将该命令限制在特定对象类型的页面上（例如仅在 Company 记录上）
conditionalAvailabilityExpression否用于动态控制可见性的布尔表达式（见下文）

​
无头命令

与无头前端组件配对的命令菜单项，是交付一键操作（运行代码、导航，或确认并执行）的惯用方式。 Front Components 页面介绍了处理“执行操作并卸载”模式的 SDK Command 组件（Command、CommandLink、CommandModal、CommandOpenSidePanelPage）。 一个典型的流程：
src/front-components/run-action.tsx
import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/command';
import { CoreApiClient } from 'twenty-sdk/clients';

const RunAction = () => {
  const execute = async () => {
    const client = new CoreApiClient();
    await client.mutation({
      createTask: {
        __args: { data: { title: 'Created by my app' } },
        id: true,
      },
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
  name: 'run-action',
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
});
src/command-menu-items/run-action.command-menu-item.ts
import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
  label: 'Run my action',
  icon: 'IconPlayerPlay',
  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
});

​
条件可用性表达式

通过 conditionalAvailabilityExpression 字段，您可以基于当前页面上下文控制命令何时可见。 从 twenty-sdk 导入带类型的变量和运算符来构建表达式：
src/command-menu-items/bulk-update.command-menu-item.ts
import {
  defineCommandMenuItem,
  objectPermissions,
  everyEquals,
} from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: '...',
  label: 'Bulk Update',
  availabilityType: 'RECORD_SELECTION',
  frontComponentUniversalIdentifier: '...',
  conditionalAvailabilityExpression: everyEquals(
    objectPermissions,
    'canUpdateObjectRecords',
    true,
  ),
});
RECORD_SELECTION 已经意味着非空选择 — 仅在需要表达具体数量时使用 numberOfSelectedRecords（例如 >= 2）。

​
上下文变量

这些变量表示页面的当前状态：
变量类型描述
pageTypestring当前页面类型（例如 ‘RecordIndexPage’、‘RecordShowPage’）
isInSidePanelboolean组件是否在侧边栏中渲染
numberOfSelectedRecordsnumber当前选中的记录数量
isSelectAllboolean“全选”是否已激活
selectedRecordsarray已选记录对象
favoriteRecordIdsarray已收藏记录的 ID
objectPermissionsobject当前对象类型的权限
targetObjectReadPermissionsobject目标对象的读取权限
targetObjectWritePermissionsobject目标对象的写入权限
featureFlagsobject当前启用的功能标志
objectMetadataItemobject当前对象类型的元数据
hasAnySoftDeleteFilterOnViewboolean当前视图是否包含软删除筛选器

​
运算符

将变量组合为布尔表达式：
运算符描述
isDefined(value)当该值不是 null/undefined 时为 true
isNonEmptyString(value)当该值为非空字符串时为 true
includes(array, value)当数组包含该值时为 true
includesEvery(array, prop, value)当每个条目的属性都包含该值时为 true
every(array, prop)当该属性在每个条目上都为 truthy 时为 true
everyDefined(array, prop)当该属性在每个条目上都已定义时为 true
everyEquals(array, prop, value)当该属性在每个条目上都等于该值时为 true
some(array, prop)当至少一个条目上的该属性为 truthy 时为 true
someDefined(array, prop)当至少一个条目上的该属性已定义时为 true
someEquals(array, prop, value)当至少一个条目上的该属性等于该值时为 true
someNonEmptyString(array, prop)当至少一个条目上的该属性为非空字符串时为 true
none(array, prop)当该属性在每个条目上都为 falsy 时为 true
noneDefined(array, prop)当该属性在每个条目上都为 undefined 时为 true
noneEquals(array, prop, value)当该属性在任意条目上都不等于该值时为 true