bitrix-cms-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CMS Basics

CMS基础

Baseline: main 23.0+. Features newer than baseline are marked Since.

Site management layer above the framework — sites, templates, menus, content areas. Landing sites / Sites24: skill

bitrix-landing

基准版本：main 23.0+。晚于基准版本的功能会标记为Since。

位于框架之上的站点管理层——站点、模板、菜单、内容区域。落地页/站点24：技能

bitrix-landing

。

Sites (Multisite)

站点（多站点）

ORM tablet:

\Bitrix\Main\SiteTable

→ table

b_lang

(

main/lib/SiteTable.php

). Legacy:

CSite

Key fields:

LID

(primary, e.g.

s1

NAME

DIR

DOC_ROOT

SERVER_NAME

SITE_NAME

LANGUAGE_ID

CULTURE_ID

ACTIVE

DEF

php

$site = \Bitrix\Main\SiteTable::getRow([
    'filter' => ['=LID' => SITE_ID],
    'select' => ['LID', 'DIR', 'SERVER_NAME', 'DOC_ROOT', 'LANGUAGE_ID'],
]);

$docRoot = \Bitrix\Main\SiteTable::getDocumentRoot(SITE_ID);

SITE_ID

SITE_DIR

are available after kernel init. Resolve site by host/path:

SiteTable::getByDomain($host, $directory)

ORM表：

\Bitrix\Main\SiteTable

→ 数据库表

b_lang

（文件路径

main/lib/SiteTable.php

）。旧版用法：

CSite

。

关键字段：

LID

（主键，例如

s1

）、

NAME

、

DIR

、

DOC_ROOT

、

SERVER_NAME

、

SITE_NAME

、

LANGUAGE_ID

、

CULTURE_ID

、

ACTIVE

、

DEF

。

php

$site = \Bitrix\Main\SiteTable::getRow([
    'filter' => ['=LID' => SITE_ID],
    'select' => ['LID', 'DIR', 'SERVER_NAME', 'DOC_ROOT', 'LANGUAGE_ID'],
]);

$docRoot = \Bitrix\Main\SiteTable::getDocumentRoot(SITE_ID);

SITE_ID

SITE_DIR

在内核初始化后可用。通过主机/路径解析站点：

SiteTable::getByDomain($host, $directory)

。

Site Templates

站点模板

Location:

/local/templates/<template_id>/

/local/templates/mytemplate/
├── header.php
├── footer.php
├── description.php       # Template meta ($arTemplate), incl. EDITOR_STYLES
├── styles.css            # Content styles — also loaded by the visual editor
├── template_styles.css   # Template frame styles (header/footer/grid)
├── .styles.php           # Visual editor style list entries
├── components/           # Template-level component overrides
├── page_templates/       # Page layout templates
└── lang/

#WORK_AREA#
— required placeholder in the site template (often a single-file template or between

header.php

footer.php

flow). The kernel injects the page body at

#WORK_AREA#

. Missing marker → admin error “set the #WORK_AREA# separator”.

Template selected per site in Admin → Sites → Edit. Prefer

/local/templates/

, not

/bitrix/templates/

存放位置：

/local/templates/<template_id>/

/local/templates/mytemplate/
├── header.php
├── footer.php
├── description.php       # 模板元信息($arTemplate)，包含EDITOR_STYLES
├── styles.css            # 内容样式——也会被可视化编辑器加载
├── template_styles.css   # 模板框架样式（页眉/页脚/网格）
├── .styles.php           # 可视化编辑器样式列表条目
├── components/           # 模板级别的组件重写
├── page_templates/       # 页面布局模板
└── lang/

#WORK_AREA#
——站点模板中必填的占位符（通常是单文件模板或位于

header.php

footer.php

流程之间）。内核会在

#WORK_AREA#

处注入页面主体内容。缺少该标记会导致管理端错误“设置#WORK_AREA#分隔符”。

每个站点的模板可在管理端→站点→编辑中选择。优先使用

/local/templates/

，而非

/bitrix/templates/

。

Styles (CSS)

样式（CSS）

Store CSS next to the owner of the markup:

Owner of markup	Where CSS lives
Site frame ( `header.php` / `footer.php` , grid, background)	`template_styles.css` of the site template
Page content that must be styleable in the visual editor	`styles.css` + `.styles.php` of the site template
Component template markup ( `template.php` )	`style.css` next to the component template
JS-extension UI loaded via `Extension::load()`	CSS inside the extension ( `config.php` `css` key) — skill `bitrix-extensions`
One-off page CSS	`Asset::getInstance()->addCss()` / classic `SetAdditionalCSS()`

styles.css
vs
template_styles.css
: the visual editor renders content in an iframe and injects

styles.css

into its

<head>

— never put site-frame rules there, or they distort the editor; keep them in

template_styles.css

. Both files are editable in Admin → Settings → Product settings → Sites → Site templates (tabs "Site styles" / "Template styles").

Visual editor style list —

.styles.php

in the template returns entries (CSS rule itself goes to

styles.css

php

return [
    'example' => [                     // array key = CSS class name
        'tag' => 'p',                  // tag(s) the style applies to; comma-separated list allowed
        'title' => 'Test style',       // name shown in the editor
        'html' => '<span style="...">Preview</span>', // optional styled preview
        // optional 'section' => groups entries in the editor's style dropdown
    ],
];

Editor-only CSS files —

EDITOR_STYLES

in the template's

description.php

(

$arTemplate

'EDITOR_STYLES' => ['/bitrix/css/main/bootstrap.css', ...]

. Loaded only in the visual editor; include them separately for the public site if needed.

Include APIs:

php

$APPLICATION->ShowCSS();          // classic, in header.php <head>: outputs page + template CSS set
$APPLICATION->SetAdditionalCSS('/local/templates/demo/additional.css'); // classic add to that set

\Bitrix\Main\Page\Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . '/styles/page.css');
// 2nd param $additional=true → file goes to the template set, after styles.css / template_styles.css

\Bitrix\Main\UI\Extension::load('demo.product-card'); // extension JS+CSS from its config.php

Prefer

Asset::addCss()

(D7) or

Extension::load()

for new code;

ShowCSS()

SetAdditionalCSS()

belong to classic site templates.

Optimization (Admin → Settings → Product settings → Module settings → Main module): merge CSS files (

main

option

optimize_css_files

), use existing

.min

versions, gzip copies (

compres_css_js_files

, requires zlib). Merge applies only to Asset-registered CSS, is skipped in the admin section and Ajax mode, and can be disabled via

disableOptimizeCss()

. Merged files live in

/bitrix/cache/css/<SITE_ID>/<template>/

(kernel /

template_<hash>

page_<hash>

sets) — after editing CSS clear the Bitrix cache (and browser cache) if the old look persists.

将CSS与标记的所属方放在一起：

标记所属方	CSS存放位置
站点框架（ `header.php` / `footer.php` 、网格、背景）	站点模板的 `template_styles.css`
必须在可视化编辑器中可设置样式的页面内容	站点模板的 `styles.css` + `.styles.php`
组件模板标记（ `template.php` ）	组件模板旁的 `style.css`
通过 `Extension::load()` 加载的JS扩展UI	扩展内的CSS（ `config.php` 的 `css` 键）——技能 `bitrix-extensions`
一次性页面CSS	`Asset::getInstance()->addCss()` / 传统方法 `SetAdditionalCSS()`

styles.css
与
template_styles.css
的区别：可视化编辑器在iframe中渲染内容，并将

styles.css

注入其

<head>

——切勿在其中放置站点框架规则，否则会扭曲编辑器显示；应将这些规则放在

template_styles.css

中。这两个文件都可在管理端→设置→产品设置→站点→站点模板（“站点样式”/“模板样式”标签页）中编辑。

可视化编辑器样式列表——模板中的

.styles.php

返回条目（CSS规则本身需写入

styles.css

）：

php

return [
    'example' => [                     // 数组键 = CSS类名
        'tag' => 'p',                  // 样式适用的标签；允许多个标签用逗号分隔
        'title' => 'Test style',       // 编辑器中显示的名称
        'html' => '<span style="...">Preview</span>', // 可选的样式预览
        // 可选'section' => 在编辑器的样式下拉菜单中对条目进行分组
    ],
];

仅编辑器可用的CSS文件——模板

description.php

（

$arTemplate

）中的

EDITOR_STYLES

：

'EDITOR_STYLES' => ['/bitrix/css/main/bootstrap.css', ...]

。仅在可视化编辑器中加载；如果需要在公开站点使用，需单独引入。

引入API：

php

$APPLICATION->ShowCSS();          // 传统方法，在header.php的<head>中：输出页面+模板的CSS集合
$APPLICATION->SetAdditionalCSS('/local/templates/demo/additional.css'); // 传统方法，添加到该集合中

\Bitrix\Main\Page\Asset::getInstance()->addCss(SITE_TEMPLATE_PATH . '/styles/page.css');
// 第二个参数$additional=true → 文件会被加入模板集合，位于styles.css / template_styles.css之后

\Bitrix\Main\UI\Extension::load('demo.product-card'); // 从扩展的config.php加载扩展的JS+CSS

新代码优先使用

Asset::addCss()

（D7）或

Extension::load()

；

ShowCSS()

SetAdditionalCSS()

属于传统站点模板用法。

优化（管理端→设置→产品设置→模块设置→主模块）：合并CSS文件（

main

模块的

optimize_css_files

选项），使用已有的

.min

版本，启用gzip压缩（

compres_css_js_files

，需要zlib支持）。合并仅对通过Asset注册的CSS生效，在管理端和Ajax模式下会被跳过，也可通过

disableOptimizeCss()

禁用。合并后的文件存放在

/bitrix/cache/css/<SITE_ID>/<template>/

（内核/

template_<hash>

page_<hash>

集合）——编辑CSS后，如果旧样式仍然存在，需清除Bitrix缓存（以及浏览器缓存）。

Section and Access Files

区域与权限文件

.section.php

.section.php

Per-directory file (walked from current path up to site root). Typical contents:

php

<?php
$sSectionName = 'News';
$arDirProperties = [
    'TITLE' => 'News section',
    'keywords' => 'news, updates',
    'description' => 'Company news',
];

```
$sSectionName
```
— used for breadcrumbs (
```
GetNavChain
```
).

$arDirProperties

— directory properties; read via

$APPLICATION->GetDirProperty()

/ merged into

$APPLICATION->GetProperty()

每个目录下的文件（从当前路径向上遍历至站点根目录）。典型内容：

php

<?php
$sSectionName = 'News';
$arDirProperties = [
    'TITLE' => 'News section',
    'keywords' => 'news, updates',
    'description' => 'Company news',
];

```
$sSectionName
```
——用于面包屑（
```
GetNavChain
```
）。

$arDirProperties

——目录属性；可通过

$APPLICATION->GetDirProperty()

读取 / 合并到

$APPLICATION->GetProperty()

中。

.access.php

.access.php

Per-directory file permissions (

PERM[...]

). Managed by

$APPLICATION->SetFileAccessPermission()

/ admin UI. Do not hand-edit unless you know the format; kernel includes it when resolving file rights.

每个目录下的文件权限（

PERM[...]

）。通过

$APPLICATION->SetFileAccessPermission()

/ 管理端UI管理。除非了解格式，否则不要手动编辑；内核在解析文件权限时会包含该文件。

Page Properties

页面属性

php

$APPLICATION->SetPageProperty('title', 'About');
$APPLICATION->SetPageProperty('description', 'About the company');
$APPLICATION->SetPageProperty('keywords', 'about');

$title = $APPLICATION->GetPageProperty('title', 'Default');
// GetProperty: page first, then directory (.section.php), then default
$desc = $APPLICATION->GetProperty('description');

```
SetPageProperty
```
/
```
GetPageProperty
```
— current page only.

SetDirProperty

GetDirProperty

— directory props (often from

.section.php

```
GetProperty
```
— page → dir → default.

Common keys:

title

description

keywords

, plus custom uppercase IDs.

php

$APPLICATION->SetPageProperty('title', 'About');
$APPLICATION->SetPageProperty('description', 'About the company');
$APPLICATION->SetPageProperty('keywords', 'about');

$title = $APPLICATION->GetPageProperty('title', 'Default');
// GetProperty：优先读取页面属性，然后是目录属性(.section.php)，最后是默认值
$desc = $APPLICATION->GetProperty('description');

```
SetPageProperty
```
/
```
GetPageProperty
```
——仅针对当前页面。

SetDirProperty

GetDirProperty

——目录属性（通常来自

.section.php

）。

```
GetProperty
```
——页面→目录→默认值。

常用键：

title

、

description

、

keywords

，以及自定义大写ID。

Menus

菜单

Menu types per site (
```
top
```
,
```
left
```
, …).
Files:
```
/.top.menu.php
```
,
```
/.left.menu.php
```
in site root or section.
Component:
```
bitrix:menu
```
.

每个站点有不同的菜单类型（
```
top
```
、
```
left
```
等）。
文件：站点根目录或区域下的
```
/.top.menu.php
```
、
```
/.left.menu.php
```
。
组件：
```
bitrix:menu
```
。

Page Templates

页面模板

/local/templates/<id>/page_templates/

— reusable layouts for the visual editor.

/local/templates/<id>/page_templates/

——可视化编辑器的可重用布局。

Include Areas

包含区域

bitrix:main.include

— editable content blocks:

php

$APPLICATION->IncludeComponent('bitrix:main.include', '', [
    'AREA_FILE_SHOW' => 'file',
    'PATH' => '/include/phone.php',
]);

Files typically under

/include/

/local/include/

bitrix:main.include

——可编辑的内容块：

php

$APPLICATION->IncludeComponent('bitrix:main.include', '', [
    'AREA_FILE_SHOW' => 'file',
    'PATH' => '/include/phone.php',
]);

文件通常存放在

/include/

或

/local/include/

下。

Breadcrumbs

面包屑

Auto from
```
$sSectionName
```
in
```
.section.php
```
along the path.

Manual:

$APPLICATION->AddChainItem('Title', '/path/')

Component:
```
bitrix:breadcrumb
```
.

自动从路径上的
```
.section.php
```
中的
```
$sSectionName
```
生成。

手动设置：

$APPLICATION->AddChainItem('Title', '/path/')

。

组件：
```
bitrix:breadcrumb
```
。

Users and Groups

用户与组

```
CUser
```
,
```
\Bitrix\Main\UserTable
```
— users.
Groups control permissions via
```
\CMain::GetUserRight()
```
and group IDs.
User fields (UF) —
```
CUserTypeEntity
```
,
```
\Bitrix\Main\UserFieldTable
```
; register in module
```
DoInstall
```
; access via
```
USER.UF_*
```
in ORM or user fields API.

```
CUser
```
、
```
\Bitrix\Main\UserTable
```
——用户相关。
用户组通过
```
\CMain::GetUserRight()
```
和组ID控制权限。
用户字段（UF）——
```
CUserTypeEntity
```
、
```
\Bitrix\Main\UserFieldTable
```
；在模块的
```
DoInstall
```
中注册；可通过ORM中的
```
USER.UF_*
```
或用户字段API访问。

Admin Panel

管理面板

/bitrix/admin/

— admin scripts. Custom pages via module install admin files, or modern UI (

bitrix-ui

). Legacy lists:

CAdminList

CAdminForm

/bitrix/admin/

——管理脚本。可通过模块安装管理文件或现代UI（

bitrix-ui

）创建自定义页面。旧版列表：

CAdminList

CAdminForm

。

Checklist

检查清单

Site-specific code checks
```
SITE_ID
```
/
```
SITE_DIR
```
.
Template has
```
#WORK_AREA#
```
; overrides in
```
/local/templates/
```
.
Site-frame CSS in
```
template_styles.css
```
; editor-visible content CSS in
```
styles.css
```
(+
```
.styles.php
```
); component CSS in the template's
```
style.css
```
; new code uses
```
Asset::addCss()
```
/
```
Extension::load()
```
.
Section meta/breadcrumbs via
```
.section.php
```
; rights via
```
.access.php
```
/ API.
Page meta via
```
SetPageProperty
```
/
```
GetProperty
```
.
Menus via
```
.menu.php
```
or Admin UI; includes for editable fragments.
Landings / composite sites →
```
bitrix-landing
```
when applicable.

站点特定代码检查
```
SITE_ID
```
/
```
SITE_DIR
```
。
模板包含
```
#WORK_AREA#
```
；在
```
/local/templates/
```
中进行重写。
站点框架CSS放在
```
template_styles.css
```
中；编辑器可见内容的CSS放在
```
styles.css
```
（+
```
.styles.php
```
）中；组件CSS放在模板的
```
style.css
```
中；新代码使用
```
Asset::addCss()
```
/
```
Extension::load()
```
。
区域元信息/面包屑通过
```
.section.php
```
设置；权限通过
```
.access.php
```
/ API设置。
页面元信息通过
```
SetPageProperty
```
/
```
GetProperty
```
设置。
菜单通过
```
.menu.php
```
或管理端UI设置；使用包含区域处理可编辑片段。
落地页/复合站点→适用时使用
```
bitrix-landing
```
。