steedos-tabs

name

steedos-tabs

description

Navigation tabs (.tab.yml) for Steedos application sidebars. TRIGGER: .tab.yml files; sidebar navigation item; tab types (object, page, url, analytics_dashboard); link to object list view, micro page, analytics dashboard, external/internal URL; tab icon, label, desktop/mobile, is_use_iframe, is_new_window, license, permission_set visibility; tab not appearing. SKIP: application container → steedos-applications; page content → steedos-pages.

Steedos Tabs | Steedos 标签页

Overview | 概述

Tabs define the navigation items that appear in an application's sidebar. Each tab is a .tab.yml file that points to an object, a micro page, or a URL. Tabs are referenced by name in the application's tabs array.

标签页定义了应用程序侧边栏中的导航项。每个标签页是一个 .tab.yml 文件，指向一个对象、微页面或 URL。标签页通过名称在应用程序的 tabs 数组中引用。

File Format | 文件格式

• File Extension: .tab.yml
• Location: main/default/tabs/
• Format: YAML
• Naming: [tab_name].tab.yml

Tab Types | 标签页类型

1. Object Tab | 对象标签页

Displays an object's list view. Most common tab type.

显示对象的列表视图。最常用的标签页类型。

name: object_contract
desktop: true
icon: collection
label: 合同
mobile: true
object: contract
permissions: []
type: object

2. Page Tab | 微页面标签页

Renders an Amis micro page (type: page in .page.yml). Used for custom UIs, landing pages, and standalone app pages. NOT for dashboards — use analytics_dashboard for that.

渲染 Amis 微页面（.page.yml 中 type: page）。用于自定义界面、落地页和独立应用页面。不用于仪表盘 — 仪表盘请使用 analytics_dashboard。

name: page_app_launcher
desktop: true
icon: agent_home
is_new_window: false
is_use_iframe: false
label: 应用
mobile: true
page: app_launcher
permissions: []
type: page

3. Analytics Dashboard Tab | 仪表盘标签页

Links to an analytics dashboard (仪表盘). This is the correct type for dashboards — NOT type: page.

指向一个分析仪表盘。这是仪表盘的正确类型，不要用 type: page。

name: dashboard_sales
desktop: true
icon: dashboard
is_new_window: false
is_use_iframe: false
label: 销售仪表盘
mobile: false
analytics_dashboard: sales_dashboard
permissions: []
type: analytics_dashboard

4. URL Tab | URL 标签页

Opens an internal or external URL. Can use iframe or new window.

打开内部或外部 URL。可使用 iframe 或新窗口。

name: admin_swagger
desktop: true
icon: data_model
is_new_window: true
is_use_iframe: true
label: OpenAPI
mobile: true
permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'off'
    permission_set: user
type: url
url: /api/v6/

Field Reference | 字段参考

Required Fields | 必需字段

name (String) — ⚠️ Required, MUST NOT be omitted

Unique identifier for the tab. This is the name referenced in the application's tabs array.

标签页的唯一标识符。这是在应用程序 tabs 数组中引用的名称。不能省略。

name: object_contract

type (String)

⚠️ MUST be one of: object, page, url, analytics_dashboard. No other values are valid. 严禁使用其他值。

Value	Use Case
object	Object list view
page	Amis micro page (standalone custom UI, NOT dashboards)
analytics_dashboard	Analytics dashboard / 仪表盘
url	Internal or external URL

type: object
type: page
type: analytics_dashboard
type: url

label (String)

Display name shown in the sidebar navigation.

侧边栏导航中显示的名称。

label: 合同管理

Type-Specific Fields | 类型特定字段

object (String) — for type: object

The object API name to display.

⚠️ CRITICAL: The field name is object, NOT object_name. Using object_name is a common mistake and will NOT work.

⚠️ 重要：字段名为 object，不是 object_name。使用 object_name 是常见错误，不会生效。

type: object
object: contracts     # ✅ Correct
# object_name: contracts  # ❌ WRONG — do NOT use object_name

page (String) — for type: page

The micro page name to render. This must be an Amis micro page (type: page in .page.yml). Do NOT use this for dashboards — use type: analytics_dashboard instead.

微页面的名称。必须是 Amis 微页面（.page.yml 中 type: page）。不要用于仪表盘 — 仪表盘请使用 type: analytics_dashboard。

