命令菜单项

使用 defineCommandMenuItem 将前端组件暴露为快速操作和命令菜单（Cmd+K）条目。

命令菜单项 是用户与前端组件之间的桥梁。 它会在 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',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

​

配置字段

字段	必填	描述
universalIdentifier	是	该命令的稳定唯一 ID
label	是	在命令菜单（Cmd+K）中显示的完整标签
frontComponentUniversalIdentifier	是	此命令打开的前端组件的 universalIdentifier
shortLabel	否	固定的快速操作按钮上显示的较短标签
icon	否	已弃用 — 该设置会被应用程序图标取代并被忽略；如设置，构建时将发出警告
isPinned	否	为 true 时，会将该命令显示为页面右上角的快速操作按钮
availabilityType	否	控制命令出现的位置：'GLOBAL'（始终可用）、'GLOBAL_OBJECT_CONTEXT'（仅在具有对象上下文的页面上——索引页和记录页）、'RECORD_SELECTION'（仅在选择了记录时），或 'FALLBACK'（当没有其他命令匹配时显示）
availabilityObjectUniversalIdentifier	否	将该命令限制在特定对象类型的页面上（例如仅在 Company 记录上）
conditionalAvailabilityExpression	否	用于动态控制可见性的布尔表达式（见下文）

​

无头命令

与无头前端组件配对的命令菜单项，是交付一键操作（运行代码、导航，或确认并执行）的惯用方式。 Front Components 页面介绍了处理“执行操作并卸载”模式的 SDK Command 组件（Command、CommandLink、CommandModal、CommandOpenSidePanelPage）。

一个典型流程：一个 headless 组件会渲染 <Command execute={...} />（参见完整示例），并且命令菜单项会指向它：

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',
  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）。

​

上下文变量

这些变量表示页面的当前状态：

变量	类型	描述
pageType	string	当前页面类型（例如 ‘RecordIndexPage’、‘RecordShowPage’）
isInSidePanel	boolean	组件是否在侧边栏中渲染
numberOfSelectedRecords	number	当前选中的记录数量
isSelectAll	boolean	“全选”是否已激活
selectedRecords	array	已选记录对象
favoriteRecordIds	array	已收藏记录的 ID
objectPermissions	object	当前对象类型的权限
targetObjectReadPermissions	object	目标对象的读取权限
targetObjectWritePermissions	object	目标对象的写入权限
featureFlags	object	当前启用的功能标志
objectMetadataItem	object	当前对象类型的元数据
hasAnySoftDeleteFilterOnView	boolean	当前视图是否包含软删除筛选器

​

运算符

将变量组合为布尔表达式：

运算符	描述
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