UDF AI + Network + Shape

Hàm cell-level gọi network: AI Gemini, HTTP GET, parse JSON, info shape, translate, OCR.

AI Functions

DvdAskGemini

Hỏi Gemini AI tại cell-level:

=DvdAskGemini("Tỷ giá USD/VND hiện tại?")
   → "Khoảng 24.500 đồng/USD (tháng 5/2026)"

=DvdAskGemini("Tóm tắt văn bản: " & A1, 100)
   → tóm tắt nội dung A1 trong tối đa 100 từ

=DvdAskGemini(A1, , "gemini-2.5-pro")
   → dùng model Pro thay vì flash mặc định

Tham số:

1. prompt — câu hỏi.
2. maxWords (tùy chọn) — giới hạn từ output.
3. model (tùy chọn) — model Gemini.
4. temperature (tùy chọn) — 0.0-1.0.

Hàm này async — trả #GETTING_DATA ngay, resolve khi Gemini phản hồi.

Cẩn thận với cell tham chiếu

Nếu cell có công thức =DvdAskGemini(A1) và A1 đổi liên tục → mỗi lần đổi sẽ gọi Gemini API mới → tốn quota.

Để tránh: dùng Ctrl+C → Paste Special → Values để chuyển công thức thành value static.

DvdExplain / DvdExplainEN

AI giải thích công thức Excel trong cell khác:

=DvdExplain(A1)

Nếu A1 = =VLOOKUP(B1, Sheet2!A:Z, MATCH(C1, Sheet2!1:1, 0), FALSE), output:

Hàm tra cứu giá trị tại B1 trong cột đầu của bảng Sheet2!A:Z, sau đó lấy giá trị cột tương ứng với header C1 (tìm trong hàng 1 của Sheet2). FALSE nghĩa là tìm chính xác.

DvdExplainEN cho English version.

Network Functions

DvdHttpGet

GET request, trả body text:

=DvdHttpGet("https://api.example.com/data")
   → "..." (text response)

=DvdHttpGet("https://api.example.com/data", "Authorization: Bearer xyz")
   → request có header

=DvdHttpGet("https://api.example.com/data", , 5)
   → timeout 5 giây

Use case:

• Lấy data từ API public (weather, exchange rate, stock price).
• Webhook trigger từ Excel.
• Health check service.

DvdParseJson

Đọc field JSON theo dotted path:

Cell A1 = '{"user":{"name":"Đặng","age":35},"items":[{"id":1},{"id":2}]}'

=DvdParseJson(A1, "user.name")        → "Đặng"
=DvdParseJson(A1, "user.age")         → 35
=DvdParseJson(A1, "items[0].id")      → 1
=DvdParseJson(A1, "items[1].id")      → 2
=DvdParseJson(A1, "items.length")     → 2

Tương đương JSONPath syntax đơn giản. Phù hợp combine với DvdHttpGet:

=DvdParseJson(DvdHttpGet("https://api.weather.com/...?q=Hanoi"), "current.temp")
   → 28.5  (nhiệt độ hiện tại Hà Nội)

DvdUrlEncode / DvdUrlDecode

URL escape:

=DvdUrlEncode("Hà Nội")              → "H%C3%A0%20N%E1%BB%99i"
=DvdUrlDecode("H%C3%A0%20N%E1%BB%99i") → "Hà Nội"

Shape Functions

DvdShapeText

Lấy text trong shape:

=DvdShapeText("Rectangle 1")        → "Click here to start"
=DvdShapeText("TextBox 5")          → "Total: 1,234,567"

Use case: dashboard có shape chứa text dynamic → cell tham chiếu shape value.

DvdShapeFillColor / DvdShapeLineColor / DvdShapeFontColor

Lấy màu shape theo hex:

=DvdShapeFillColor("Rectangle 1")    → "#FF0000"  (red)
=DvdShapeLineColor("Rectangle 1")    → "#000000"  (black)
=DvdShapeFontColor("TextBox 5")      → "#FFFFFF"  (white)