type: page
page: app_launcher

analytics_dashboard (String) — for type: analytics_dashboard

The analytics dashboard name to display. Use this for all dashboards (仪表盘).

要显示的分析仪表盘名称。所有仪表盘都使用此类型。

type: analytics_dashboard
analytics_dashboard: sales_dashboard

url (String) — for type: url

The URL to open. Supports template variables.

要打开的 URL。支持模板变量。

type: url
url: /app/admin/space_users/view/${context.user.spaceUserId}

URL Template Variables | URL 模板变量:

Variable	Description
${context.user.spaceUserId}	Current user's space_users ID

Optional Fields | 可选字段

desktop (Boolean)

Whether the tab is visible on desktop. Default: true.

desktop: true

mobile (Boolean)

Whether the tab is visible on mobile. Default: true.

mobile: true

icon (String)

⚠️ MUST be a valid SLDS icon name from the objects skill Valid Icon Values list. Do NOT invent icon names. If no icon matches, use custom or record.

⚠️ 必须为对象 skill 有效图标列表中的有效 SLDS 图标名称，严禁编造。如无匹配，使用 custom 或 record。

Salesforce Lightning Design System icon name.

icon: contract
icon: agent_home
icon: data_model

is_new_window (Boolean)

Whether to open in a new browser window/tab. Default: false.

是否在新浏览器窗口/标签页中打开。默认：false。

is_new_window: true

is_use_iframe (Boolean)

Whether to render the content in an iframe within the app. Default: false. Typically used with URL tabs.

是否在应用内使用 iframe 渲染内容。默认：false。通常与 URL 标签页配合使用。

is_use_iframe: true

locked (Boolean)

Whether the tab configuration is locked from editing in the UI.

locked: false

license (Array)

License tiers required to access this tab.

访问此标签页所需的许可证级别。

license:
  - platform-professional
  - platform-enterprise

Permissions | 权限

Control tab visibility per permission set. Each entry has permission (⚠️ MUST be 'on' or 'off', no other values) and permission_set.

按权限集控制标签页可见性。每个条目有 permission（⚠️ 必须为 'on' 或 'off'）和 permission_set。

permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'on'
    permission_set: user
  - permission: 'off'
    permission_set: customer
  - permission: 'off'
    permission_set: supplier
  - permission: 'off'
    permission_set: organization_admin
  - permission: 'off'
    permission_set: workflow_admin

An empty permissions: [] means the tab is visible to all users.

空的 permissions: [] 表示标签页对所有用户可见。

Complete Examples | 完整示例

Object Tab — Business Object | 对象标签页 — 业务对象

name: object_pepsico_material
desktop: true
icon: contact_list
label: 材料素材
mobile: true
object: pepsico_material
permissions: []
type: object

Object Tab — Admin Only | 对象标签页 — 仅管理员

name: admin_apps
desktop: true
icon: apps
is_new_window: false
label: 应用程序
mobile: true
permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'off'
    permission_set: user
  - permission: 'off'
    permission_set: customer
  - permission: 'off'
    permission_set: supplier
  - permission: 'off'
    permission_set: organization_admin
  - permission: 'off'
    permission_set: workflow_admin
type: object
object: apps

Page Tab — Custom UI | 微页面标签页 — 自定义界面

name: page_app_store
desktop: true
icon: product_consumed
is_new_window: false
is_use_iframe: false
label: App Store
mobile: true
permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'off'
    permission_set: user
type: page
page: app_store

Analytics Dashboard Tab | 仪表盘标签页

name: dashboard_sales
desktop: true
icon: dashboard
is_new_window: false
is_use_iframe: false
label: 销售仪表盘
mobile: false
permissions: []
type: analytics_dashboard
analytics_dashboard: sales_dashboard

URL Tab — External Tool | URL 标签页 — 外部工具

name: nodered
desktop: true
icon: incident
is_new_window: true
is_use_iframe: false
label: Node-RED
locked: false
mobile: true
permissions:
  - permission: 'off'
    permission_set: user
type: url
url: /flows

URL Tab — Embedded Dashboard | URL 标签页 — 嵌入仪表板

name: material_kanban
desktop: true
icon: app
is_new_window: false
is_use_iframe: true
label: 看板
locked: false
mobile: false
permissions: []
type: url
url: /analytics/embed/dashboard/6788be6a41162b06257df7a9#titled=false&bordered=false

