لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/pages/block-styles.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Update block styles

PATCH /v1/pages/:pageId/blocks/:blockId/styles

Changes the CSS classes and inline styles of block nodes on a site page. Nodes are selected by selectors from the block manifest; a single call can change several nodes.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
ParameterblockId (path) Typenumber Requiredyes DescriptionID of a block on this page. List: GET /v1/pages/:pageId/blocks
Parameterscope (query) Typestring Requiredno DescriptionSite area: KNOWLEDGE — knowledge base, GROUP — workgroup pages, MAINPAGE — home pages. Omit the parameter for pages of all other sites

Request fields (body)

Field Type Required Description
Fieldstyles Typeobject Requiredyes DescriptionAn object of the form "selector → changes". Must not be empty. The body has no other fields
Fieldstyles.<selector> Typeobject Requiredyes DescriptionThe key is a node selector .class or .class@N, where N is a zero-based index among the nodes with that class. Without @N, the change applies to all nodes with that class. Valid selectors are the keys of style.nodes in the response of GET /v1/pages/:pageId/blocks/:blockId/content. The value is an object with a classList field, a style field, or both
Fieldstyles.<selector>.classList Typestring[] Requiredno DescriptionThe new list of node classes. Each element is a non-empty string without spaces. If the field is omitted, the node classes do not change
Fieldstyles.<selector>.style Typeobject Requiredno DescriptionInline node styles as "property → value" pairs, for example {"color": "#ff0000"}. They are written to the node's style attribute

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/42/blocks/7/styles" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styles": {
      ".landing-block-node-title": {
        "classList": ["landing-block-node-title", "g-color-red", "g-mb-20"]
      }
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/42/blocks/7/styles" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "styles": {
      ".landing-block-node-title": {
        "classList": ["landing-block-node-title", "g-color-red", "g-mb-20"]
      }
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/42/blocks/7/styles', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    styles: {
      '.landing-block-node-title': {
        classList: ['landing-block-node-title', 'g-color-red', 'g-mb-20'],
      },
    },
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/42/blocks/7/styles', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    styles: {
      '.landing-block-node-title': {
        classList: ['landing-block-node-title', 'g-color-red', 'g-mb-20'],
      },
    },
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typenumber DescriptionBlock ID
Fielddata.pageId Typenumber DescriptionPage ID
Fielddata.anchor Typestring DescriptionBlock anchor. An automatic anchor has the form b<id>, for example b7
Fielddata.content Typestring DescriptionThe full block HTML, read back after the change
Fielddata.nodes Typeobject DescriptionEmpty object. The block state is in content
Fielddata.styles Typeobject DescriptionEmpty object. The block state is in content
Fielddata.attrs Typeobject DescriptionEmpty object. The block state is in content
Fielddata.cards Typeobject DescriptionEmpty object. The block state is in content
Fielddata.active Typeboolean DescriptionWhether the block is active

Response example

The paragraph text in content is shortened with an ellipsis; the markup is unchanged.

JSON 
{
  "success": true,
  "data": {
    "id": 7,
    "pageId": 42,
    "anchor": "b7",
    "content": "<div id=\"block7\" data-id=\"7\" class=\"block-wrapper block-27-one-col-fix-title-and-text-2\"><section class=\"landing-block js-animation g-pt-30 g-pb-30\">\r\n\t<div class=\"landing-block-node-text-container container g-max-width-container\">\r\n\t\t<h2 class=\"landing-block-node-title g-color-red g-mb-20\">Spring sale</h2>\r\n\t\t<div class=\"landing-block-node-text js-animation g-mb-20 g-pb-1 g-color\">\r\n\t\t\tSed feugiat porttitor nunc, non dignissim ipsum vestibulum in…\r\n\t\t</div>\r\n\t</div>\r\n</section></div>",
    "nodes": {},
    "styles": {},
    "attrs": {},
    "cards": {},
    "active": true
  }
}

Error response example

400 — classList contains a class with a space:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Styles accept classList string tokens and a style object"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe value for a selector is not an object with classList and style: an extra key, a class with a space or an empty string, or style is not an object
HTTP400 CodeINVALID_PARAMS DescriptionThe selector is not in the .class or .class@N format. Service keys are not accepted in place of a selector
HTTP400 CodeINVALID_PARAMS DescriptionThe selector is not among the block's style.nodes, or the @N index exceeds the number of nodes with that class. The message lists the available selectors
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than styles
HTTP400 CodeINVALID_PARAMS DescriptionpageId or blockId is not a positive integer
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body is not a JSON object, it has no styles field, or styles is an empty object
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe page does not exist, the block does not exist, or the block belongs to another page
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe change was accepted, but the block could not be read back afterwards
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is not enabled on the Bitrix24 account
HTTP409 CodePORTAL_ADDRESS_CHANGED DescriptionThe self-hosted Bitrix24 moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the block change
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. The request is refused before any call to the Bitrix24 account
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the landing scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 access tokens

Full list of common API errors — Errors.

Known specifics

  • classList replaces the node classes entirely. Classes missing from the passed list are removed from the node. In the example above, the heading with the classes landing-block-node-title js-animation fadeIn g-mb-20 g-color ended up with landing-block-node-title g-color-red g-mb-20 after the call. To add a class to the existing ones, first read the node's current classes in content and pass the full list.
  • Classes the manifest uses to address the node are preserved. If classList omits the selector class, for example landing-block-node-title, it still stays on the node. So the node is still found by the same selector in subsequent calls.
  • The set of selectors for styles is wider than for text. style.nodes includes containers that are not among the editable nodes, for example .landing-block-node-text-container. The style of such a node can be changed with this method, but its text cannot be changed via PATCH …/nodes.

See also