命令菜单项

命令菜单项 是用户与前端组件之间的桥梁。它会在 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`

概览

应用

接口

自托管

贡献

配置字段

无头命令

条件可用性表达式

上下文变量

运算符

​配置字段

​无头命令

​条件可用性表达式

​上下文变量

​运算符

配置字段

无头命令

条件可用性表达式

上下文变量

运算符