Cú pháp mẫu

Biến là những trình giữ chỗ trong mẫu, sẽ được thay bằng dữ liệu thực từ bản ghi Lark Base.

Cú pháp cơ bản

Dùng dấu ngoặc nhọn với tên trường chính xác:

{Field_Name}

Ví dụ:

• {Customer_Name} → “Acme Corp”
• {Invoice_Date} → “2024-01-15”
• {Total_Amount} → “1,500.00”

Mẹo

Dùng trang Biến trong tiện ích AutomaDoc để duyệt toàn bộ trường khả dụng và sao chép cú pháp chính xác chỉ với một cú nhấp.

Các loại trường được hỗ trợ

Nhóm	Loại trường	Kết quả mặc định
Văn bản	Văn bản thường, Email, trường Mã vạch	Giữ nguyên
Số	Số, Tiền tệ, Tiến độ (%), Đánh giá	Định dạng của Lark (ví dụ $1,234.56)
Ngày/Giờ	Ngày, Thời gian tạo, Thời gian sửa	Định dạng của Lark (theo múi giờ đã đặt)
Lựa chọn	Chọn một, Chọn nhiều	Văn bản / phân tách bằng dấu phẩy
Người	User, Created By, Modified By, Group	Tên hiển thị
Liên hệ	Điện thoại, URL	Số điện thoại / URL
Hộp kiểm	Giá trị Có/Không	true / false
Tệp đính kèm	Tệp và hình ảnh	Xem hình ảnh động
Bản ghi liên kết	Truy cập dữ liệu từ bảng liên quan	Xem bản ghi liên kết
Lookup	Giá trị lấy từ bản ghi liên kết	Giá trị đã phân giải
Công thức	Trường tính toán (văn bản, số, ngày)	Tùy theo kiểu kết quả

Bản ghi liên kết (trường lồng nhau)

Truy cập trường của bản ghi liên kết bằng cú pháp dấu chấm:

{Customer.Name}
{Customer.Address}
{Customer.Email}

Hỗ trợ lồng tối đa 5 cấp:

{Order.Customer.Company.Address.City}

Thuộc tính mở rộng của trường (cú pháp dấu chấm)

Một số loại trường cung cấp thuộc tính con qua cú pháp dấu chấm. Nếu không dùng dấu chấm, chúng hiển thị giá trị mặc định.

Trường URL

{Website}          → "https://example.com" (địa chỉ liên kết)
{Website.text}     → "Example Site" (văn bản liên kết)
{Website.link}     → "https://example.com" (địa chỉ liên kết)

User / Created By / Modified By

Created By và Modified By chỉ chứa một người nên dùng cú pháp dấu chấm được. Trường User luôn là một danh sách — kể cả khi chỉ có một người — nên {Assignee.name} không trả về gì. Hãy dùng chỉ số hoặc vòng lặp:

{Created_By}            → "John Doe"
{Created_By.name}       → "John Doe"
{Created_By.en_name}    → "John Doe" (tên tiếng Anh)
{Created_By.id}         → "ou_abc123"

{Assignee}              → "John Doe, Jane Roe"
{Assignee[0].name}      → "John Doe"
{Assignee[0].en_name}   → "John Doe" (tên tiếng Anh)
{Assignee[0].id}        → "ou_abc123" (ID người dùng Lark)

Với trường nhiều người, hãy dùng vòng lặp:

{#Assignee}
  {name} ({en_name})
{/Assignee}

Trường vị trí

{Office}                → "Headquarters, 123 Main St, City"
{Office.name}           → "Headquarters"
{Office.full_address}   → "123 Main St, City, Country"
{Office.address}        → "123 Main St"

Trường nhóm

Trường nhóm cũng là danh sách nên {Team.name} không trả về gì. Hãy dùng chỉ số hoặc vòng lặp:

{Team}          → "Engineering, Design" (tên nhóm phân tách bằng dấu phẩy)
{Team[0].name}     → tên nhóm đầu tiên
{Team[0].id}       → ID nhóm đầu tiên

Để lấy toàn bộ nhóm, hãy dùng vòng lặp:

{#Team}
  {name} (ID: {id})
{/Team}

Chọn nhiều

Trường chọn nhiều có thể lặp qua, hoặc nối lại bằng dấu phân tách tùy chọn:

{Tags}                  → "Red, Blue, Green" (mặc định phân tách bằng dấu phẩy)
{Tags | join:" / "}     → "Red / Blue / Green"
{#Tags}
  - {.}
{/Tags}

Trường số và ngày (bộ lọc ghi đè định dạng)

Trường số và ngày/giờ hiển thị theo định dạng mặc định của Lark. Khi áp dụng bộ lọc, AutomaDoc dùng giá trị gốc (số thực hoặc mốc thời gian) và ghi đè hoàn toàn định dạng của Lark:

{Price}                 → "$1,234.50" (định dạng Lark)
{Price | number:2}      → "1,234.50" (số gốc, định dạng lại)
{Price | currency:"EUR":"de-DE"} → "1.234,50 €" (số gốc, locale Đức)

{Date}                  → "2026/02/26" (định dạng Lark)
{Date | date:"DD MMM YYYY"}     → "26 Feb 2026" (mốc thời gian gốc, định dạng lại)

Trường không có bộ lọc luôn giữ định dạng gốc của Lark.

Vòng lặp (trường liên kết nhiều bản ghi)

Với trường liên kết tới nhiều bản ghi, dùng cú pháp vòng lặp để lặp lại nội dung cho từng mục:

{#Line_Items}
  Product: {Product_Name}
  Quantity: {Quantity}
  Price: {Price}
{/Line_Items}

{#Field} mở vòng lặp, {/Field} đóng lại. Bên trong vòng lặp, viết tên trường mà không cần tiền tố của trường cha.

Thẻ đóng rút gọn

Bạn có thể dùng {/} thay vì viết lại tên trường:

{#Line_Items}
  {Product_Name} - {Price}
{/}

Mở rộng hàng bảng

Khi thẻ vòng lặp được đặt trong một hàng của bảng, toàn bộ hàng sẽ được nhân bản cho mỗi mục — rất hợp cho bảng chi tiết.

Product	Qty	Price
{#Line_Items} {Product_Name}	{Quantity}	{Price} {/Line_Items}

Mảng giá trị đơn giản

Với mảng chứa giá trị đơn giản (không phải đối tượng), dùng {.} để tham chiếu mục hiện tại:

{#Tags}
  {.}
{/Tags}

Siêu dữ liệu vòng lặp

Bên trong bất kỳ vòng lặp nào, các biến đặc biệt sau đều khả dụng:

Biến	Mô tả	Ví dụ
{$index}	Chỉ số hiện tại (bắt đầu từ 0)	0, 1, 2, …
{$num}	Số thứ tự hàng (bắt đầu từ 1)	1, 2, 3, …
{$first}	true ở mục đầu tiên	In ra true / false
{$last}	true ở mục cuối cùng	In ra true / false

Chú ý

Biến vòng lặp in ra giá trị của nó nhưng không dùng được trong điều kiện — {#if $num} và {#if $first} không được nhận diện và sẽ xuất hiện nguyên văn trong tài liệu. {#if …} chỉ chấp nhận tên trường.

Vòng lặp lồng nhau

Vòng lặp có thể lồng nhau. Vòng lặp bên trong vẫn truy cập được trường ở phạm vi bên ngoài:

{#Departments}
  Department: {Name}
  {#Employees}
    {Name} works in {Department.Name}
  {/Employees}
{/Departments}

Nếu một tên trường tồn tại ở cả phạm vi trong và ngoài, phạm vi bên trong được ưu tiên.

Nội dung có điều kiện

Hiển thị hoặc ẩn nội dung dựa trên giá trị của trường.

Kiểm tra có giá trị

Chỉ hiển thị nội dung khi trường có dữ liệu:

{#if Discount}
  Discount applied: {Discount}
{/if}

Kiểm tra rỗng (phủ định)

Chỉ hiển thị nội dung khi trường rỗng:

{#if !Notes}
  No additional notes.
{/if}

So sánh bằng

{#if Status == "Approved"}
  This invoice has been approved.
{/if}

So sánh khác

{#if Status != "Draft"}
  This document has been submitted.
{/if}

Bộ lọc

Bộ lọc thay đổi cách hiển thị giá trị, dùng cú pháp dấu gạch đứng (|):

{Field | filterName}
{Field | filterName:"arg1":"arg2"}

Bộ lọc được áp dụng sau khi lấy giá trị và trước khi chèn vào tài liệu. Nếu không dùng bộ lọc, giá trị hiển thị theo định dạng mặc định của Lark.

Bộ lọc chuỗi

Bộ lọc	Mô tả	Ví dụ	Kết quả
upper	Viết hoa toàn bộ	{Name | upper}	ACME CORP
lower	Viết thường toàn bộ	{Name | lower}	acme corp
capitalize	Viết hoa chữ cái đầu mỗi từ	{Name | capitalize}	Acme Corp
trim	Bỏ khoảng trắng đầu/cuối	{Name | trim}	Acme Corp
truncate	Cắt bớt theo độ dài (mặc định 50)	{Description | truncate:16}	Lorem ipsum dolo...
pad	Đệm bằng ký tự (mặc định 0)	{$num | pad:3}	001

Bộ lọc số

Mọi bộ lọc số đều nhận thêm tham số locale tùy chọn để định dạng theo khu vực:

Bộ lọc	Tham số	Ví dụ	Kết quả
number	số thập phân, locale	{Price | number:2}	1,234.50
number	số thập phân, locale	{Price | number:2:"de-DE"}	1.234,50
currency	mã tiền tệ, locale	{Price | currency:"USD"}	$1,234.50
currency	mã tiền tệ, locale	{Price | currency:"EUR":"de-DE"}	1.234,50 €
currency	mã tiền tệ, locale	{Price | currency:"JPY":"ja-JP"}	￥1,235
percent	số thập phân, locale	{Rate | percent:1}	45.6%
percent	số thập phân, locale	{Rate | percent:1:"de-DE"}	45,6 %

Ghi chú

Bộ lọc số và ngày dùng giá trị gốc từ Lark, không phải chuỗi đã định dạng sẵn. Nhờ vậy bạn có thể định dạng lại số và ngày tùy ý, bất kể Lark hiển thị thế nào.

Bộ lọc ngày

Định dạng ngày theo mẫu riêng — hữu ích khi định dạng sẵn có của Lark không phù hợp.

Cú pháp: {Field | date:"format":"timezone":"locale"}

Mọi tham số đều tùy chọn. Múi giờ mặc định là UTC, locale mặc định là en-US.

Bộ lọc	Tham số	Ví dụ	Kết quả
date	định dạng, múi giờ, locale	{Date | date:"DD MMM YYYY"}	26 Feb 2026
date	định dạng, múi giờ, locale	{Date | date:"dddd, DD MMMM YYYY"}	Thursday, 26 February 2026
date	định dạng, múi giờ, locale	{Date | date:"DD MMMM YYYY":"UTC":"fr-FR"}	26 février 2026
date	định dạng, múi giờ, locale	{Date | date:"dddd, DD MMMM YYYY":"UTC":"de-DE"}	Donnerstag, 26 Februar 2026

Các ký hiệu ngày được hỗ trợ:

Ký hiệu	Kết quả	Ví dụ
YYYY	Năm 4 chữ số	2026
MMMM	Tên tháng đầy đủ (theo locale)	February, février, Februar
MMM	Tên tháng viết tắt (theo locale)	Feb, fév, Feb
MM	Tháng 2 chữ số	02
dddd	Tên thứ đầy đủ (theo locale)	Thursday, Donnerstag, 木曜日
ddd	Tên thứ viết tắt (theo locale)	Thu, Do, 木
DD	Ngày 2 chữ số	26
HH	Giờ định dạng 24h	15
mm	Phút	30
ss	Giây	00

Ví dụ:

{Invoice_Date | date:"DD MMM YYYY"}                         → 26 Feb 2026
{Invoice_Date | date:"YYYY-MM-DD"}                          → 2026-02-26
{Invoice_Date | date:"MM/DD/YYYY"}                          → 02/26/2026
{Invoice_Date | date:"DD/MM/YYYY":"Asia/Tokyo"}             → 26/02/2026 (múi giờ Tokyo)
{Invoice_Date | date:"dddd, DD MMMM YYYY":"UTC":"ja-JP"}    → 木曜日, 26 2月 2026
{Invoice_Date | date:"DD MMMM YYYY":"UTC":"id-ID"}          → 26 Februari 2026

Bộ lọc khác

Bộ lọc	Mô tả	Ví dụ	Kết quả
join	Nối các giá trị mảng (mặc định , )	{Tags | join:" / "}	Red / Blue / Green
default	Giá trị thay thế khi rỗng	{Phone | default:"N/A"}	N/A

Nối chuỗi bộ lọc

Có thể nối nhiều bộ lọc bằng dấu gạch đứng, áp dụng từ trái sang phải:

{Name | trim | upper}             → "  hello  " thành "HELLO"
{$num | pad:3}                    → 1 thành "001"
{Phone | default:"N/A" | upper}   → null thành "N/A"

Bộ lọc trong vòng lặp

Bộ lọc cũng dùng được với biến vòng lặp và tham chiếu mục hiện tại:

{#Items}
  #{$num | pad:3} - {Name | upper}
{/Items}

{#Tags}{. | capitalize}, {/Tags}

Hình ảnh động

Thay ảnh giữ chỗ bằng ảnh thật từ trường tệp đính kèm của Lark:

1. Chèn một ảnh bất kỳ vào mẫu Word (đây là ảnh giữ chỗ).
2. Nhấp chuột phải vào ảnh → Edit Alt Text.
3. Trong phần mô tả Alt Text, nhập {FieldName}.
4. Lưu mẫu lại.

Ảnh giữ chỗ sẽ được thay bằng ảnh thật từ trường tệp đính kèm, giữ nguyên kích thước của ảnh giữ chỗ.

Ghi chú

Alt text có thể chứa thêm văn bản khác bên cạnh trình giữ chỗ, ví dụ Company Logo {Logo}.

Nhiều ảnh

Với trường có nhiều tệp đính kèm, dùng cú pháp chỉ số:

{Photo}      → Ảnh đầu tiên (giống {Photo[0]})
{Photo[1]}   → Ảnh thứ hai
{Photo[2]}   → Ảnh thứ ba

Lặp qua toàn bộ ảnh

Với trường có số lượng tệp đính kèm thay đổi, dùng cú pháp vòng lặp với {.} làm alt text. Mỗi tệp đính kèm sẽ nhân ra một bản sao của ảnh giữ chỗ:

{#Product_Photos}
  [ảnh có alt text: {.}]
{/Product_Photos}

Trong bảng, mỗi tệp đính kèm chiếm một hàng riêng:

#	Photo	Filename
{#Product_Photos} {$num}	alt ảnh: {.}	{name} {/Product_Photos}

Các thuộc tính khả dụng bên trong vòng lặp:

Biến	Mô tả	Ví dụ
{name}	Tên tệp	photo1.jpg
{type}	Kiểu MIME	image/jpeg
{size}	Dung lượng tệp (byte)	204800

Ghi chú

Cú pháp chỉ số cố định ({Photo[0]}, {Photo[1]}) vẫn dùng được cho bố cục biết trước số lượng ảnh.

Ảnh trong vòng lặp bản ghi liên kết

Trình giữ chỗ ảnh cũng hoạt động bên trong vòng lặp. Mỗi vòng lặp sẽ lấy đúng ảnh của mục đó:

{#Employees}
  Name: {Name}
  Photo: [ảnh có alt text: {Photo}]
{/Employees}

Mã QR và mã vạch

Tạo mã QR và mã vạch từ giá trị của trường. Cách thiết lập giống hình ảnh động — thông qua Alt Text của ảnh.

Mã QR

{QR:FieldName}

Ví dụ: {QR:Order_ID} tạo mã QR chứa giá trị của Order_ID.

Mã vạch

Cú pháp	Loại	Ghi chú
{BARCODE:FieldName}	Code128	Mặc định, chữ và số
{BARCODE128:FieldName}	Code128	Chỉ định rõ Code128
{BARCODE39:FieldName}	Code39	Chỉ chữ hoa và chữ số
{BARCODEEAN13:FieldName}	EAN-13	Mã sản phẩm bán lẻ 13 chữ số
{BARCODEEAN8:FieldName}	EAN-8	EAN rút gọn 8 chữ số
{BARCODEUPCA:FieldName}	UPC-A	Bán lẻ Bắc Mỹ 12 chữ số
{BARCODEUPCE:FieldName}	UPC-E	UPC nén
{BARCODEITF14:FieldName}	ITF-14	Mã vận chuyển / thùng hàng
{BARCODEDATAMATRIX:FieldName}	DataMatrix	Mã 2D, mật độ cao
{BARCODEPDF417:FieldName}	PDF417	Mã 2D, tuyến tính xếp chồng

Tiền tố không phân biệt hoa thường — {qr:Field} và {QR:Field} đều hoạt động.

Đầu trang và chân trang

Toàn bộ cú pháp trình giữ chỗ cũng hoạt động ở đầu trang và chân trang, giống như trong phần thân tài liệu.

Các cách dùng phổ biến:

• Tên công ty hoặc logo ở đầu trang
• Số hiệu tài liệu hoặc ngày tháng ở chân trang
• Nhãn động như Invoice for {Customer_Name}

Cách thêm: Insert → Header/Footer → Edit → nhập trình giữ chỗ như {Field_Name}.

Tra cứu nhanh

Cú pháp	Mô tả
{Field}	Biến đơn giản
{Field.Nested}	Trường của bản ghi liên kết (cú pháp dấu chấm)
{URL.text} / {URL.link}	Thuộc tính con của URL
{Created_By.name} / {Assignee[0].name}	Thuộc tính con của người dùng
{Location.name} / {Location.full_address}	Thuộc tính con của vị trí
{Team[0].name} / {Team[0].id}	Thuộc tính con của nhóm
{#Field}...{/Field}	Lặp qua trường nhiều giá trị
{/}	Thẻ đóng rút gọn (đóng vòng lặp gần nhất)
{.}	Mục hiện tại trong vòng lặp (mảng đơn giản)
{$index}	Chỉ số vòng lặp (từ 0)
{$num}	Số thứ tự hàng (từ 1)
{$first} / {$last}	Boolean mục đầu/cuối
{#if Field}...{/if}	Điều kiện (có giá trị)
{#if !Field}...{/if}	Điều kiện (rỗng)
{#if Field == "val"}...{/if}	Điều kiện (bằng)
{#if Field != "val"}...{/if}	Điều kiện (khác)
{Field | upper}	Bộ lọc: viết hoa
{Field | lower}	Bộ lọc: viết thường
{Field | capitalize}	Bộ lọc: hoa chữ cái đầu mỗi từ
{Field | trim}	Bộ lọc: bỏ khoảng trắng
{Field | truncate:30}	Bộ lọc: cắt bớt kèm dấu ba chấm
{Field | pad:3}	Bộ lọc: đệm số 0
{Field | number:2}	Bộ lọc: số với phần thập phân
{Field | number:2:"de-DE"}	Bộ lọc: số theo locale
{Field | currency:"USD"}	Bộ lọc: định dạng tiền tệ
{Field | currency:"EUR":"de-DE"}	Bộ lọc: tiền tệ theo locale
{Field | percent:1}	Bộ lọc: phần trăm
{Field | date:"DD MMM YYYY"}	Bộ lọc: định dạng ngày tùy chỉnh
{Field | date:"dddd, MMMM DD":"UTC":"fr-FR"}	Bộ lọc: ngày theo locale
{Field | join:" / "}	Bộ lọc: nối mảng bằng dấu phân tách
{Field | default:"N/A"}	Bộ lọc: giá trị thay thế
{Field | trim | upper}	Nối bộ lọc (trái sang phải)
{Photo} / {Photo[1]}	Hình ảnh (qua Alt Text)
{QR:Field}	Mã QR (qua Alt Text)
{BARCODE:Field}	Mã vạch (qua Alt Text)