DvdShapePosition

Lấy Top / Left / Width / Height (point):

=DvdShapePosition("Rectangle 1", "Top")     → 50.25
=DvdShapePosition("Rectangle 1", "Left")    → 100.5
=DvdShapePosition("Rectangle 1", "Width")   → 200
=DvdShapePosition("Rectangle 1", "Height")  → 100

Use case: bảng vẽ mặt bằng có nhiều shape — muốn lấy vị trí và kích thước ra bảng để analyze.

Translation Functions

DvdTranslateGoogle

Google Translate qua UDF:

=DvdTranslateGoogle("Hello World", "en", "vi")    → "Xin chào thế giới"
=DvdTranslateGoogle(A1, "auto", "vi")              → auto-detect ngôn ngữ nguồn

Free — không cần API key.

DvdTranslateGemini / DvdTranslateChatGPT

Dùng AI service dịch (chính xác hơn Google cho thuật ngữ chuyên ngành):

=DvdTranslateGemini("thép chờ", "vi", "en")        → "starter bar"
=DvdTranslateChatGPT("bê tông lót", "vi", "en")    → "lean concrete"

Yêu cầu API key đã config trong Preferences.

Premium

DvdTranslateGemini và DvdTranslateChatGPT yêu cầu license. Free fallback dùng DvdTranslateGoogle.

OCR Functions

DvdOcr

OCR file ảnh → text:

=DvdOcr("D:\Images\bill.jpg")             → "..." (text trong ảnh)
=DvdOcr("D:\Images\bill.jpg", "vi")       → OCR ngôn ngữ Vietnamese

DvdOcrPdf

OCR 1 trang PDF:

=DvdOcrPdf("D:\Documents\scan.pdf", 1)     → text trang 1
=DvdOcrPdf("D:\Documents\scan.pdf", 2)     → text trang 2

Premium

DvdOcr + DvdOcrPdf yêu cầu license.

License gating

Hàm	Free	Activated/Trial
Shape functions	✓	✓
DvdHttpGet, DvdParseJson, DvdUrlEncode/Decode	✓	✓
DvdTranslateGoogle	✓	✓
DvdAskGemini, DvdExplain, DvdExplainEN	✗ (trả #LICENSE!)	✓
DvdTranslateGemini, DvdTranslateChatGPT	✗	✓
DvdOcr, DvdOcrPdf	✗	✓

Async behavior

Hàm gọi network (HTTP, AI, Translate, OCR) chạy async:

1. Cell trả #GETTING_DATA ngay.
2. Background thread gọi API.
3. Khi response về → cell update → workbook recalc.

→ Excel không bị freeze. Có thể có 100+ UDF async đồng thời.

Giới hạn concurrency:

• DvdTranslate* — SemaphoreSlim(10).
• DvdAskGemini / DvdOcr — SemaphoreSlim(10).
• DvdHttpGet — không giới hạn (user tự quản lý rate).

Performance tips

UDF cell-level dễ tốn quota AI nếu có nhiều cell tham chiếu:

• 100 cell =DvdAskGemini(...) → 100 API call.
• 1000 cell =DvdTranslateGemini(...) → 1000 API call (lâu + tốn).

Mẹo:

• Dialog thay UDF: dùng Translate dialog thay vì DvdTranslateGemini — dedupe trước khi gọi API → tiết kiệm 80%+ quota.
• Cache values: sau khi UDF resolve, Ctrl+C → Paste Special Values → cell thành static.
• Disable auto-calc trong Preferences nếu workbook quá nhiều UDF async.

Liên quan

• UDF Text — local text functions.
• UDF Date + Math — local date/math.
• UDF Range + Lookup — local range/lookup.
• Translate — dialog dịch (alternative cho UDF).
• AI Assistant — chat AI (alternative cho DvdAskGemini).