URL Tab — Dynamic URL with Context | URL 标签页 — 带上下文的动态 URL

name: admin_personal_information
desktop: true
icon: user_role
is_new_window: false
label: 个人资料
mobile: true
permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'on'
    permission_set: user
type: url
url: /app/admin/space_users/view/${context.user.spaceUserId}

Tab with License Restriction | 带许可证限制的标签页

name: admin_ai_chatbots
desktop: true
icon: live_chat
is_new_window: false
label: Chatbots
mobile: true
permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'off'
    permission_set: user
type: object
object: ai_chatbots
license:
  - platform-professional
  - platform-enterprise

Relationship with Applications | 与应用程序的关系

Tabs are referenced in .app.yml files via the tabs array. The tab name is used as the reference key.

标签页通过 tabs 数组在 .app.yml 文件中引用。标签页的 name 作为引用键。

# In application .app.yml
tabs:
  - page_app_launcher
  - core_announcements
  - core_tasks

tab_items:
  page_app_launcher:
    group: ''
    index: 1
  core_announcements:
    group: 协作
    index: 2
  core_tasks:
    group: 协作
    index: 3

tab_groups:
  - group_name: 协作
    default_open: true

When an application's tabs array includes a name that matches no .tab.yml file, the system treats it as an implicit object tab (directly using the name as the object API name).

当应用程序的 tabs 数组包含的名称没有匹配的 .tab.yml 文件时，系统将其视为隐式对象标签页（直接将名称作为对象 API 名称）。

File Location | 文件位置

steedos-packages/
└── my-package/
    └── main/
        └── default/
            ├── tabs/
            │   ├── object_contract.tab.yml
            │   ├── page_dashboard.tab.yml
            │   └── admin_settings.tab.yml
            └── applications/
                └── my_app.app.yml

Naming Conventions | 命名约定

Pattern	Use Case	Example
object_{name}	Object tabs for business objects	object_contract
admin_{name}	Admin-only tabs	admin_apps
page_{name}	Micro page tabs (Amis custom UI)	page_app_launcher
dashboard_{name}	Analytics dashboard tabs	dashboard_sales
core_{name}	Core platform tabs	core_tasks

Best Practices | 最佳实践

1. Permission Configuration

Always explicitly set permissions for admin-only tabs:

始终为仅管理员标签页明确设置权限：

permissions:
  - permission: 'on'
    permission_set: admin
  - permission: 'off'
    permission_set: user

For tabs visible to all users, use empty permissions:

对所有用户可见的标签页，使用空权限：

permissions: []

2. iframe vs New Window

• Use is_use_iframe: true for embedded dashboards and tools that should stay within the app

• Use is_new_window: true for external tools like Node-RED that need their own window

• Don't combine both — choose one approach

• 使用 is_use_iframe: true 嵌入仪表板和需要留在应用内的工具

• 使用 is_new_window: true 用于像 Node-RED 这样需要独立窗口的外部工具

• 不要同时使用两者 — 选择一种方式

3. Mobile Visibility

Set mobile: false for tabs that don't work well on mobile (e.g., complex dashboards, iframe embeds):

对不适合移动端的标签页设置 mobile: false（如复杂仪表板、iframe 嵌入）：

desktop: true
mobile: false

Troubleshooting | 故障排除

Issue: Tab not appearing in sidebar

Solutions:

1. Verify the tab name is listed in the application's tabs array
2. Check permissions — user must have permission: 'on' for their permission_set
3. Ensure desktop: true (or mobile: true for mobile)
4. Check license restrictions if present

Issue: URL tab showing blank

Solutions:

1. For iframe embeds, ensure is_use_iframe: true
2. Check the target URL allows iframe embedding (X-Frame-Options)
3. Verify the URL path is correct and accessible

Issue: Page tab not rendering

Solutions:

1. Verify the page value matches an existing micro page name
2. Ensure the micro page .page.yml and .page.amis.json files exist
3. Check page permissions

References | 参考资料

• Applications — how tabs are used in app configuration
• Micro Pages — creating pages for type: page tabs
• Dashboards — creating dashboards for type: analytics_dashboard tabs
• Object Permissions — permission sets referenced in tab permissions
• Salesforce Lightning Icons