@nocobase/plugin-ai 2.2.0-alpha.7 → 2.2.0-alpha.9

package/dist/ai/docs/nocobase/file-manager/stable-url.md

@@ -0,0 +1,87 @@
+---
+pkg: '@nocobase/plugin-file-manager'
+title: "Stable URL (proxy URL)"
+description: "Explains NocoBase stable file URLs, access permissions, redirects, temporary Office preview URLs, and behavior across file-related features."
+keywords: "stable URL,proxy URL,permanent URL,file access,file permissions,Office preview,NocoBase"
+---
+
+# Stable URL
+
+Files managed by a NocoBase storage engine are accessed through a **stable URL**. The URL first reaches NocoBase, where the file record and access permissions are checked, and then redirects to the actual URL generated by the storage engine.
+
+## URL format
+
+```text
+/files/<app>/<dataSource>/<collection>/<id><extname>
+```
+
+For example:
+
+```text
+/files/main/main/attachments/42.pdf
+```
+
+When `APP_PUBLIC_PATH=/nocobase` is configured, the URL starts with `/nocobase/files/`. The path identifies the app, data source, file collection, record ID, and extension. The ID and extension cannot be changed after creation, which keeps the URL stable for the lifetime of the record.
+
+## URL variants
+
+| Purpose | URL | Behavior |
+|---|---|---|
+| Open or embed | `/files/.../42.pdf` | Checks permission and redirects to the actual file URL |
+| Preview | `/files/.../42.png?preview=1` | Redirects to the preview or thumbnail URL |
+| Download | `/files/.../42.pdf?download=1` | Redirects with download semantics |
+| Office preview | `/files/.../42.xlsx?temporaryAccessToken=...` | Allows Microsoft Office Online Viewer to fetch one file for a short time |
+
+:::tip
+
+Use the `url` and `preview` values returned by NocoBase. Application code normally should not construct `/files` URLs or their query parameters.
+
+:::
+
+## Behavior across NocoBase
+
+- Attachment fields and file collections return stable URLs after upload and when records are queried
+- [HTTP API](./http-api.md) responses no longer expose local paths, storage domains, or presigned download URLs
+- Markdown uploads store the stable URL, including files in private S3, OSS, COS, or S3 Pro storage
+- Attachment URL fields store a stable URL for managed uploads, while manually entered external URLs remain unchanged
+- Image, PDF, audio, video, and text previews use the stable URL and the current NocoBase login session
+- Public forms grant limited access to files uploaded in the current public-form browser session; this does not create a generally public link
+
+## Office preview
+
+Microsoft Office Online Viewer fetches the file from Microsoft servers and cannot use the user's NocoBase cookie. When the user opens an Office preview, NocoBase first checks the user's file permission and then issues a temporary URL for that file.
+
+The URL is valid for 10 minutes by default. `TEMPORARY_FILE_ACCESS_EXPIRES_IN` may be set from 5 to 10 minutes. It is requested again when the preview is reopened and must never be saved in an attachment field, Markdown content, or a business record.
+
+## Permissions and redirects
+
+Logged-in requests use the current app credentials and role. After permission is granted, NocoBase responds with `302` and redirects to the local or object-storage URL.
+
+Stable URLs support `GET` and `HEAD`. Other methods return `405`. A command-line client must follow redirects, for example:
+
+```bash
+curl -L \
+  -H "Authorization: Bearer <JWT>" \
+  "https://example.com/files/main/main/attachments/42.pdf"
+```
+
+## Important notes
+
+- Stable does not mean public; recipients still need permission to view the file
+- Deleting the record or changing its app, data source, or collection context invalidates the old URL
+- Do not persist `temporaryAccessToken` or use it as a sharing link
+- Do not cache the `302 Location` as a permanent URL because storage signatures can expire
+- Do not rewrite the app, data source, collection, ID, or extension in the path
+- Reverse proxies must forward the `/files/` route under `APP_PUBLIC_PATH` to NocoBase. For subpath deployments, keep a compatible root-level `/files/` route as well. Configurations generated by the NocoBase CLI include both routes automatically
+- Deployments where the pages access the API cross-origin (with `API_BASE_URL` pointing to another origin) must add the page origin to `CORS_ORIGIN_WHITELIST`; otherwise the login cookie is never stored and stable URLs return `403` for lack of credentials. See [Environment Variables](../get-started/installation/env.md#api_base_url)
+- Use a different `hostname` for each independent NocoBase service instead of separating services only by port. Browser cookies are not isolated by port; see [Production Environment Deployment](../get-started/deployment/production.md)
+- Sub-apps in the same NocoBase deployment are distinguished by app name and do not need separate hostnames. However, an independent service on another port still needs hostname isolation if it contains a main app or sub-app with the same name
+- Custom `fetch()` code may also need object-storage CORS after following the redirect
+- Use a dedicated sharing or public-access feature when a long-lived public link is required
+
+## Related links
+
+- [HTTP API](./http-api.md) — Upload and query files through the API
+- [File preview](./file-preview/index.md) — Preview behavior for supported file types
+- [Office file preview](./file-preview/ms-office.md) — Configure Microsoft Office Online Viewer
+- [Storage engines](./storage/index.md) — Configure local and object storage

package/dist/ai/docs/nocobase/get-started/deployment/production.md

@@ -2,12 +2,34 @@
 
 When deploying NocoBase in a production environment, installing dependencies can be cumbersome due to differences in build methods across various systems and environments. For a complete functional experience, we recommend deploying with **Docker**. If your system environment cannot use Docker, you can also deploy using **create-nocobase-app**.
 
-:::warning
+:::warning Note
 
 It is not recommended to deploy directly from source code in a production environment. The source code has many dependencies, is large in size, and a full compilation has high CPU and memory requirements. If you must deploy from source code, it is recommended to first build a custom Docker image and then deploy it.
 
 :::
 
+:::warning Note
+
+If you deploy multiple independent NocoBase services, use a different `hostname` for each service, such as separate subdomains. Do not distinguish services only by port, for example `https://example.com:13000` and `https://example.com:14000`.
+
+NocoBase uses cookies to maintain login state and [file access permissions](../../file-manager/stable-url.md). Browsers do not isolate cookies by port, so services on different ports under the same `hostname` may share cookies with the same name. This can overwrite login state or cause file preview and download authorization failures.
+
+Sub-apps within the same NocoBase deployment are outside this restriction. Login cookies are distinguished by app name, so the main app and differently named sub-apps can share one `hostname`.
+
+However, independent services still need isolation. If another NocoBase service runs on a different port under the same `hostname` and contains a main app or sub-app with the same name, its cookies may still conflict.
+
+Use addresses such as `app1.example.com` and `app2.example.com`, then route them to different NocoBase services through Nginx or Caddy.
+
+:::
+
+## Separated Frontend / Cross-Origin API Access
+
+Prefer keeping the pages and the API on the same origin: use a reverse proxy under one domain to forward `${APP_PUBLIC_PATH}api/` and `${APP_PUBLIC_PATH}files/` to the NocoBase service, and leave `API_BASE_URL` empty.
+
+If the pages must access the API cross-origin (with `API_BASE_URL` pointing to another origin), add the page origin to `CORS_ORIGIN_WHITELIST`. Otherwise the browser ignores `Set-Cookie` in API responses, the login cookie is never stored, and preview and download through stable file URLs fail authorization.
+
+Also note that cookies are stored per `hostname`: when the pages and the API use entirely different domains, requests to `/files/` from the page domain will not carry the login cookie stored under the API domain. Such deployments should switch to a same-origin reverse proxy. See [Environment Variables](../installation/env.md#api_base_url).
+
 ## Deployment Process
 
 For production environment deployment, you can refer to the existing installation and upgrade steps.
@@ -39,4 +61,4 @@ In a production environment, it is recommended to manage static assets with a pr
 Depending on the installation method, you can use the following commands to manage the NocoBase process:
 
 - [docker compose](./common-commands/docker-compose.md)
-- [pm2](./common-commands/pm2.md)
+- [pm2](./common-commands/pm2.md)

package/dist/ai/docs/nocobase/get-started/installation/docker-caddy.mdx

@@ -94,6 +94,7 @@ services:
 - `NOCOBASE_PROXY_UPSTREAM_HOST=app` lets the Caddy container reach the `app` service through the Compose network
 - `./storage` must be mounted into both the `app` and `caddy` containers so they can share proxy config, static assets, and uploaded files
 - The `caddy` container should wait until `nocobase.caddy` is generated, then link it to `/etc/caddy/Caddyfile` with `ln -sf`
+- The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
 - Expose only the Caddy container port to the host. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
 
 ## If you use a local host Caddy
@@ -169,6 +170,8 @@ sudo systemctl reload caddy
 
 If your host Caddy does not use `/etc/caddy/Caddyfile`, replace the link target with your own config path. Usually it is safer to keep `nocobase.caddy` as the main entry file instead of copying its content manually.
 
+If you maintain Caddy yourself instead of using the generated config, make sure `/files/*` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Caddy Reverse Proxy](../../nocobase-cli/production/reverse-proxy/caddy.md) for a complete example.
+
 ## Related links
 
 - [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup

package/dist/ai/docs/nocobase/get-started/installation/docker-nginx.mdx

@@ -95,6 +95,7 @@ services:
 - `NOCOBASE_PROXY_UPSTREAM_HOST=app` lets the Nginx container reach the `app` service through the Compose network
 - `./storage` must be mounted into both the `app` and `nginx` containers so they can share proxy config, static assets, and uploaded files
 - The `nginx` container should wait until `nocobase.conf` is generated, then link it to `/etc/nginx/conf.d/default.conf` with `ln -sf`
+- The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
 - If you use an external Nginx container, let the `nginx` container handle the host port mapping. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
 
 ## If you use a local host Nginx
@@ -170,6 +171,8 @@ sudo systemctl reload nginx
 
 If your host Nginx does not use the `conf.d` directory, replace the link target with your own config path. Usually it is safer to keep `nocobase.conf` as a file included from the `http {}` context instead of copying its content manually.
 
+If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
+
 ## Related links
 
 - [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup

package/dist/ai/docs/nocobase/get-started/installation/docker.mdx

@@ -627,7 +627,7 @@ If you use the built-in Nginx image, it is usually better not to expose `13000`
 
 The following config proxies domain requests to `http://127.0.0.1:13000/`:
 
-```bash
+```nginx
 server {
     listen 80;
     server_name your_domain.com;  # Replace your_domain.com with your domain
@@ -658,6 +658,8 @@ server {
 
 If you also want to enable HTTPS, configure `443` and the certificate on the host Nginx. The NocoBase container does not need to handle certificates separately.
 
+The `location /` block in this root-path configuration also proxies `/api/`, `/ws`, and `/files/`. If you split static assets from application routes, make sure `/files/` is still forwarded to NocoBase and is not handled as a static directory.
+
 ### Subpath deployment
 
 If you want to deploy the app under a subpath, such as `https://your_domain.com/nocobase/`, configure the `APP_PUBLIC_PATH` environment variable first:
@@ -674,7 +676,7 @@ Keep the leading and trailing `/` in the path. After this is configured, the app
 
 Then configure the host Nginx with the same subpath proxy:
 
-```bash
+```nginx
 server {
     listen 80;
     server_name your_domain.com;  # Replace your_domain.com with your domain
@@ -700,10 +702,32 @@ server {
         send_timeout 600;
         proxy_buffering off;
     }
+
+    # Keep compatibility with root-level file access URLs.
+    location ^~ /files/ {
+        proxy_pass http://127.0.0.1:13000;
+        proxy_http_version 1.1;
+
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+
+        add_header Cache-Control "no-cache, no-store" always;
+
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+    }
 }
 ```
 
-The key point is that `APP_PUBLIC_PATH` and the path in `proxy_pass` must stay consistent. If either side misses `/nocobase/`, static assets and routing will usually not work correctly.
+Keep these points in mind:
+
+- `APP_PUBLIC_PATH` and the path in `proxy_pass` must stay consistent. If either side misses `/nocobase/`, static assets and routing will usually not work correctly
+- `/nocobase/files/` is forwarded by `location /nocobase/`; the compatible root-level `/files/` route must be forwarded to NocoBase separately
 
 ### Other options
 

package/dist/ai/docs/nocobase/get-started/installation/env.md

@@ -86,6 +86,39 @@ API_BASE_PATH=/api/
 
 ### API_BASE_URL
 
+Base URL the frontend uses to access the NocoBase API. Empty by default, which means the same-origin `${APP_PUBLIC_PATH}api/` is used.
+
+```bash
+API_BASE_URL=
+```
+
+Only set it to the full API address when the pages and the API service are on different origins (different protocol, domain, or port):
+
+```bash
+API_BASE_URL=https://api.example.com/api/
+```
+
+:::warning{title="Cross-origin deployments"}
+NocoBase uses cookies to maintain login state and to authorize [stable file URLs](../../file-manager/stable-url.md). When `API_BASE_URL` points to a different origin than the pages:
+
+- The page origin must be added to [`CORS_ORIGIN_WHITELIST`](#cors_origin_whitelist). Otherwise the browser ignores `Set-Cookie` in API responses, the login cookie is never stored, and cookie-dependent features such as file preview and download fail with `403`.
+- Cookies are stored per `hostname`. If the pages and the API use entirely different domains, requests to `/files/` stable URLs from the page domain will not carry the login cookie stored under the API domain, so file access still fails.
+
+Prefer serving the pages and the API from the same origin through a reverse proxy and leaving `API_BASE_URL` empty.
+:::
+
+### CORS_ORIGIN_WHITELIST
+
+Whitelist of origins allowed to access the API cross-origin with credentials (cookies). Multiple origins are separated by commas. Empty by default.
+
+```bash
+CORS_ORIGIN_WHITELIST=https://www.example.com,https://admin.example.com
+```
+
+- When not configured, only same-origin requests are treated as trusted; cross-origin requests can still call the API anonymously, but the browser is not allowed to read or write cookies for them.
+- When configured, whitelisted origins receive an exact `Access-Control-Allow-Origin` echo and `Access-Control-Allow-Credentials: true`, which lets the browser send and store login cookies on cross-origin requests.
+- The sign-in API validates the request `Origin` / `Referer`; cross-origin sign-in requests from origins outside the whitelist are rejected with `403`.
+
 ### CLUSTER_MODE
 
 > `v1.6.0+`

package/dist/ai/docs/nocobase/index.md

@@ -28,7 +28,7 @@ features:
         link: /ai/install-nocobase-app
       - title: Tutorials
         details: Step-by-step tutorials to build real projects with NocoBase from scratch.
-        link: /tutorials/v2/
+        link: /tutorials/
 
   - title: AI
     details: An AI-powered new way to get started - use natural language to build, use, and develop.

package/dist/ai/docs/nocobase/interface-builder/index.md

@@ -16,12 +16,9 @@ Edit mode:
 ![20251023215951](https://static-docs.nocobase.com/20251023215951.png)
 
 
-## Layout Template
+## UI Layout
 
-NocoBase ships with a default layout template: navigation on the top and left, and a content area on the right.
-
-
-![未命名.002](https://static-docs.nocobase.com/未命名.002.jpeg)
+NocoBase provides desktop and mobile layouts. The desktop layout works well for standard administration and adapts its navigation and page content on phones. The mobile layout provides separate mobile navigation and page configuration. See [UI Layout](./ui-layout/index.md) for details.
 
 
 ## Configuration Options
@@ -55,4 +52,8 @@ Action configuration options:
 Table column configuration options:
 
 
-![20251023221814](https://static-docs.nocobase.com/20251023221814.png)
+![20251023221814](https://static-docs.nocobase.com/20251023221814.png)
+
+## Related links
+
+- [UI Layout](./ui-layout/index.md) — Learn about desktop and mobile layouts

package/dist/ai/docs/nocobase/interface-builder/ui-layout/desktop.md

@@ -0,0 +1,97 @@
+---
+title: "Desktop Layout"
+description: "Learn about the navigation structure, page building, route management, and narrow-screen responsive behavior of the NocoBase desktop layout."
+keywords: "desktop layout,UI layout,narrow-screen responsive,page building,route management,UI Editor,NocoBase"
+---
+
+# Desktop Layout
+
+In NocoBase, the **desktop layout** is the default application interface. It is designed for data management, form entry, business configuration, and everyday work on a computer, and can also be used on mobile devices.
+
+The desktop layout is available at `/admin` by default. If the application has its own access prefix, the actual URL automatically includes that prefix.
+
+![20260715224020](https://static-docs.nocobase.com/20260715224020.png)
+
+![20260715224603](https://static-docs.nocobase.com/20260715224603.png)
+
+## Build a page
+
+### Step 1: Open the desktop layout
+
+Visit `/admin` to open the desktop layout. After signing in, the application usually opens this layout directly.
+
+![20260715225049](https://static-docs.nocobase.com/20260715225049.png)
+
+### Step 2: Open UI Editor
+
+Click 「UI Editor」 in the upper-right corner of the page to enter UI building mode. Configuration entries then appear around menus, pages, blocks, fields, and actions.
+
+![20260715225155_rec_](https://static-docs.nocobase.com/20260715225155_rec_.gif)
+
+### Step 3: Create menus and pages
+
+You can add groups, pages, or links in the navigation area, and enable tabs for a page. After creating a page, open it and add the blocks you need.
+
+Page content is built in the same way as other interfaces: add [blocks](../blocks/index.md) first, then configure [fields](../fields/index.md) and [actions](../actions/index.md) for your business needs.
+
+![20260715225316_rec_](https://static-docs.nocobase.com/20260715225316_rec_.gif)
+
+### Step 4: Configure page content
+
+Add table, form, details, filter, or other blocks to the page, then adjust the fields, actions, and arrangement of the blocks. Each change is reflected directly on the current page.
+
+![20260715225424_rec_](https://static-docs.nocobase.com/20260715225424_rec_.gif)
+
+## Manage routes and menus
+
+When you add a page or link in the navigation area, it also appears in the [Route Manager](../../routes/index.md). Changes made in the Route Manager also update the menu.
+
+The desktop layout supports these common route types:
+
+- **Group** — Organizes multiple pages and links under the same navigation group.
+- **Page** — Opens a page where you can continue adding blocks.
+- **Link** — Opens an internal or external URL.
+- **Tab** — Organizes multiple content tabs within a page.
+
+In the Route Manager, you can add, edit, delete, show, or hide routes. It is often the more convenient place to reorganize the entire menu structure.
+
+![20260715225711_rec_](https://static-docs.nocobase.com/20260715225711_rec_.gif)
+
+## Responsive behavior on narrow screens
+
+The desktop layout can be used directly on a phone or in a narrow browser window. In narrow-screen mode, it still uses the same desktop routes and pages. It does not automatically switch to the mobile layout.
+
+### Layout changes
+
+The navigation menu collapses, and top actions move into a more compact entry. Page margins and spacing between blocks also shrink, while the content area adapts to the visible height of the mobile browser.
+
+UI Editor is not available on narrow screens. To change menus or pages, you need to return to a desktop browser and make the changes there.
+
+![20260715224603](https://static-docs.nocobase.com/20260715224603.png)
+
+### How page content adapts
+
+Common components also adjust their interactions for narrow screens, making them easier to use on a phone. For instance, multi-column blocks switch to a single column, tables allow horizontal scrolling for columns that extend beyond the screen, and pagination and action entries become more compact. Selection, date and time, filter, and subpage interactions also use forms that are easier to operate on a phone.
+
+:::tip Desktop responsiveness and the mobile layout
+
+If you only access the application from a phone occasionally, the responsive desktop layout is usually enough. If you need separate bottom navigation, mobile pages, and mobile workflows, build a [mobile layout](./mobile.md) as well.
+
+:::
+
+## Recommendations
+
+- Use the desktop layout by default for work performed mainly on a computer.
+- Finish building the page on a wide screen, then narrow the window to check its responsive behavior.
+- If a page contains many table columns or horizontal actions, keep only the necessary content to reduce the workload on smaller screens.
+- If the desktop and mobile workflows differ significantly, separate pages are usually clearer.
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Mobile layout](./mobile.md) — Build separate mobile navigation and pages
+- [Blocks](../blocks/index.md) — Add and configure blocks on a page
+- [Fields](../fields/index.md) — Configure fields in tables, forms, and details blocks
+- [Actions](../actions/index.md) — Configure actions on pages and blocks
+- [Route Manager](../../routes/index.md) — Manage desktop menus and routes in one place
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which desktop routes each role can access

package/dist/ai/docs/nocobase/interface-builder/ui-layout/index.md

@@ -0,0 +1,50 @@
+---
+title: "UI Layout"
+description: "An overview of NocoBase UI layouts, including desktop and mobile layout features, use cases, and how their configurations relate."
+keywords: "UI layout,desktop layout,mobile layout,responsive layout,mobile pages,NocoBase"
+---
+
+# UI Layout
+
+NocoBase provides desktop and mobile layouts. Both layouts support UI building, so you can create pages and configure blocks, fields, and actions within them.
+
+The desktop layout is the default choice and works well for everyday administration and data processing on a computer. If you need dedicated navigation and pages for mobile devices, you can build a mobile layout as well.
+
+## Desktop layout
+
+The [desktop layout](./desktop.md) is available at `/admin` by default. It consists of top navigation, side navigation, and a page content area, making it suitable for common business scenarios such as managing tables, entering form data, and viewing records.
+
+The desktop layout also supports responsive behavior on narrow screens. When a page is displayed on a smaller screen, the navigation, spacing, and common components adjust to fit while continuing to use the existing desktop menus and pages.
+
+![20260715224020](https://static-docs.nocobase.com/20260715224020.png)
+
+## Mobile layout
+
+The [mobile layout](./mobile.md) is available at `/mobile` by default. It uses a bottom tab bar for primary navigation and provides separate mobile pages, links, and page tabs.
+
+The mobile layout works well for frequent phone-based tasks such as on-site data entry, mobile approvals, task processing, and data lookup. You can build and preview pages in a desktop browser, then use a QR code to check the result on a physical device.
+
+![20260715230725](https://static-docs.nocobase.com/20260715230725.png)
+
+## Which layout should I use?
+
+Use the desktop layout by default.
+
+| I want to... | Recommended layout |
+| --- | --- |
+| Work mainly on a computer and occasionally access pages from a phone | [Desktop layout](./desktop.md) |
+| Design separate navigation, pages, and workflows for phones | [Mobile layout](./mobile.md) |
+| Provide a complete experience for both computers and mobile devices | Build the desktop and mobile layouts separately |
+
+## How the configurations relate
+
+The desktop and mobile layouts use the same data sources and business data. You can use the same data table to build separate pages for different devices.
+
+Menus, routes, and page configurations are maintained separately. Changes to a desktop page do not automatically update its mobile counterpart, and changes to mobile navigation do not affect desktop navigation. [Route access permissions](../../users-permissions/acl/permissions.md) also need to be configured separately for each layout.
+
+## Related links
+
+- [Desktop layout](./desktop.md) — Build desktop pages and learn how they behave on narrow screens
+- [Mobile layout](./mobile.md) — Build separate mobile navigation and pages
+- [Route Manager](../../routes/index.md) — Manage desktop and mobile pages, links, and menus
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which menus and pages each role can access

package/dist/ai/docs/nocobase/interface-builder/ui-layout/mobile.md

@@ -0,0 +1,133 @@
+---
+title: "Mobile Layout"
+description: "Learn about NocoBase mobile navigation, page building, desktop preview, subpage interactions, routes, and permissions."
+keywords: "mobile layout,mobile pages,bottom navigation,mobile preview,mobile routes,UI Editor,NocoBase"
+---
+
+# Mobile Layout
+
+In NocoBase, the **mobile layout** is used to build dedicated navigation and pages for mobile devices. It is available at `/mobile` by default and uses a bottom tab bar as its primary navigation, making it more suitable for data entry, lookup, approval, and task processing on a phone.
+
+The mobile and desktop layouts use the same data sources and business data, but their menus, routes, and page content are configured separately. This lets you reorganize pages around mobile workflows without being constrained by the desktop page structure.
+
+<!-- Add a full-page screenshot of the mobile layout on a physical device -->
+
+## Open and preview the mobile layout
+
+By default, you can click 「Mobile」 in Settings to open the layout, or visit `/mobile` directly.
+
+It is best to build pages in a desktop browser. The desktop view provides a mobile preview area and a toolbar at the top:
+
+- 「UI Editor」 turns UI building mode on or off.
+- 「Tablet preview」 checks the display on wider mobile devices.
+- 「Mobile preview」 restores the phone-sized preview area.
+- 「QR code」 opens the current mobile URL on a phone.
+
+![20260715221712](https://static-docs.nocobase.com/20260715221712.png)
+
+After building the pages on a computer, scan the QR code and check them on a physical device. Pay particular attention to navigation, scrolling, form input, pop-up pages, and safe areas.
+
+## Build mobile navigation
+
+The mobile layout uses a bottom tab bar as its primary navigation. Primary navigation currently supports mainly pages and links.
+
+### Add a page
+
+1. Open 「UI Editor」.
+2. Click the add button on the right side of the bottom tab bar.
+3. Select 「Page」.
+4. Enter a page title and select an icon.
+5. Submit the form to open the new page, then continue adding page content.
+
+![20260715221823_rec_](https://static-docs.nocobase.com/20260715221823_rec_.gif)
+
+### Add a link
+
+To open an internal or external URL, select 「Link」 and configure its title, icon, and URL.
+
+A link can open in the current window or a new window, depending on its configuration.
+
+![20260715221950](https://static-docs.nocobase.com/20260715221950.png)
+
+### Arrange navigation
+
+In UI building mode, drag bottom tabs to reorder them. You can also edit a tab's title and icon, configure linkage rules, copy its UID, or delete it.
+
+To view, show, hide, or delete mobile routes in one place, open 「Settings / Routes / Mobile routes」.
+
+![20260715222113_rec_](https://static-docs.nocobase.com/20260715222113_rec_.gif)
+
+## Build a mobile page
+
+Create and open a mobile page before adding blocks to it. The approach to building page content is essentially the same as on desktop: use [blocks](../blocks/index.md), [fields](../fields/index.md), and [actions](../actions/index.md) to organize business content. However, mobile navigation and some component interactions are adjusted for smaller screens.
+
+### Add page content
+
+1. Open the mobile page you want to build.
+2. Make sure 「UI Editor」 is enabled.
+3. Click 「Add block」 on the page.
+4. Select a table, form, details, filter, or another block.
+5. Continue configuring fields, actions, and block settings.
+
+![20260715222230_rec_](https://static-docs.nocobase.com/20260715222230_rec_.gif)
+
+### Use page tabs
+
+A mobile page can also use tabs. If multiple pieces of content belong under the same navigation entry but remain relatively independent, place them in separate tabs.
+
+1. Open the page settings and enable 「Enable page tabs」. You can also edit the page under 「Settings / Routes / Mobile routes」 and select 「Enable page tabs」.
+2. Turn on 「UI Editor」.
+3. Click 「Add tab」 on the right side of the page tab bar.
+4. Add the tab, then configure its name and page content.
+
+If a mobile page contains only a small amount of content, use a single page. You do not need to enable tabs.
+
+![20260715222354_rec_](https://static-docs.nocobase.com/20260715222354_rec_.gif)
+
+### Mobile interactions for common components
+
+Common components adjust their arrangement and interactions for the mobile layout. For instance, multi-column content automatically switches to a single column that is easier to browse vertically; selection and date-time fields use mobile-friendly pickers; and filters, associated record selection, and subpages use interfaces designed for touch interaction.
+
+Tables remain tables on mobile, with horizontal scrolling for columns that extend beyond the screen. Any additional mobile behavior depends on the support provided by each block.
+
+## Pages and subpages
+
+Content opened from view, edit, associated record selection, and similar actions appears as a mobile subpage. The subpage provides a back button that returns you to the previous page.
+
+When you open a deeper subpage, the bottom tab bar is hidden to leave more room for the current content. It reappears when you close the subpage or return to the previous level.
+
+When switching between bottom tabs, the state of open pages is preserved, making it easier to move between mobile tasks.
+
+![20260715222828_rec_](https://static-docs.nocobase.com/20260715222828_rec_.gif)
+
+## Manage routes and permissions
+
+Mobile routes can be maintained in the [Route Manager](../../routes/index.md). Open 「Settings / Routes / Mobile routes」 to add, edit, delete, show, or hide pages and links, or to configure tabs for a page.
+
+Mobile route access permissions are configured separately from desktop permissions. Under role permissions, open 「Mobile routes」 and select the pages the current role can access. See [Permission configuration](../../users-permissions/acl/permissions.md) for details.
+
+![20260715223016_rec_](https://static-docs.nocobase.com/20260715223016_rec_.gif)
+
+![20260715223106_rec_](https://static-docs.nocobase.com/20260715223106_rec_.gif)
+
+## Relationship with the desktop layout
+
+You can build separate desktop and mobile pages from the same data table. For instance, a desktop page may use a table with many fields for data processing, while a mobile page may use a simpler list or form for on-site data entry.
+
+The two layouts do not synchronize pages automatically. Changes to desktop pages, menus, or routes do not update the mobile configuration, and mobile changes do not affect desktop pages.
+
+:::tip Recommendation
+
+If mobile users only need occasional access to desktop pages, try the responsive [desktop layout](./desktop.md) first. Build a separate mobile layout only when you need dedicated navigation and page workflows for mobile devices.
+
+:::
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Desktop layout](./desktop.md) — Use the default desktop layout and its narrow-screen responsiveness
+- [Blocks](../blocks/index.md) — Add business content to mobile pages
+- [Fields](../fields/index.md) — Configure mobile forms and data display fields
+- [Actions](../actions/index.md) — Configure actions on mobile pages
+- [Route Manager](../../routes/index.md) — Manage mobile pages, links, and tabs
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which mobile routes each role can access